Contents

Incremental authorisations (API)

Warning
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.

If you are unsure, please contact our Support Team for assistance.

 

An incremental authorisation is used to increase the total amount to be paid by the customer, if it is not known at time of authorisation. It is an additional request submitted using the Webservices API, which can be used to seek authorisation for additional funds, once the full amount is known. The total amount to be paid by the customer is the value from the original AUTH, in addition to amounts associated with the incremental authorisations.

 


 

Requirements

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

Info
Incremental authorisations are only supported by certain acquiring banks and 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

 

Please contact our Support Team for further information.

PAYMENT
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) or 1 (pending manual settlement).

 


 

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:

 


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
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' => '[email protected]',
  '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 [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "10000",
  "orderreference": "My_Order_123",
  "authmethod": "INCREMENTAL",
  "parenttransactionreference": "1-2-345678"
}]}'
{"alias":"[email protected]","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>[email protected]</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)
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.
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.

 

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.
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.
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”.

 


 

Settlement and updates

Relationship with the parent transaction

The initial payment and associated child incremental authorisations are linked together on our system. Using MyST, you can view any incremental authorisations associated with a transaction by clicking the “Related transactions” tab displayed when viewing a transaction’s details.

 

 

Updating the parent transaction

Because of the connection shared between the initial payment and child incremental authorisations, the following behaviour is to be expected:

 

Updating incremental authorisations

The only permitted updates for incremental authorisations are:

Info
Rules that are processed on incremental authorisations can only perform the updates listed above.

 

Security considerations

Info
Incremental authorisations bypass any fraud, duplicate and Security Policy checks that can be run on regular payments. If such checks cause the parent AUTH to be suspended or cancelled, this will also suspend / cancel any child incremental authorisations.

 


 

Refunds

To refund the order in full, the initial payment AND all child incremental authorisations must be refunded separately.

Info
As with standard payments, you can only refund incremental authorisations when they have been settled (settlestatus = 100). If an incremental authorisation has not been settled, you can update the settlestatus to defer or cancel settlement.

 


 

Additional notes