# Batch Processing

## Overview

Sola's batch processing tool allows you to process a large volume of transactions in a single batch, all at once. Batches can be processed for a single account or multiple accounts.

### Conventions <a href="#batchprocessing-conventions" id="batchprocessing-conventions"></a>

**x** = Incrementing Sequence Number

* Numbers can be skipped but they must always be greater than the previous file.
* Files with older or invalid sequence numbers are ignored.
* Sequence Number Max Value = 999999999 (9 digits).

**KVP** = URL Encoded Key-Value-Pair

* Sample: `xName=John%20Smith&xAmount=1`
* **Note**: Ensure that all values are URL encoded.

## Batch Upload Lifecycle <a href="#batchprocessing-batchuploadlifecycle" id="batchprocessing-batchuploadlifecycle"></a>

### Request <a href="#batchprocessing-request" id="batchprocessing-request"></a>

1. Client uploads Request/REQUEST\_X.KVP
2. Client uploads Request/PROCESS\_X.KVP
3. Batch process is triggered when Request/PROCESS\_X.KVP is received

### Response <a href="#batchprocessing-response" id="batchprocessing-response"></a>

1. Gateway saves Response/RESPONSE\_X.KVP
2. Gateway saves Response/COMPLETE\_X.KVP
3. Client polls and parses Response/COMPLETE\_X.KVP
4. If `xStatus`=Success, then client downloads and parses Response/RESPONSE\_X.KVP
5. Client deletes all files from Response folder

## File Formats <a href="#batchprocessing-fileformats" id="batchprocessing-fileformats"></a>

### Request Data File <a href="#batchprocessing-requestdatafile" id="batchprocessing-requestdatafile"></a>

**Filename Format:** REQUEST\_X.KVP

* Each line contains an individual transaction in KVP format. Any transaction that can be executed via the standard API can be submitted in the Request Data File.

**Required Variables:**

| **Value**                      | **Description**                                                | **Sample Data**                                                                                                               |
| ------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `xIndex`                       | The zero-based index number of each row.                       | `xIndex=0&xSequenceNumber=99999&xKey=&xVersion=&xSoftwareNa me=&xSoftwareVersion=&xCommand=&xCardNum=&xExp=&xName=& xAmount=` |
| `xSequenceNumber`              | Must match the Incrementing Sequence Number in the file name.  | `xIndex=0&xSequenceNumber=99999&xKey=&xVersion=&xSoftwareNa me=&xSoftwareVersion=&xCommand=&xCardNum=&xExp=&xName=& xAmount=` |
| Standard API request variables | See [iFields](https://docs.solapayments.com/products/ifields). | `xIndex=0&xSequenceNumber=99999&xKey=&xVersion=&xSoftwareNa me=&xSoftwareVersion=&xCommand=&xCardNum=&xExp=&xName=& xAmount=` |

**File Formats**

### Request Metadata File <a href="#batchprocessing-requestmetadatafile" id="batchprocessing-requestmetadatafile"></a>

**Filename Format:** PROCESS\_X.KVP\
**Required Variables:**

| **Value**         | **Description**                                              | **Sample Data**                                               |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| `xKey`            | Batch upload credential (not the merchant credential).       | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=99999` |
| `xSubmittedCount` | Count of transactions in the Request File.                   | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=99999` |
| `xFormat`         | KVP.                                                         | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=99999` |
| `xSequenceNumber` | Must match the incrementing sequence number in the file name | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=99999` |

**File Formats**

### Response Data File <a href="#batchprocessing-responsedatafile" id="batchprocessing-responsedatafile"></a>

**Filename Format:** RESPONSE\_X.KVP

* Each line contains an individual response in KVP format.

**Required Variables:**

| **Value**                       | **Description**                                                            | **Sample Data**                                                                                                                    |
| ------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `xIndex`                        | Corresponds to the xIndex in the request.                                  | `xIndex=0&xSequenceNumber=99999&xResult=&xStatus=&xError=&xRe fNum=&xAuthCode=&xAuthAmount=&xToken=&xMaskedCardNumber= &xInvoice=` |
| `xSequenceNumber`               | Corresponds to the `xSequenceNumber` in the request.                       | `xIndex=0&xSequenceNumber=99999&xResult=&xStatus=&xError=&xRe fNum=&xAuthCode=&xAuthAmount=&xToken=&xMaskedCardNumber= &xInvoice=` |
| Standard API response variables | See [API Docs](https://docs.solapayments.com/api/transaction/credit-card). | `xIndex=0&xSequenceNumber=99999&xResult=&xStatus=&xError=&xRe fNum=&xAuthCode=&xAuthAmount=&xToken=&xMaskedCardNumber= &xInvoice=` |

**File Formats**

### Response Metadata File <a href="#batchprocessing-responsemetadatafile" id="batchprocessing-responsemetadatafile"></a>

**Filename Format:** COMPLETE\_X.KVP

**Required Variables:**

| **Value**         | **Description**                                                       | **Sample Data**                                                                                           |
| ----------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `xResult`         | <p>Status of the batch upload process.</p><p>Success/Error value.</p> | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=9999 9&xResult=&xStatus=&xError=&xProcessedCount=` |
| `xStatus`         | <p>Status of the batch upload process.</p><p>Success/Error value.</p> | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=9999 9&xResult=&xStatus=&xError=&xProcessedCount=` |
| `xError`          | If `xStatus` = Error, this variable contains the error message.       | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=9999 9&xResult=&xStatus=&xError=&xProcessedCount=` |
| `xProcessedCount` | Count of the processed transactions.                                  | `xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=9999 9&xResult=&xStatus=&xError=&xProcessedCount=` |