Implementing a Batch Integration
Prerequisites
- Ensure that your merchant profile is enabled for the Batch service.
- Before you commence integration, see Best Practices and Tips.
Integration steps
Step 1: Access the gateway
As a first step, check your connectivity to the Mastercard Gateway.
Step 2: Knowing your input fields
Before you start building the integration, you must be prepared with the values for the fields that require your input.
Step 3: Create a batch request
Creating the body of the request is a critical step in the integration.
Step 4: Send a batch request
There are many components to making sure the transaction request body is sent securely to the Mastercard Gateway.
Step 5: Retrieve batch status
Once a batch is submitted you can periodically request a batch status to determine the current state of the batch processing.
Step 6: Process batch response
After a batch has completed processing, you can request a response file that contains the result of each of the uploaded operations.
Step 7: Test and go live
Testing allows you to check if your integration is working as desired.
Troubleshooting and FAQs
Can I use multiple merchant profiles in a single batch request?
Yes, you can use multiple merchant profiles in a single batch request if you can ensure that the operation credentials (merchant identifier and authentication password) for each operation record row are valid to enable successful authentication and authorization.
By default, the operation credentials for each operation in a batch will use the authentication credentials supplied in the batch request header (both merchant identifier and password). You may choose to use the defaulting mechanism, or supply operation credentials against each operation record row. With the latter, authentication of the operation will use the operation level credentials and will not default to the uploading batch credentials. If the operation level credentials are incorrect, then the batch upload will be rejected.
In the sample batch file below, the VOID operations will use the batch request header credentials as the merchant identifier and password haven't been supplied.
merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency, cardDetails.card.number, cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104169,TXID1,100,AUD,345678901234564,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
What are the possible causes for a batch submission to fail?
A batch submission may fail due to the following error conditions.
| Scenario | Error Message |
|---|---|
| Batch incomplete because the SHA-1 message digest does not match | Batch submission failed for one of the following reasons:
|
Duplicate batch name
|
Batch submission failed: A batch with this name is currently uploading or a batch with this name but different content has already been uploaded. If the file is already uploading please wait for the upload to finish. If you are using a file name that is already taken, please rename the file and submit again. |
An authentication error is returned if you do not have sufficient privileges to submit batches:
|
Authentication failed: The credentials provided in record <record number> are incorrect. This can be caused by:
|
| An authentication error is returned if you provide only the password but no Merchant ID at the operation level. | Authentication failed. In record <record number> of the batch file a password is provided but no Merchant ID. Please either add a Merchant ID or remove the password to use the batch level merchant credentials for this record, then try to submit the request again. |
| An authentication error is returned if the batch credentials are formatted incorrectly. | Authentication failed: The credentials provided in the header either:
|
An authentication error is returned if:
|
Authentication failed: The credentials provided for the batch are invalid. Please correct the credentials and try to submit the request again |
| A parsing error is returned if the header contains invalid characters. | Batch submission failed: The batch could not be parsed because the header contained an illegal character. Allowed characters are:
|
| A parsing error is returned if an operation record row contains more values than defined in the header. | Batch submission failed: The batch could not be parsed because record <record number> contained more values than defined in the header. Please correct the batch, then try to submit again. |
| A parsing error is returned if the maximum individual field size is exceeded or an unknown parsing error has occurred in an operation record. | Batch submission failed: The batch could not be parsed due to an error in record <record number>. Please make sure the batch complies with the file format and that you are using the correct encoding, then try to submit the batch again. |
| An encoding error is returned if no encoding or an unsupported encoding has been provided. | Request failed: The provided encoding is not supported. Supported encodings are UTF-8 and LATIN1. Please submit the request again using a supported encoding. |
| Batch could not be found | Request failed: A batch with this batch name could not be found. Please correct the batch name and submit the request again. |
| The length check for the provided version failed. | Request failed: The provided version is not valid. Please correct the version and submit the request again. |
| The length check for the provided Batch Name failed. | Request failed: The provided batch name is not valid. Please correct the batch name and submit the request again. |
| The length check for the provided Merchant ID failed. | Request failed: The provided Merchant ID is not valid. Please correct the Merchant ID and submit the request again. |
| A gateway error occurred | The request could not be submitted to the Gateway due to an internal error in the Gateway. Please try again later. |
Processing of operations by Batch may fail due to communications or systems failure resulting in one of the following errors:
- An error occurred due to an internal system failure.
- An error occurred because the server had insufficient resources to process the request at the moment.
- An error occurred while processing a Tokenization verification transaction
When this occurs and an operation is retryable, Batch will retry sending the operation for processing either until a non-retryable response is received on the operation or retry limit is reached.
Batch stores the batch names and their corresponding Message Integrity Code (MIC) uploaded by you. Batches with a batch name that has been previously submitted but with a different content can be identified and will be rejected by Batch.
Batches with a same name and content as a previously submitted batch can also be identified, and Batch returns the same status as for the batch previously uploaded. So, if the merchant suspects there was a transmission problem, he is able to verify that the batch was uploaded successfully to Batch.
Values in the header row of a batch request submitted for processing may only contain characters that can be found in API NVP field names. The following characters are allowed:
- Alphanumeric (a-z, A-Z, 0-9)
- Period (.)
- Square brackets ([ ])
Batch rejects a batch if parsing errors are encountered. Parsing includes splitting the batch into rows, and rows into fields.
A parsing error may occur when:
- operation record that has more commas than what is included in the header record
- the maximum individual field size is exceeded
You must correct these errors first before submitting the batch for processing again.
Best practices and tips
The Batch service does not guarantee that it will process operations in the same order as specified in the batch file because the Batch dispatcher can process operations in parallel. This behavior may also be attributed to the retry function, i.e., if some operations in a batch file need a retry then operations that are ready will be processed first irrespective of the order in which they are specified. For example, even if subsequent operations are specified after initial operations (Capture followed by an Authorization, Void followed by a Pay), then Capture may be performed before Authorization, or Void before Pay.
Hence, for operations that must strictly follow an order, it's recommended that you run the initial batch of operations first, wait for the batch response file, and if successful run the subsequent batch of operations.
Tokenization stores cards details in a token. To use Tokenization with Batch you must use the token identifier in the batch file, as shown below.
apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
The operation credentials include merchant identifier and password. The operation credentials for each operation in a batch will default to the authentication credentials supplied in the batch request header (both merchant identifier and password). However, if you do specify values for both of these fields against operation record rows, authentication of the operation will use the operation level credentials and will not default to the uploading batch credentials.
Yes, you can process multiple operation types in a single batch file provided they are NOT related to the same order, i.e., they do not contain the same order identifier. The Batch service does not guarantee that it will process operations in the same order as specified in the batch file because the Batch dispatcher can process operations in parallel. This behavior may also be attributed to the retry function, i.e., if some operations in a batch file need a retry then operations that are ready will be processed first irrespective of the order in which they are specified. For example, if Pay and Void operations are in the same batch file, the Void may be performed before Pay. However, if the operations are NOT related to the same order, i.e., if they contain different order identifiers, then you can have multiple operation types in a single batch file.
Yes, you can use multiple sources of card details in a single batch file, except the payment session identifier. For information on multiple sources, see Multiple Sources of Card Details.
The Authorize operations in the sample below use tokens instead of card details.
apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,
Yes, there is restriction on the file size. The hosted batch upload allows maximum of 30MB. If the file exceeds the specified limit, ensure files are split into two or more parts, which must not exceed the specified limit, 30MB.