Process payments in batch
Beta
Last updated: February 12, 2025
Batch processing enables you to process a large number of payment actions in bulk. For example, if you need to process refunds or captures based on daily inventory management requirements.
You can use batch processing to:
- Authorize pay-in merchant-initiated transactions (MIT)
- Request card and bank payouts
- Capture payments
- Reverse payments
- Process refunds
To submit a batch request you must:
- Configure your Secure File Transfer Protocol (SFTP) server.
- Prepare the batch request file. This is a CSV file containing:
- The IDs of the payments you want to process.
- The payment action you want to perform on each payment.
- Encrypt the batch request file.
- Upload the batch request file to the SFTP server.
Before you can process batch requests, you must first configure an SFTP server to upload your batch request files to.
To create a public and private key pair, run the following command in your command line tool:
This generates:
- A public key, with the file name
checkout-sftp.pub. - A private key, with the file name
checkout-sftp.
To retrieve the public key using the command line, run the following command in your command line tool:
Alternatively, you can locate and open the file using your system's file explorer.
Contact your Account Manager or [email protected] to request an SFTP server and provide them with your public key.
In return, you'll receive the following:
- An SFTP server
- A port
- A username
To sign in to your SFTP server, use the following credentials:
- Username – The username provided to you by Checkout.com
- Password – The private key you generated in an earlier step
When you sign in to your SFTP server, you can access:
- The uploads folder, where you can upload your batch request files.
- The results folder, where we can return the results of each batch request.
Your batch request file must follow RFC 4180 standards and use a specific format so that it can be processed successfully.
Depending on the batch actions you want to process, your CSV file must be configured differently:
You can batch process MIT pay-in authorizations, such as recurring and unscheduled payments with stored card details, and process card and bank payouts.
Create a new spreadsheet in a spreadsheet editor, and add the following header rows for three columns:
action_typeamountprocessing_channel_id
Set the action_type values to Payment.
You can specify any number of additional headers in the batch request file. Each additional header must be a field supported by the Payments API.
The required API fields vary depending on the action you want to take. Ensure you send supported fields for each payment schema:
For example, to send the following data in the file:
You must create two headers in the CSV file:
customer.emailcustomer.name
Information
Because only MIT authorizations are supported, the following apply:
"payment_type": “Regular”is not supported.- The only authentication supported is 3D requester-initiated (3RI).
- Incremental authorizations are not supported for batch authorizations.
Create a new spreadsheet in a spreadsheet editor and in the header row:
- Use the header
payment_idfor the first column. - Use the header
action_typefor the second column.
Provide the ID of each payment you want to process in a new row in the payment_id column.
A batch request file can only be used to process one type of payment action for all payment IDs included in the file. For example, you can process captures and partial captures in the same batch request file, but the file is invalid if it includes a mix of capture and refund payment actions.
Ensure you submit only one action for each payment ID. Only the first action for a given payment ID within the file is processed.
For each row in the action_type column, use one of the following values, depending on the payment action you want to perform on the payments:
- Capture
- Refund
- Reversal
Information
You must provide a value for the payment_id and action_type columns in every row. If either of these values are missing from a row, the file is invalid.
You can specify any number of additional headers in the batch request file. Each additional header must be a field supported by the respective payment action API:
The header values must exactly match the format of the API field, including the letter case used.
For example, to send the following data in the file:
You must create two headers in the CSV file:
customer.emailcustomer.name
If you include a header in the file but do not want to provide a value for any given payment ID, leave the cell blank.
Information
To process multiple partial captures, include a capture_type header and set the value to NonFinal in the appropriate rows.
When your batch request file is ready, export it as a CSV file with a unique name and encode it using UTF-8.
Encrypt the batch request file to protect any sensitive information it may contain, such as card numbers or customer names.
Before you begin, install GnuPG using one of the following options:
- GnuPG installer – Windows and macOS
- Homebrew, using the
brew install gnupgcommand – macOS only, requires Homebrew to be installed - Chocolatey, using the
choco install gnupgcommand – Windows only, requires Chocolatey to be installed
Then, follow the steps for the environment you want to encrypt the batch file for:
- Import the public Checkout.com key for the test environment, using the following command in your terminal:
- Confirm that the key imported successfully:
- Encrypt the CSV with the imported key. In the following command, replace
[FILE_NAME]with your CSV file name, and[KEY_ID]with the ID listed in the output from the previous step:
By default, the encrypted file is created in the same directory as the source file, with a .gpg file extension. For example, example.csv.gpg.
Sign in to your SFTP server and upload the batch request file to the uploads folder.
If you encounter an issue when uploading or processing your batch request file, ensure that the file:
- Contains comma-separated data in CSV format – other delimiters are not supported
- Is encoded using UTF-8
- Is encrypted with PGP
- Uses a character set that follows Unicode standards
- Does not exceed 100MB in size
- Does not exceed the 100,000 row limit
Once you successfully upload the batch request file, it's added to the processing queue. The file is automatically deleted after 24 hours.
Information
Checkout.com only processes one batch request per entity_id at a time. If you've submitted several batch requests for the same entity, they will be processed sequentially once the previous batch request in the queue has completed.
When you upload a batch request file, the system checks that the file's contents are valid and adds an acknowledgement file in your SFTP server's results folder:
- If the batch request file passes validation, you receive an ACK file.
- If one or more lines in the file fail validation, you receive a NACK file.
The file name is the name of the original batch request file with the suffix _ack or _nack, depending on which type of acknowledgement was returned. For example, Batch_payment_processing_sample_ack.csv.
Information
ACK and NACK files are available for 30 days and then they're automatically deleted.
An ACK file is a CSV file containing two headers:
batch_id– The ID of the batch payment request filerequest_count– The number of payment action rows (records) in the file
A NACK file is a CSV file containing three headers:
type– The type of validation error, with each row containing one of the following values:file– There is an issue with the file format, file size, or encryption.header– There is an issue with the header row.line– There is an issue with the data.
error_description– A description of the validation error.line_number– The line on which the validation error occurred, if the errortypeisline.
When your batch request is processed, you'll receive a file in your SFTP server's results folder.
The file name is the name of the original batch request file with the suffix _result. For example, Batch_payment_processing_sample_result.csv.
Information
The results file is available for 30 days and then it's automatically deleted.
The results file is a CSV file containing four headers:
line_number– The line number of the payment that was processed.payment_id– The payment's unique ID.http_status_code– The HTTP status code returned by the request.response_body– The response body returned by the request.