Incremental authorisations using our API

The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
Read this article to learn more.

An incremental authorisation is used to increase the total amount to be paid by the customer for a transaction that was previously authorised but not yet settled. It is an additional request submitted using the Webservices API that can be used to seek authorisation for additional funds. If authorised successfully, this request will automatically update the settle amount of the transaction in question.

Requirements

You can only process incremental authorisations with Visa-branded cards.

Incremental authorisations are supported for merchants with a Trust Payments acquiring account and supported MCC codes

Your account must be assigned one of the following Merchant Category Codes (MCC) to be eligible to use incremental authorisations:

3351-3999, 4111, 4112, 4121, 4131, 4411, 5812, 5813, 7011, 7033, 7394, 7512, 7513, 7519, 7996, 7999

If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.

A previously-authorised payment is required

Incremental authorisations require a parent pre-authorisation that meets the following criteria:

Parent AUTH MUST have accounttypedescription= “ECOM” or “MOTO”.
Parent AUTH MUST have authmethod = “PRE”.
Parent AUTH MUST have settlestatus = 0 (pending automatic settlement),1 (pending manual settlement) or 2 (suspended).

Processing incremental authorisations

Incremental authorisations are processed by submitting additional AUTH requests using our Webservices API.

Request

The following request example submits an incremental authorisation. This follows the same structure as a standard AUTH request, except for the following key differences:

The authmethod field must be submitted with the value “INCREMENTAL”.
The parenttransactionreference must contain a reference to a previously authorised payment, meeting the requirements outlined above.
New incremental authorisations must be processed using the same card as the parent AUTH.
New incremental authorisations must be processed using the same currency as the parent AUTH.
New incremental authorisations must be processed using the same acquirer as the parent AUTH.
New incremental authorisations cannot be processed using a parent AUTH that has been settled or cancelled.

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "baseamount": "10000",
  "orderreference": "My_Order_123",
  "authmethod": "INCREMENTAL",
  "parenttransactionreference": "1-2-345678"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'baseamount' => '10000',
  'orderreference' => 'My_Order_123',
  'authmethod' => 'INCREMENTAL',
  'parenttransactionreference' => '1-2-345678'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias":"webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "baseamount": "10000",
    "orderreference": "My_Order_123",
    "authmethod": "INCREMENTAL",
    "parenttransactionreference": "1-2-345678"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "baseamount":"10000",
    "orderreference":"My_Order_123",
    "authmethod":"INCREMENTAL",
    "parenttransactionreference":"1-2-345678"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount>10000</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <authmethod>INCREMENTAL</authmethod>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

Field specification

Field	Format	Description
authmethod XPath: /operation/authmethod	Alpha (11)	For the incremental authorisation, this must be set to “INCREMENTAL”.
baseamount XPath: /billing/amount	Numeric (13)	The amount associated with the incremental authorisation. Must be in base units, with no commas or decimal points, so £10 would be 1000. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	Submit the transactionreference of the “PRE” AUTH for which incremental authorisations are to be processed with.
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “AUTH”.
sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support Team.
credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	Can optionally be submitted as part of Visa’s Credentials on File (CoF) feature: “2” – A payment using previously-stored credentials.

Response

This follows the same specification as a standard AUTH response.

Field specification

Field	Format	Description
authmethod XPath: /operation/authmethod	Alpha (11)	This is returned as “INCREMENTAL”.
baseamount XPath: /billing/amount	Numeric (13)	The amount associated with the incremental authorisation. Returned in base units, with no commas or decimal points, so £10 would be 1000.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference of the “PRE” AUTH upon which the incremental authorisation was processed.
requesttypedescription XPath: /@type	Alpha (20)	This is returned as “AUTH”.
credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	Indicates whether transaction is part of Visa’s Credentials on File (CoF) feature: “2” – A payment using previously-stored credentials. This field is returned if submitted in the request.

Updating the transaction

All updates are to be performed on the original parent authorisation.

By performing successful incremental authorisations, the total amount authorised for the transaction is increased.
At any time prior to settlement while the transaction is still pending, you can update the settle amount to be any value that is less than or equal to the total amount authorised.

Refunds

Incremental authorisations having been processed on a given transaction does not affect the steps needed to perform a refund.

Ensure you are performing the refund using the original transaction as the parent rather than trying to action any of the individual incremental authorisations.
When performing a refund, the system will automatically refund the customer using the total amount settled, including any additional funds added via incremental authorisations prior to settlement.

Further reading on this topic