# Process payments in bulk 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 payin merchant-initiated transactions (MIT) - Request card and bank payouts - Capture payments - Reverse payments - Process refunds To submit a batch request you must: 1. Prepare the batch 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. 2. Encrypt the batch file. 3. Upload the batch file. You can upload the file to the Dashboard or an SFTP server. --- ## Prepare the batch file Your batch file must follow [RFC 4180](https://datatracker.ietf.org/doc/html/rfc4180) standards and use a specific format so that it can be processed successfully. A batch file can only contain payments for one entity. If you process payments for more than one entity, create a separate batch file for each entity and upload them individually. Depending on the batch actions you want to process, your CSV file must be configured differently: - [Authorize MIT transactions, or request bank or card payouts](#Configure_a_file_to_authorize_MIT_transactions,_or_request_bank_or_card_payouts) - [Capture, refund, or reverse payments](#Configure_a_file_to_capture,_refund,_or_reverse_payments) > **Information** > > You can enable [idempotency](#Add_idempotency_header_for_requests) for requests in the batch file. ### Configure a file to authorize MIT transactions, or request bank or card payouts You can batch process MIT payin authorizations, such as [recurring](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/recurring-payments-with-stored-card-details.md) and [unscheduled](https://www.checkout.com/docs/payments/accept-payments/pay-with-stored-card-details/unscheduled-payments-with-stored-card-details.md) payments with stored card details, and process [card](https://www.checkout.com/docs/payments/request-payouts/card-payouts.md) and [bank](https://www.checkout.com/docs/payments/request-payouts/bank-payouts.md) payouts. Create a new spreadsheet in a spreadsheet editor, and add the following header rows for three columns: - `action_type` - `amount` - `processing_channel_id` Set the `action_type` values to `Payment`. You can specify any number of additional headers in the batch file. Each additional header must be a field supported by the [Payments](https://api-reference.checkout.com/#tag/Payments) API. The required API fields vary depending on the action you want to take. Ensure you send supported fields for each payment schema: - [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout!path=0/currency&t=request) - [Request a card payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout!path=2/source&t=request) - [Request a bank payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout!path=3/source&t=request) For example, to send the following data in the file: ```json { "customer":{ "email": "", "name": "" } } ``` You must create two headers in the CSV file: - `customer.email` - `customer.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. [Download sample payment batch request .zip file](https://www.checkout.com/docs/assets/downloads/Batch_payment_example.zip) ### Configure a file to capture, refund, or reverse payments Create a new spreadsheet in a spreadsheet editor and in the header row: - Use the header `payment_id` for the first column. - Use the header `action_type` for the second column. Provide the ID of each payment you want to process in a new row in the `payment_id` column. A batch 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 file, but the file is invalid if it includes a mix of captures and refunds. 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 value is missing from a row, the file is invalid. You can specify any number of additional headers in the batch file. Each additional header must be a field supported by the respective payment action API: - [Capture a payment](https://api-reference.checkout.com/tag/Payments/#operation/captureAPayment) - [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) - [Reverse a payment](https://api-reference.checkout.com/tag/Payments/#operation/reversePayment) 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: ```json { "customer":{ "email": "", "name": "" } } ``` You must create two headers in the CSV file: - `customer.email` - `customer.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. [Download sample batch file (.zip)](https://www.checkout.com/docs/assets/downloads/Batch_payment_processing_sample.zip) When your batch file is ready, export it as a CSV file with a unique name and encode it using UTF-8. > **Information** > > If you use the Dashboard to process batch files, you do not need to encrypt your file or configure an SFTP server. Skip to the [Upload the file to the Dashboard](#Upload_the_file_to_the_Dashboard) step. ### Add idempotency header for requests [Idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md) enables you to safely retry failed requests without the risk of a duplicate request. For example, due to a network error or timeout. To enable idempotency for the requests in your batch file: 1. Add a new column to the file. 2. Name the column header `cko_idempotency_key`. 3. Provide an idempotency key for each request you want to enable idempotency for. > **Information** > > This provides the same functionality as providing a `Cko-Idempotency-Key` header in your API request. --- ## Encrypt the batch file Encrypt the batch file to protect any sensitive information it may contain, such as card numbers or customer names. Before you start, install GnuPG using one of the following options: - [GnuPG installer](https://gnupg.org/download/index.html) – Windows and macOS - Homebrew, using the `brew install gnupg` command – macOS only, requires Homebrew to be installed - Chocolatey, using the `choco install gnupg` command – Windows only, requires Chocolatey to be installed Then, follow the steps for the environment you want to encrypt the batch file for: > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** 1. Import the public Checkout.com key for the sandbox environment, using the following command in your terminal: ```curl curl -s "https://cdn1.checkout.com/keys/cko-batch-actions-key-4096.txt" | gpg --import ``` 2. Confirm that the key imported successfully: ``` gpg --list-keys ``` 3. 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: ``` gpg --encrypt --recipient [KEY_ID] [FILE_NAME].csv ``` 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`. **Sandbox** 1. Import the public Checkout.com key for the sandbox environment, using the following command in your terminal: ```curl curl -s "https://cdn1.checkout.com/keys/cko-batch-actions-key-sbox-4096.txt" | gpg --import ``` 2. Confirm that the key imported successfully: ``` gpg --list-keys ``` 3. 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: ``` gpg --encrypt --recipient [KEY_ID] [FILE_NAME].csv ``` 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`. --- ## Configure the SFTP server > **Information** > > You do not need to configure an SFTP server if you [upload your batch file to the Dashboard](#Upload_the_file_to_the_Dashboard). You can configure an SFTP server to upload your batch files to. ### Create a public and private key pair To create a public and private key pair, run the following command in your command line tool: ``` ssh-keygen -t rsa -b 4096 -f "checkout-sftp" ``` 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: **macOS/Linux** ``` cat "checkout-sftp.pub" ``` **Windows** ``` type "checkout-sftp.pub" ``` Alternatively, you can locate and open the file using your system's file explorer. To request an SFTP server and provide them with your public key, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). You receive the following: - An SFTP server - A port - A username ### Sign in to the SFTP server 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 upload your batch files - The _results_ folder, where we return the results of each batch request --- ## Upload the batch file You can upload the encrypted batch file to the Dashboard or an SFTP server you configured. ### Upload the file to the Dashboard To upload a batch file to the Dashboard: 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Payments_ > _Processing_ > _All payments_. 3. Select _Batch processing_. 4. Select _Upload batch file_. 5. Upload the file in the modal that appears.
If the file is valid, you receive an email when the payments are processed. The email contains a link to view the processed payments in the Dashboard.
If the file is invalid, you receive a validation result file which describes the errors in your batch file. Fix the errors and upload the file again. ### Upload the file to the SFTP server Sign in to your SFTP server and upload the batch file to the _uploads_ folder. Ensure your SFTP client uploads files directly using their final file name. Some clients upload files using a temporary file name (for example, by appending .filepart or .tmp) and then rename them after completion. This causes the file to be rejected. If your client has this option, disable it before uploading. If you encounter an issue when uploading or processing your batch file, ensure that the file: - Has a .GPG or .ASC file extension. - 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 file, it's added to the processing queue. The file is automatically deleted after 24 hours. > **Information** > > Each batch file must only contain payments for a single `entity_id`. If you process payments for multiple entities, upload a separate batch file for each entity. > > Checkout.com only processes one batch request per `entity_id` at a time. If you've submitted several batch requests for the same entity, we process them sequentially once the previous batch request in the queue completes. --- ## Review batch file validation > **Information** > > If you upload a batch file to the Dashboard, you do not receive any files on the SFTP server. When you upload a batch 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 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 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. The files are automatically deleted after this period. If you've [configured your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), you also receive a webhook as follows: - If the batch file passes validation, you receive [Batch successful](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/batch_successful.md) webhook. - If one or more lines in the file fail validation, you receive a [Batch unsuccessful](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/batch_unsuccessful.md) webhook. ### ACK file contents An ACK file is a CSV file containing two headers: - `batch_id` – The ID of the batch payment request file - `request_count` – The number of payment action rows (records) in the file [Download sample ACK file (.zip)](https://www.checkout.com/docs/assets/downloads/ACK_sample.zip) ### NACK file contents 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 error `type` is `line`. [Download sample NACK file (.zip)](https://www.checkout.com/docs/assets/downloads/NACK_sample.zip) --- ## View batch processing results > **Information** > > If you upload a batch file to the Dashboard, you do not receive any files on the SFTP server. 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 file with the suffix `_result`. For example, `Batch_payment_processing_sample_result.csv`. > **Information** > > The results file is available for 30 days. The file is automatically deleted after this period. 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. [Download sample results file (.zip)](https://www.checkout.com/docs/assets/downloads/Results_sample.zip)