Payment Tokenisation
Quick Find
Go straight to the section you need.
1.0 Gateway Integration →
2.0 New Transactions →
3.0 Management Requests →
4.0 AVS/CV2 Checking →
5.0 3-D Secure Authentication →
11 Receipts and Notifications →
17 Advanced Data →
17.7 Device Information Fields
19 Gateway Wallet →
26 Digital Wallet Transactions →
Appendix
A-1 Response Codes
A-1.1 Authorisation Response Codes
A-2 AVS / CV2 Check Response Codes
A-3 Secure Authentication Data
A-4 3-D Secure Enrolment/Authentication Only
A-9 Duplicate Transaction Checking
A-10 Capture Delay
A-13 Sample Signature Calculation
A-14 Transaction Life cycle
A-14.1 Authorise, Capture and Settlement
A-15.2 Mail Order/Telephone Order (MOTO)
A-15.3 Continuous Authority (CA)
A-16 Payment Tokenisation
A-16.1 PREAUTH, SALE, REFUND, VERIFY requests
A-16.3 CANCEL or CAPTURE requests
A-16.5 SALE or REFUND Referred Authorisation requests
A-18 PSD2 SCA Compliance
A-18.1 Obtaining Strong Customer Authentication
A-18.3 Exemptions to Strong Customer Authentication
A-19 Hosted Payment Page Options
A-20 Integration Libraries
A-20.1 Gateway Integration Library
A-20.2 Hosted Payment Page Library
A-20.3 Hosted Payment Fields Library
A-21 Example HTTP Requests
A-22 Example Integration Code
A-23 Example Library Code
A-23.1 Gateway Integration Library
A-16 Payment Tokenisation
All new transactions stored by the gateway are assigned a unique reference number that is referred to as the cross reference and returned in the xref response field. This cross reference is displayed on the Merchant Management System (MMS) and used whenever a reference to a previous transaction is required.
The cross reference can be sent as part of a transaction request, in the xref request field, to tell the Gateway to perform an action on an existing transaction. This is usually for management actions such as CANCEL or CAPTURE.
The cross reference can also be sent with new transactions such as PREAUTH, SALE, and REFUND actions, to request that the Gateway uses the values from the existing transaction if they have not been specified in the new request. For more information on how the existing values are used, please refer to appendix A-17. This allows an existing transaction to be effectively repeated without your needing to know the original card number. The only exception to this is the card’s security code (CVV) which the Gateway cannot store, due to PCI DSS restrictions. Accordingly, it will have to be supplied in the new request (unless the new request is a Continuous Authority transaction, refer to appendix A-15.3).
The use of cross references to perform repeat transactions is referred to as Payment Tokenisation and should not be confused with Card Tokenisation which is a separate service offered by the Gateway.
Refer to section 12 for details on how to instruct the Gateway to repeat a payment automatically.
The way each action handles any supplied xref is as follows:
A-16.1 PREAUTH, SALE, REFUND, VERIFY requests
These requests will always create a new transaction.
The xref field can be provided to reference an existing transaction, which will be used to complete any missing fields in the current transaction. The previous transaction will not be modified. For more information on how the existing values are used, please refer to appendix A-17. If the existing transaction cannot be found, then an error will be returned and recorded against the new transaction
The request is expected to contain any transaction information required.
The xref will only be used to complete any missing card and order details, relieving you from having to store card details and reducing your PCI requirements.
A-16.2 REFUND_SALE requests
These requests will always create a new transaction.
The xref field can be provided to reference an existing transaction that is going to be refunded. This existing transaction will be marked as have been fully or partially refunded and the amounts will be tallied to ensure that you cannot refund more than the original amount of this existing transaction. If the existing transaction cannot be found, then an error will be returned and recorded against the new transaction.
The request is expected to contain any transaction information required.
The xref will not only be used to find the transaction to be refunded: additionally, that transaction will be used to complete any missing card and order details, relieving you from having to store card details and reducing your PCI requirements.
A-16.3 CANCEL or CAPTURE requests
These requests will always modify an existing transaction.
The xref field must be provided to reference an existing transaction, which will be modified to the desired state. If the existing transaction cannot be found, then an error is returned but no record of the error will be recorded against any transaction.
The request must not contain any new transaction information any attempt to send any new transaction information will result in an error. The exception is that a CAPTURE request can send in a new lesser amount field when a lesser amount, than originally authorised, must be settled.
A-16.4 QUERY requests
These requests will not create or modify any transaction.
The xref field must be provided to reference an existing transaction, which will be returned as if it had just been performed. If the existing transaction cannot be found, then an error is returned but no record of the error will be recorded against any transaction.
The request must not contain any new transaction information and any attempt to send any new transaction information will result in an error.
A-16.5 SALE or REFUND Referred Authorisation requests
These will always create a new transaction.
The xref field must be provided to reference an existing transaction, which must be of the same request type and be in the referred state. A new transaction will be created based upon this transaction. If the existing transaction cannot be found or is not in the referred state, then an error will be returned and recorded against the new transaction.
The new transaction will be put in the approved state and captured when specified by the existing or new transaction details. It will not be sent for authorisation again first.
The request may contain new transaction details, but any card details or order amount must be the same as the existing transaction. Any attempt to send different card details or order details will result in an error.
NB: This usage is very similar to a normal SALE or REFUND request sent with an authorisationCode included. The difference is that the xref must refer to an existing referred transaction whose full details are used if required and not simply an existing transaction whose card details are used if required.
This means it is not possible to create a pre-authorised SALE or REFUND request and use a xref (ie to use the card and order details from an existing transaction). As soon as the xref field is seen, the Gateway identifies that it is a referred transaction that you wish to authorise.