Incremental authorisations using our API

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

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)
	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. This field is returned if submitted in the request.
	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:

• If the settleduedate and/or settlestatus on the initial payment is updated, all child incremental authorisations are updated automatically to match.
• If the initial payment is settled, all child incremental authorisations are also settled automatically.
• If the initial payment is cancelled, all child incremental authorisations are also cancelled automatically.
• If the initial payment is suspended, all child incremental authorisations are also suspended automatically.

Updating incremental authorisations

The only permitted updates for incremental authorisations are:

• Update the settlestatus to “3”, to cancel the incremental authorisation.
• Update the settleamount to be a lower value than was authorised for the incremental authorisation.
• Update the value of the orderreference.

Security considerations

Refunds

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

Additional notes

• Billing and delivery details can differ between incremental authorisations and their parent AUTH.
• Incremental authorisations do not support DCC.
• Protect Plus checks can be performed on an incremental authorisation after it has been processed. Manually process a new RISKDEC request (using our Webservices API) that includes the transactionreference from the incremental AUTH response.