Skip to main content

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:

FieldTypeRequiredDescription
AMOUNTIntegerSIAmount to collect, in cents
CARDStringYESUUID of the card that will be used to make payment
CUSTOMER_EXTERNAL_IDStringYESIdentifier of the user who will make the payment. Must be the same as the one used to store the card.
SERVICEStringYESUUID of the service
ADDITIONALStringNONO
URL_POSTStringNOURL of the merchant where the notification will be sent with the payment result
EXTRA_DATAStringNOYou 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:

FieldTypeRequiredDescription
ORDER_UUIDStringSIUUID of the order to return
AMOUNTIntegerNOAmount 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".