Send Batch Request

There are many components to making sure the transaction request body is sent securely to the Suncorp Gateway. This section goes through the essential concepts and functions you may need to use in your integration.

Uploading the Batch Request

The batch file is submitted via HTTP over Secure Socket Layer (SSL) protocol using the HTTP PUT method. This section contains sample code snippets written in shell scripting language. For the sample integration code, see the Downloads section.

Connection URL

The connection URL contains information identifying the Batch Integration version (same as API version), merchant identifier, and batch name.

https://suncorp.gateway.mastercard.com/batch/version/<versionNum>/merchant/<merchantId>/batch/<batchName>

where:

<versionNum> is the version of Batch Integration
<merchantId> is your Merchant identifier
<batchName> is your unique name for the batch

# Configuration: Batch Integration application
VERSION_NUM=72
HB_HOST="https://suncorp.gateway.mastercard.com/batch";

# Configuration: Merchant
MERCHANT_ID="<YOUR_MERCHANT_ID>"
MERCHANT_PASSWORD="<YOUR_MERCHANT_PASSWORD>"

CONNECT_URL="$HB_HOST/version/$VERSION_NUM/merchant/$MERCHANT_ID/batch/"

If you submit a batch request to an incorrectly formatted URL, you will be redirected to a landing page displaying information on how the request should be formatted.

https://suncorp.gateway.mastercard.com/batch

Authentication Data

The Suncorp Gateway requires every batch request to be authenticated successfully. The below snippet covers how to provide authentication data (Merchant ID and API Password) with each batch request.

This code snippet shows how to set credentials in the program.

# Configuration: Batch Integration application
VERSION_NUM=72
HB_HOST="https://suncorp.gateway.mastercard.com/batch";

# Configuration: Merchant
MERCHANT_ID="<YOUR_MERCHANT_ID>"
MERCHANT_PASSWORD="<YOUR_MERCHANT_PASSWORD>"

# Configuration: Advanced
CONNECT_URL="$HB_HOST/version/$VERSION_NUM/merchant/$MERCHANT_ID/batch/"
HTTP_HEADERS="Authorization: Basic `echo -n :$MERCHANT_PASSWORD | base64`"$'\n'"
Content-Type: text/plain; charset=UTF-8"

HTTP Headers

HTTP Headers provide metadata information about the batch request being sent to the the Suncorp Gateway. This snippet demonstrates the mandatory HTTP Headers that must be set for every batch request (the headers listed here must be set in addition to any authentication headers mentioned under Authentication Data, where applicable).

The character encoding of your request must include only ISO-8859-1(Latin1), or UTF-8 formats. See Ensure Character Encoding.

This code snippet shows how to set HTTP headers in the program.

HTTP_HEADERS="Authorization: Basic `echo -n :$MERCHANT_PASSWORD | base64`"$'\n'
"Content-Type: text/plain; charset=UTF-8"

Uploading the Message Integrity Code

Batch Integration requires you to confirm the integrity of the batches you upload by providing a Message Integrity Code (MIC) for validation. The MIC must be calculated by creating a SHA-1 digest of the complete upload request body that contains the CSV NVP batch data and must be HEX encoded.

Supplying the MIC for validation is mandatory.

The MIC upload works as follows:

Upload a batch to the Batch Integration service.

Ensure the batch status is UPLOADED before you supply the MIC. See retrieving the batch status.

Upload the MIC to the Batch Integration service by sending a HTTPS POST request to the following URL with the MIC HEX encoded in the request body.

https://suncorp.gateway.mastercard.com/batch/version/<versionNum>/merchant/<merchantId>/batch/<batchName>/validate

where:

<versionNum> is the version of Batch Integration
<merchantId> is your Merchant identifier
<batchName> is your unique name for the batch

The batch status remains in the UPLOADED state until the MIC has been verified.

Batch Integration validates the supplied MIC against the uploaded batch, and if it matches, the batch will be accepted for processing. If the MIC does not match it is assumed the batch is corrupted. The batch will be deleted and will need to be uploaded again.

The next step is retrieving the batch status.