Choose a topic...
This section contains information about batch processing procedures and the required variables for each response file. Use this integration method to process large numbers of transactions in a batch across multiple accounts by specifying the source key for each transaction in the request.
Conventions
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
Request
- Client uploads Request/REQUEST_X.KVP
- Client uploads Request/PROCESS_X.KVP
- Batch process is triggered when Request/PROCESS_X.KVP is received
Response
- Gateway saves Response/RESPONSE_X.KVP
- Gateway saves Response/COMPLETE_X.KVP
- Client polls and parses Response/COMPLETE_X.KVP
- If
xStatus
=Success then Client downloads and parses Response/RESPONSE_X.KVP - Client deletes all files from Response folder
File Formats
Request Data File
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 filename | xIndex=0&xSequenceNumber=99999&xKey=&xVersion=&xSoftwareNa me=&xSoftwareVersion=&xCommand=&xCardNum=&xExp=&xName=& xAmount= |
Standard API request variables | See iFields | xIndex=0&xSequenceNumber=99999&xKey=&xVersion=&xSoftwareNa me=&xSoftwareVersion=&xCommand=&xCardNum=&xExp=&xName=& xAmount= |
File Formats
Request Metadata File
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 filename | xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=99999 |
File Formats
Response Data File
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 iFields | xIndex=0&xSequenceNumber=99999&xResult=&xStatus=&xError=&xRe fNum=&xAuthCode=&xAuthAmount=&xToken=&xMaskedCardNumber= &xInvoice= |
File Formats
Response Metadata File
Filename Format: COMPLETE_X.KVP
Required Variables:
Value | Description | Sample Data |
---|---|---|
xResult |
Status of the batch upload process
Success/Error value |
xKey=&xSubmittedCount=500&xFormat=KVP&xSequenceNumber=9999 9&xResult=&xStatus=&xError=&xProcessedCount= |
xStatus |
Status of the batch upload process
Success/Error value |
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= |