Batch operations
To perform several similar operations in a group manner, the batch-operations endpoints can be used.
This endpoint allows to send a CSV file to the server containing several operations to be executed in a batch process.
This CSV must contain a header line with the name of the fields. The second and following rows will contain all the information of the different operations. The fields within each row must be separated by a comma (,).
The batch transactions available at these endpoints are Payments and Returns, each of these transactions has its own file structure and endpoint to request.
Batch payments
To batch process a set of payments, you just need to send a CSV to the corresponding endpoint following the payments file structure described below.
Batch Payments CSV Structure
A payments CSV contains a first line with the headers of the fields to be processed, and a line with the transaction data for each payment to be made.
The CSV headers should be as follows:
AMOUNT,CARD,CUSTOMER_EXTERNAL_ID,SERVICE,ADDITIONAL,URL_POST
And the transaction lines should be populated with the following fields:
Field | Type | Required | Description |
---|---|---|---|
AMOUNT | Integer | SI | Amount to collect, in cents |
CARD | String | YES | UUID of the card that will be used to make payment |
CUSTOMER_EXTERNAL_ID | String | YES | Identifier of the user who will make the payment. Must be the same as the one used to store the card. |
SERVICE | String | YES | UUID of the service |
ADDITIONAL | String | NO | NO |
URL_POST | String | NO | URL of the merchant where the notification will be sent with the payment result |
EXTRA_DATA | String | NO | You can enter as many fields as you need following the CSV format, separating each field by ; |
The fields that can be included in the extra_data are the ones contained within the extra_data field when generating a payment order .
For Paylands to be able to read the .csv file correctly, the standard must be respected by separating the fields by ,
An example of a CSV payment file would be the following:
AMOUNT,CARD,CUSTOMER_EXTERNAL_ID,SERVICE,ADDITIONAL,URL_POST,EXTRA_DATA
111,ABCDF61C46B84F768E3E8E038F5FB11E,customer111,ACDBB424-023B-4E13-B63C-F52ADA63A9FF,additional_info_111,https://google.es/post,cof.reason:OTHER;address.city:Madrid;address.address1:Alcala street;address.country:Spain,
222,ABCDF61C46B84F768E3E8E038F5FB11E,customer111,ACDBB424-023B-4E13-B63C-F52ADA63A9FF,additional_info_222,
333,ABCDF61C46B84F768E3E8E038F5FB11E,customer111,ACDBB424-023B-4E13-B63C-F52ADA63A9FF,additional_info_333, ,address.city:Madrid;address.address1:Alcala street;address.country:Spain,
Batch refunds
To batch process a set of returns, you will need to send a CSV to the batch returns endpoint following the Returns file structure described below:
Batch refunds CSV structure
The Returns CSV file must contain a first line with the headers of the fields to be processed, and a line with the operation data for each return to be processed.
The CSV headers should be as follows:
ORDER_UUID,AMOUNT
And the lines of each transaction should be filled with the following fields:
Field | Type | Required | Description |
---|---|---|---|
ORDER_UUID | String | SI | UUID of the order to return |
AMOUNT | Integer | NO | Amount to be returned, in cents |
An example of a CSV Returns file would be as follows:
ORDER_UUID, AMOUNT
AAA94216-045C-4A8F-ABBC-E480BEAA22B4,111
3FC5B2E2-87FC-4329-B3AC-FE9DEC9EE56A,452
1F8B9B46-E125-4F01-B981-35C2358FCCF3,388
Operations response
The response from these endpoints will keep the same format as the rest of the endpoints. In addition, the field "errors" will be added where it will contain an array with all the errors produced in the file, together with the line in which it occurred.
{
"errors": [
{
"line": 13,
"msg": "Invalid card"
}
],
}
If there are no errors in sending the file, the response will contain an empty array under the key "errors".