Bulk Capture
Description
Instead of capturing transactions through the DIBS administration interface or using capture.cgi it may be beneficial to be able to capture a bulk of transaction in one operation. A bulk-capture facility is available in DIBS through transferring a file with the transactions in question to the DIBS server via FTP. Once the DIBS server has processed the so-called request file, a so-called response file is made available, also trough FTP. In addition, the DIBS server emails the number of transactions processed in a bulk to the shop. The bulk facility is not a default facility in DIBS and is set up only on request, please contact the DIBS support for details.
Once the facility is set up, the request files can be uploaded to the DIBS server at any time. However, before a request file is processed, a so-called run file must also be uploaded to the DIBS server (i.e. to avoid the DIBS server to start processing request files that are not fully uploaded). This run file must have the same name as the request file, but with the extension .run. The actual time of processing the request files is decided by the DIBS server (so as to minimise the server load), but batch captures are usually processed several times a day. The response files are generally available for download once their equivalent .run file is also available in your ftp directory.
If a transaction in the batch is not immediately capturable (e.g. due to communication problems with the acquirer) the transaction is automatically saved for capture at a later time.
If a transaction is more than 2 months old, it is automatically re-authorised before capture. If the re-authorisation fails, the transaction is entirely rejected.
File Formats
The naming convention for the batch files is:
- Request files: requestddmmyy_nn.txt
- Run files: requestddmmyy_nn.run
- Response files: responseddmmyy_nn.txt
where ddmmyy is the date as in day, month and year, and nn is a serial number, which is reset every day (the first file of the day gets number 01, the second file number 02, etc). The file extentions must be lowercase. The response files may contain transaction from several request files, thus the serial numbers of request and response files are independent of each other.
The file format for a batch capture contains the transaction number, the order number, the amount and the currency, e.g.:
230861,”A7201”,10000,208
230942,”A7110”,18700,208
240013,”A7208”,99300,208
The order number is a string, therefore it needs to be enclosed in quotation marks. The amount must (as always) be given in the smallest possible unit. The currency code must adhere to the ISO4217 standard (e.g. 208 = DKK, or Danish crowner), see the section on currency codes for more information (Section 6.2 on page 48). Order number and transaction number must be identical to those given in the authorisation process.
The response file is a comma-separated file with one transaction per line, each containing the transaction number and a result code. The following codes are possible:
Code | Explaination |
0 | Accepted |
1 | Postponed |
100 | Capture rejected by acquirer |
101 | The transaction number is not found. That is, invalid or rejected authorisations, or transactions belonging to another shop. |
102 | Capture failed because the transaction was already captured. |
103 | The amount in the batch file does not correspond to the original amount in the authorisation. |
104 | Order number not identical to the order number given in the authorisation. |
105 | The currency is not identical to the one given in the authorisation. |
106 | The transaction has been cancelled manually through the DIBS administration interface. |
107 | The transaction could not be re-authorised. |
108 | The transaction could not be re-authorised, because the credit card had expired. |
109 | The transaction could not be re-authorised, because of insufficient cover. |
110 | The capture was postponed 7 days in a row. |
113 | Manual capture is necessary, please contact DIBS Support. |
Please note, that your FTP client must be set up to use the ASCII type transfer, thus the newline operator is converted correctly (i.e. \r\n vs \n).
Email format and contents
When the batch capture file has been processed an email is sent to an address, which is specified in the DIBS administration interface. The email contains the following:
- Time of initiating the batch capture
- Time when the batch capture process finished
- Number of transactions received in the batch capture file
- Number of transaction postponed from previous batch captured
- Number of successfully captured transactions
- Number of rejected transactions
- Number of postponed transactions
Note
When running any form of batch caputure, there will be a menu entry for batch-info (Payments + Batch-info), where you can find historic batch-data.
