Transaction Management

Using our API, you can manage the complete lifecycle of a transaction in your application, from settlement and refunding to voids. Although all these calls can be managed in our transaction processing and reconciliation tool, Ecommerce Portal, using the API means you don't have to log in to different interfaces.

In this API reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on Transaction Management, see our main article.

This request type is used to capture a Delayed Capture transaction, placing it in the next settlement file to be sent to the acquirer. The amount of time the funds can remain ring-fenced on the customer's card may vary between different card issuers and acquirers. The card brands like Visa and MasterCard also have their own rules around how long transactions can wait to be captured. For more information, contact your account manager with us or your acquirer.

Transactions can be captured for up to 115% of the original authorization amount.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="settle" timestamp="20180613104233">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>wgH8RjewQ16gIWJ5bqQKGA</orderid>
  <foreignretailer flag="false"/>
  <pasref>14611471047824414</pasref>
  <!-- Optional - supply the amount to settle for
  <amount>599</amount> 
  -->
  <sha1hash>31ee74dfac4e3f40c8e568d416f543fc495f9b4e</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Sample response

<response timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>wgH8RjewQ16gIWJ5bqQKGA</orderid>
  <authcode>000000</authcode>
  <result>00</result>
  <cvnresult>U</cvnresult>
  <avspostcoderesponse>U</avspostcoderesponse>
  <avsaddressresponse>U</avsaddressresponse>
  <batchid>320060</batchid>
  <message>Successful</message>
  <pasref>14611472244322341</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <cardissuer>
    <bank/>
    <country/>
    <countrycode/>
    <region/>
  </cardissuer>
  <sha1hash>b9f5ff97f622def43205e18288e419fe8c4f7fcf</sha1hash>
</response>

Response syntax

A refund is a reversal to an existing successfully captured authorization. For the request to be accepted, you must supply the original Order ID, Payments Reference (pasref) and Auth Code from the authorization response. Transactions can be refunded for up to 115% of the original authorization amount and the original currency must also be sent in the request.

To process a refund you must supply the Rebate Password, which you can set with a member of our support team (this is a different password than the Refund Password). This password must be hashed using the SHA-1 algorithm before being added to the request.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="rebate" timestamp="20180613104233">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>wgH8RjewQ16gIWJ5bqQKGA</orderid>
  <foreignretailer flag="false"/>
  <amount currency="EUR">1999</amount>
  <pasref>14609958221624162</pasref>
  <authcode>12345</authcode>
  <refundhash>fb528c20a04fb494f796591392ede2d36140b471</refundhash>
  <sha1hash>946435842f5602b9db2a78c1fc983e2960b79c13</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Sample response

<response timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>wgH8RjewQ16gIWJ5bqQKGA</orderid>
  <authcode>000000</authcode>
  <result>00</result>
  <cvnresult>U</cvnresult>
  <avspostcoderesponse>U</avspostcoderesponse>
  <avsaddressresponse>U</avsaddressresponse>
  <batchid>320060</batchid>
  <message>Successful</message>
  <pasref>14611472244322341</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <cardissuer>
    <bank/>
    <country/>
    <countrycode/>
    <region/>
  </cardissuer>
  <sha1hash>b9f5ff97f622def43205e18288e419fe8c4f7fcf</sha1hash>
</response>

Response syntax

Before settlement, it is possible to Void an Authorization, Offline, Refund, or Credit request. If the transaction has already been placed in the next settlement file, this will remove it. If using Delayed Capture, this will cancel the initial authorization. If the transaction has been settled or batched, then it cannot be voided. This request requires the Order ID and Payments Reference (pasref) from the original transaction.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="void" timestamp="20180613104233">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>wgH8RjewQ16gIWJ5bqQKGA</orderid>
  <foreignretailer flag="false"/>
  <pasref>14611495995965048</pasref>
  <sha1hash>6b4b2d2002c308bf85324ec2404d14cf7ae957f3</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Sample response

<response timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>wgH8RjewQ16gIWJ5bqQKGA</orderid>
  <authcode>000000</authcode>
  <result>00</result>
  <cvnresult>U</cvnresult>
  <avspostcoderesponse>U</avspostcoderesponse>
  <avsaddressresponse>U</avsaddressresponse>
  <batchid>320060</batchid>
  <message>Successful</message>
  <pasref>14611472244322341</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <cardissuer>
    <bank/>
    <country/>
    <countrycode/>
    <region/>
  </cardissuer>
  <sha1hash>b9f5ff97f622def43205e18288e419fe8c4f7fcf</sha1hash>
</response>

Response syntax

