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 CommWeb payment 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 CommWeb payment 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:
  • The submitted MIC does not match the MIC computed for the batch file received.
  • The MIC is not hashed using the SHA-1 algorithm.
  • The MIC encoding is not HEX.
  • No MIC is provided in the request body.
Please check the request and try to submit the batch again.
Duplicate batch name
  • A batch with the same name but different content has already been uploaded and validated.
  • A batch with the same name is currently uploading.
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:
  • Merchant does not have the "API and Hosted Batch" privilege
  • Invalid Merchant ID
  • Incorrect password
Authentication failed: The credentials provided in record <record number> are incorrect. This can be caused by:
  • A merchant ID is provided, but this merchant does not have sufficient privileges to submit batches for processing.
  • The merchant ID is incorrect.
  • The provided password is incorrect.
Please correct the credentials and make sure the merchant has sufficient privileges to submit batches for processing, then try to submit the request again.
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:
  • use an invalid character
  • use an invalid Base 64 encoding
  • exceed 70 characters.
Please correct the request then try to submit again.
An authentication error is returned if:
  • Batch credentials are invalid
  • Merchant does not have the "API and Batch" privilege
  • Merchant ID is empty
  • Merchant ID is incorrect
  • Password is empty
  • Password is incorrect
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:
  • Alphanumeric (a-z, A-Z, 0-9)
  • Period (.)
  • Square brackets ([ ])
Please correct the header names and make sure you are using the correct encoding, then try to submit the batch again.
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.
Are failed operations in a batch file retried?

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.

What happens when I upload a duplicate batch name with same content or different content?

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.

If a duplicate batch name is submitted with a different batch content or if this batch is uploaded while the first batch is still uploading then HTTP status code 409 and an error message is returned.
Why am I receiving an HTTP code 400 Invalid header format error?

Values in the header row of a batch request submitted for processing may only contain characters that can be found in DirectAPI NVP field names. The following characters are allowed:

  • Alphanumeric (a-z, A-Z, 0-9)
  • Period (.)
  • Square brackets ([ ])
Why am I receiving a parsing error when I submit a batch for processing?

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

Is it guaranteed that the order in which the operations are specified in a batch file will be the processing order?

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.

How can I use Tokenization with Batch?

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,,,,
Do I need to provide operation credentials against every operation record row in a batch file?

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.

In case of multiple merchant profiles, you may choose to default to authentication credentials supplied with the batch request header and/or supply operation credentials for one or more merchant profiles.
If you wish to use operation level credentials, you must supply BOTH merchant identifier and credentials against every operation record row, not either of them. If you are not authorized to use Batch or if the operation level credentials are incorrect, then the batch upload will be rejected. If you wish to default to the credentials in the batch request header, do not include them in the request.
Can I process multiple operation types (Pay, Refund, Auth, Capture, Void, etc) in a single batch file?

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.

Can I use multiple sources of card details 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,,,,,

Copyright © 2020 Commonwealth Bank of Australia