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

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

  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.

  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:

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

 

Python PHP cURL Raw JSON Raw XML
#!/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

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

 

Field specification

  Field Format Description
table-required.png authmethod
XPath: /operation/authmethod
Alpha (11) For the incremental authorisation, this must be set to “INCREMENTAL”.
table-required.png 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)
table-optional.png 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.
table-required.png parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
Submit the transactionreference of the “PRE” AUTH for which incremental authorisations are to be processed with.
table-required.png requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “AUTH”.
table-required.png 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.

ppg-incremental-02.png

 

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.

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

 

Security considerations

  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.

  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

  • 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.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request