Multi-capture (also known as split-shipment) is used to process transactions with multiple items that are shipped at different times or from multiple vendors, distribution centers, or store locations. To use this functionality, in the original authorization request, the Autosettle Flag must be set to MULTI. You can capture the transaction any number of times, up to 115% of the original authorization amount.

This service must adhere to compliance rules outlined by the card brands (for example, Visa and Mastercard) to ensure that the merchant qualifies for the optimum interchange rate for their transaction.

In addition, the time the funds can remain ring-fenced on the customer's card varies among different Issuers and Acquirers. The card brands also have their own rules around how long transactions can wait to be captured. For more information, contact your account manager with us or your Acquirer.

To process a refund against a multi-capture authorization, the following must be sent in the refund request:

• Take the original Order ID of the authorization and add a preceding 'multisettle' to it.
  For example: '_multisettle_wgH8RjewQ16gIWJ5bqQKGA'
• The Payments Reference (pasref) sent in the refund must also be the one returned in the response of the last multi-capture request, not the original authorization.

Multi-capture works on logic. If you don’t include the estimated number of transactions in your request, our system will default to a maximum of five capture requests for a multi-auth transaction. The fifth capture request will be considered the final one, even if the final flag is not present. Once the transaction counter is reached, even the original amount is not fully settled.

Consider this typical scenario:

1. As usual, after five capture partial amounts, the next capture is not allowed unless we void the previous five that were settled.
2. Once we void all five previous captures, they are allowed only for the multi-auth's remaining amount.
   For example: multiauthAmt – sum of captures = 100 - 80 = 20
3. To set the multi-capture counter equator to counter five, we must bypass the multi-capture transaction five-counters condition if the following field will be sent in the request: <estnumtxn>...</estnumtxn>

Authorization

As mentioned above, in the original authorization you must indicate that this transaction will be captured multiple times; set the Autosettle Flag to MULTI.

To avail of interchange optimization, you must indicate the number of future captures. This can be done either in the initial authorization request or in one of the subsequent multi-capture requests (see below).

We recommend that if at the time of authorization you know the number of captures you intend to process; include it in the request. That way, you don’t have to include any flag in subsequent multi captures. The value can always be modified in the subsequent multi-capture requests.

If you don’t supply this information, we will automatically estimate the number of subsequent captures to be 5. As outlined, this can be overridden in the multi-captures requests themselves.

Sample request

<?xml version='1.0' encoding='UTF-8'?>
<request type='auth' timestamp='20181023110744'>
    <merchantid>Merchant ID</merchantid>
    <account>internet</account>
    <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
    <amount currency='EUR'>1001</amount>
    <card>
        <number>4263970000005262</number>
        <expdate>0519</expdate>
        <chname>James Mason</chname>
        <type>VISA</type>
        <cvn>
            <number>123</number>
            <presind>1</presind>
        </cvn>
    </card>
    <!-- Begin Multi-Capture fields -->
    <autosettle flag='MULTI'/>
    <estnumtxn>3</estnumtxn>
    <!-- End Multi-Capture fields -->
    <sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Multi-capture request

When you’re ready to capture part of a transaction you can send the specific multi-capture request to us. You can edit the estimated number of captures, or indicate that this is the last capture for this transaction.

Sample request

<?xml version='1.0' encoding='UTF-8'?>
<request type='multisettle' timestamp='20181023110744'>
    <merchantid>Merchant ID</merchantid>
    <account>internet</account>
    <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
    <amount>250</amount>
    <pasref>14611471047824414</pasref>
    <authcode>12345</authcode>
    <!-- Begin Multi-Capture Fields --> 
    <txnseq>
        <final flag="0"/>
    </txnseq>
    <!-- End Multi-Capture Fields -->
    <!-- Optional Estimated Transactions Number
    <estnumtxn>3</estnumtxn>
    -->
    <sha1hash>1a4c4c72a30a71fe056e74693bba1867ea171e82</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Build the request hash

Use the tabs below to follow the steps for a certain request type: Capture, Refund, or Void.

"timestamp.merchantid.orderid.amount.currency.cardnumber"

// in this example we are not settling for the full amount
"20200205093140.Merchant ID.wgH8RjewQ16gIWJ5bqQKGA.500.."

// in this example we are not settling for the full amount
// this will settle for the full amount
"20160420081035.Merchant ID.wgH8RjewQ16gIWJ5bqQKGA..."

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

947903969e7aaf996164c680a6669805fe405269

Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the response hash

Use the tabs below to follow the steps for a certain request type: Capture, Refund or Void. After making a selection, the steps on how to check the response hash for that type are provided.

"timestamp.merchantid.orderid.result.message.pasref.authcode"

"20200205093140.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.Successful.14631546336115597.000000"

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"