Batch Integration

The Batch Integration is an enhancement to the Direct Integration, allowing you to send multiple transactions in a single request and monitor their status. This is useful if you wish to capture multiple transactions or collect multiple payments – for example, collecting subscription charges or loan repayments.

In addition to basic sales processing, the Batch Integration can be used to perform other actions, such as refunds and cancellations, which can provide a more advanced integration with our Gateway.

Unlike the Hosted and Direct Integrations, the Batch Integration does not process transactions sent to it immediately. Instead, the Gateway queues these transactions to be processed and returns a batch reference number which can be used to download a file that contains the current status of the transactions.

Batch Processing does not support transactions that require Customer interaction such as 3-D Secure transactions, or alternative payment methods with interactive Wallet or Checkout pages.

To learn more about our API, we recommend that you check out our latest API guide.

The following example PHP code shows how to send a batch request containing three SALE transactions:

<?php
// Signature key entered on MMS. The demo account is fixed to this value,
$key = 'Circle4Take40Idea';
 
// Gateway URL
$url = 'https://gateway.example.com/batch/';
 
// Create a unique multipart boundary
$boundary = uniqid();
 
// Requests
$reqs = array(
    array(
        'merchantID' => 100001,
        'action' => 'SALE',
        'type' => 1,
        'currencyCode' => 826,
        'countryCode' => 826,
        'amount' => 1001,
        'cardNumber' => '4012001037141112',
        'cardExpiryMonth' => 12,
        'cardExpiryYear' => 15,
        'cardCVV' => '083',
        'customerName' => 'Test Customer',
        'customerEmail' => 'test@testcustomer.com',
        'customerAddress' => '16 Test Street',
        'customerPostCode' => 'TE15 5ST',
        'orderRef' => 'Test purchase',
        'transactionUnique' => uniqid(),
        'threeDSRequired' => 'N',
        'avscv2CheckRequired' => 'N',
    ),
    array(
        'merchantID' => 100001,
        'action' => 'SALE',
        'type' => 1,
        'currencyCode' => 826,
        'countryCode' => 826,
        'amount' => 2002,
        'cardNumber' => '4012001037141112',
        'cardExpiryMonth' => 12,
        'cardExpiryYear' => 15,
        'cardCVV' => '083',
        'customerName' => 'Test Customer',
        'customerEmail' => 'test@testcustomer.com',
        'customerAddress' => '16 Test Street',
        'customerPostCode' => 'TE15 5ST',
        'orderRef' => 'Test purchase',
        'transactionUnique' => uniqid(),
        'threeDSRequired' => 'N',
        'avscv2CheckRequired' => 'N',
    ),
    array(
        'merchantID' => 100001,
        'action' => 'SALE',
        'type' => 1,
        'currencyCode' => 826,
        'countryCode' => 826,
        'amount' => 3003,
        'cardNumber' => '4012001037141112',
        'cardExpiryMonth' => 12,
        'cardExpiryYear' => 15,
        'cardCVV' => '083',
        'customerName' => 'Test Customer',
        'customerEmail' => 'test@testcustomer.com',
        'customerAddress' => '16 Test Street',
        'customerPostCode' => 'TE15 5ST',
        'orderRef' => 'Test purchase',
        'transactionUnique' => uniqid(),
        'threeDSRequired' => 'N',
        'avscv2CheckRequired' => 'N',
    ),
);
 
// Create the batch parts
$parts = array();
foreach ($reqs as $req) {
    // Create the signature using the function called below.
    $req['signature'] = createSignature($req, $key);
    $parts[] =
        "Content-Id: TX{$req['transactionUnique']}\r\n" .
        "Content-Type: application/x-www-form-urlencoded; charset=\"UTF-8\"\r\n" .
        "\r\n" .
        http_build_query($req);
}
 
// Join the parts together separated by the boundary string
$post = "\r\n--{$boundary}\r\n" . join("\r\n--{$boundary}\r\n", $parts) . "\r\n--{$boundary}--\r\n";
 
// Initiate and set curl options to post to the gateway
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: multipart/mixed; charset="UTF-8"; boundary=' . $boundary,
    'Content-length: ' . strlen($post),
));
 
// Send the request
$res = curl_exec($ch);
 
// Normally, process the response here, but for this example, just echo it out.
header('Content-Type: text/plain');
echo $res . PHP_EOL;
 
// Close the connection to the gateway
curl_close($ch);
 
// Function to create a message signature
function createSignature(array $data, $key) {
    // Sort by field name
    ksort($data);
 
    // Create the URL encoded signature string
    $ret = http_build_query($data, '', '&');
 
    // Normalize all line endings (CRNL|NLCR|NL|CR) to just NL (%0A)
    $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret);
 
    // Hash the signature string and the key together
    return hash('SHA512', $ret . $key);
}
?>

To learn more about our API, we recommend that you check out our latest API guide.

Last updated on November 3, 2023

Hosted Integration Integration Libraries