Batch processing
Batch processing simply means that once a day you send ePay a file containing all your transactions for the past day, instead of sending the transactions one at a time. When your system is not communicating with ePay all the time, you reduce the pressure on both your own and ePay's systems.
We recommend batch processing if your company completes more than 100 transactions a day.
Please note that batch files concern the processing of transactions. Use the payment window for authorising payments.
Get started
You transmit batch files to ePay through an SFTP connection (SSH File Transfer Protocol). ePay's batch server will process the files. When transmitting files to ePay, connect to the SFTP server using the login information ePay provides.
If you want to use batch processing, please contact ePay as we need to configure your connection manually.
Files and folders
When you connect to the SFTP server, you'll see four folders, which contain all files:
- Files from the company to ePay are stored in the folder "IN"
- Files from ePay to the company are stored in the folder "OUT"
- Files containing syntax error are stored in the folder "ERROR"
- Files from the "IN" folder that have been processed are stored in the folder "ARCHIVE"
File naming
We recommend that files for ePay are named in the following format: YYYYMMDDHH (year, month, date, hour)
Files from ePay to the company are stored in the OUT folder in the following format: YYYYMMDDHH
Pending files
Transactions that for some reason were not processed are stored in the following format when ePay generates the output file: YYYYMMDDHH_pending
Files are stored as pending if:
- A transaction is set for capture in the future (the company governs this)
- The authorisation of an instant capture is set in the future
- ePay could not process the transaction
A row in this file contains the following information:
| Input | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | The operation to be performed on the transaction: 1. Capture (capture amount) 2. Credit (credit amount) 3. Delete (delete transaction) 4. Authorise subscription (authorise payment on a subscription) 5. Delete subscription | |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. If operation = 4 or 5, this field is blank. | |
| Subscriptionid | Long | The number identifying the subscription. If operation = 1, 2, or 3, this field is blank. | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. |
| Date | Date | 20130115 YYYYMMDD | The date when the operation is to be performed. If, for instance, you want to capture the payment on June 21st, 2013, the date is defined 20130621. |
Please note that you don’t need to take action on the pending file. This is simply information from ePay to the company about transactions to be processed in the future.
Failed transactions
Transactions that couldn’t be processed due to errors in ePay or the acquirer’s system are stored in the following format in the OUT folder: YYYYMMDDHH_error
Please note that an email is sent to the company and ePay's support team when such a file is generated.
A row in this file contains the following information:
| Input | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | The operation to be performed on the transaction: 1. Capture (capture amount) 2. Credit (credit amount) 3. Delete (delete transaction) 4. Authorise subscription (authorise payment on a subscription) 5. Delete subscription | |
| Merchantnumber | Integer | 7-10 cifre | Your unique merchant number. Find the number on your agreement with the acquirer. |
| Transactionid | Long | The unique number identifying the payment. It is returned at authorisation. If operation = 4 or 5, this field is blank. | |
| Subscriptionid | Long | The number identifying the subscription. If operation = 1, 2, or 3, this field is blank. | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. |
| ActionCode | String | 0-9 a-Z | The error code explaining why the transaction was declined. |
Please note that you have to take manual action on the transactions in this file. The transactions are not processed again. Normal procedure would be to resend the transactions in a new file for ePay.
File content
The files must be defined as CSV (comma separated values) in the format RFC 4180. Find a specification of the format here: http://tools.ietf.org/html/rfc4180
One operation is performed for each row.
Please notice:
- A file can contain several different operations
- The separator between each operation (row) is \r\n (0x0a 0x0d)
- The separator between each field in the row is a semicolon (;)
- Mandatory fields must be defined
- Fields that are not mandatory must be left blank if they’re not defined
Also note that rows must be dynamic. Since ePay might need to add more fields to each row, you cannot expect a fixed number of columns for each row. This must be dynamic.
The processing of files
ePay processes transactions as they are received. You choose whether you want to receive one daily output file or an output file per input file.
If you receive one output file, you can schedule the generation with us. If you receive an output file per input file, we sent each output file when all rows in the input file are processed.
Files older than 30 days are deleted from the OUT folder
Files in the IN folder are deleted when they’re processed and moved to the ARCHIVE folder. Files in the ARCHIVE folder are deleted after 30 days.
Data types
The following section describes the data that are sent between your system and ePay. For each function/service/operation you can see the input fields, which are the fields you transmit to ePay, and the output fields, which are the fields ePay returns.
You can make five operations on a file:
- Capture (capture amount)
- Credit (credit amount)
- Delete (delete transaction and release amount)
- Authorise subscription (authorise a capture on a subscription)
- Delete subscription (delete subscription)
Capture
Input
| Input | Type | Values | Description | Mandatory |
|---|---|---|---|---|
| Operation | Integer | 1 (fixed) | The operation to be performed on the transaction. | Yes |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. | Yes |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. | Yes | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. Please note that if this value is 0, the full amount is captured. | Yes |
| Group | String | Max 100 characters | The group to which the payment is associated. | No |
| CaptureDate | Date | 20130115 YYYYMMDD | If this field is not blank, the payment will be captured on the date specified. The date can be today's date + a maximum of 14 days. | No |
Output
| Output | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | 1 (fixed) | The operation performed on the transaction. |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. Please note that if the value was 0 in the input file, the full amount is displayed. |
| Epayresponse / action code | String | 0 = success | If this value is not 0, you have to find the reason for the rejection of the operation by looking up the error code in the list of error codes in your ePay administration. |
Credit
Input
| Input | Type | Values | Description | Mandatory |
|---|---|---|---|---|
| Operation | Integer | 2 (fixed) | The operation to be performed on the transaction. | Yes |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer (for instance Nets). | Yes |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. | Yes | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. Please note that if this value is 0, the full amount is credited. | Yes |
| Group | String | Max 100 characters | The group to which the payment is associated. | No |
Output
| Output | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | 2 (fixed) | The operation performed on the transaction. |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer (for instance Nets). |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. Please note that if the value in the input file was 0, the credited amount is displayed here (the full amount). |
| Epayresponse / action code | String | 0 = success | If this value is not 0, you have to find the reason for the rejection of the operation by looking up the error code in the list of error codes in your ePay administration. |
Delete
Input
| Input | Type | Values | Description | Mandatory |
|---|---|---|---|---|
| Operation | Integer | 3 (fixed) | The operation to be performed on the transaction. | Yes |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. | Yes |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. | Yes | |
| Group | String | Max 100 characters | The group to which the payment is associated. | No |
Output
| Output | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | 3 (fixed) | The operation performed on the transaction. |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. |
| Transactionid | Long | The unique number to identify the payment. It is returned at authorisation. | |
| Epayresponse / action code | String | 0 = success | If this value is not 0, you have to find the reason for the rejection of the operation by looking up the error code in the list of error codes in your ePay administration. |
Authorise subscription
Input
| Input | Type | Values | Description | Mandatory |
|---|---|---|---|---|
| Operation | Integer | 4 (fixed) | The operation to be performed on the subscription. | Yes |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. | Yes |
| Subscriptionid | Long | The number identifying the subscription. | Yes | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. Please note that the amount cannot be 0. | Yes |
| Currency | String | 208 = DKK 978 = EUR 840 = USD | The currency of the amount. | Yes |
| Instantcapture | Int | 0 = false 1 = true | If this = 1, the payment is captured immediately. The default setting is 0, meaning you have to manually capture the payment from your ePay administration, using API, or through batch files. | Yes |
| CaptureDate | Date | 20130115 YYYYMMDD | Unless this field is blank, the payment is captured on the date you define. If Instantcapture = 1, this field is ignored. The date can be today's date + a maximum of 14 days. | No |
| Group | String | Max 100 characters | The group to which the payment is associated. | No |
| Description | String | Max 1024 characters | A description of the payment. You can see the description in your ePay administration. | No |
| Addfee | Int | 0 = false 1 = true | If this field = 1, ePay will calculate the transaction fee and add it to the amount. | Yes |
| Orderid | String | A-z 0-9 | The order ID for the payment. If left blank, the transaction ID is used - otherwise date-time is used. | No |
Output
| Output | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | 4 (fixed) | The operation performed on the subscription. |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. |
| Subscriptionid | Long | The number identifying the subscription. | |
| Amount | Long | Minor units | The amount in minor units. DKK 149.99 must be specified as 14999 in the amount field. |
| Currency | String | 208 = DKK 978 = EUR 840 = USD | The currency of the amount. |
| Transactionid | Long | The transaction ID created at authorisation. If authorisation is declined, the value will be 0. | |
| Fee | Long | Minor units | If the input parameter addfee = 1, the amount will appear in this field. Please note that the output parameter amount does not include the fee. |
| Epayresponse / action code | String | 0 = success | If this value is not 0, you have to find the reason for the rejection of the operation by looking up the error code in the list of error codes in your ePay administration. |
Delete subscription
Input
| Input | Type | Values | Description | Mandatory |
|---|---|---|---|---|
| Operation | Integer | 5 (fixed) | The operation to be performed on the subscription. | Yes |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. | Yes |
| Subscriptionid | Long | The unique number to identify the subscription. | Yes | |
| Group | String | Max 100 characters | The group to which the payment is associated. | No |
Output
| Output | Type | Values | Description |
|---|---|---|---|
| Operation | Integer | 5 (fixed) | The operation performed on the subscription. |
| Merchantnumber | Integer | 7-10 digits | Your unique merchant number. Find the number on your agreement with the acquirer. |
| Subscriptionid | Long | The unique number to identify the subscription. | |
| Epayresponse / action code | String | 0 = success | If this value is not 0, you have to find the reason for the rejection of the operation by looking up the error code in the list of error codes in your ePay administration. |
Example
This is a data row for capturing a transaction with the following input fields:
| Parameter | Value |
|---|---|
| Operation | 1 |
| Merchantnumber | 12345678 |
| Transactionid | 987654321 |
| Amount | 2000 |
| Group | (blank) |
The CSV row will look like this:
1;12345678;987654321;2000;;
If the transaction is approved, the response data will be:
1;12345678;987654321;2000;0;
Testing
It’s easy to test batch processing. You can use your test merchant number to test the interface and access to ePay's SFTP server. The same SFTP account is used for testing and production.
Please notice that your test merchant number must be configured for the SFTP account. Contact ePay to set this up.