Batch Processing

Overview

Cardknox'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

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

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

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

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 file name.	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 file name	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 API Docs.	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=