In addition to the Token Wallet functionality, Checkout allows for the unique token to be used for refund processing via API. One such use case for this functionality is in back-office systems where refunds/compensation payments which do not always relate to an initial purchase can then be processed.
This method can only be used for Refunds. If you wish to make Merchant Initiated Transactions, you should use the Recurring Transaction API instead.
As the payment instrument, the token, is being passed in by the integrator the authentication method required is the same as used when initiating a new payment. See Authentication for the full breakdown of the request and response. It is important to remember that this authentication method means that certain fields in the authentication request (e.g.
invoiceId etc.) must match in the below request, otherwise the request will be rejected.
Token Refund Request
|Field Name||State||Data Type||Description|
|transactionType||Optional||String||Type of transaction.|
|invoiceId||Mandatory||String||Order/invoice/transaction/basket number generated by the host website, as passed in the request.|
|accountId||Optional||String||Unique reference for the store processing the transaction.|
|description||Optional||String||Message from host website to consumer.|
StringMax 1024 bytes
|Free text field for integrated system to pass custom data that will be stored against the transaction. This data will be returned in the result and available via the Transaction Management functions.|
|terminalId||Mandatory||String||Terminal ID used when authorising the transaction.|
|amount||Mandatory||Decimal||Total amount of the original order/authorisation including decimal places where applicable.|
|ipAddress||Optional||String||IP address of the computer on which the transaction is being performed.|
|currency||Mandatory||String||Currency of the transaction.|
|phone||Optional||String||Consumer’s contact phone number.|
StringMax 256 Char.
|Email address provided by consumer as main contact address.|
Token Refund Request > Card
|Field Name||State||Data Type||Description|
|accountNumber||Optional||String||Masked PAN showing the last four digits of the card – for example “************9909”.|
|cardTokenId||Mandatory||String||The Token for the card, returned in the previous integrated transaction.|
If required by the merchant, the token transaction can also verify the card security code (CSC).
If this validation is required, the CSC should be encrypted with RSA-OAEP (sha256 is used as a hash function) algorithm using DNA Public Key (key length 4096 bits) with an OAuth token used as the label parameter and base64 encoded.
For more details on how to complete this encryption please see Encrypting the Card Security Code (CSC).
|cardType||Optional||String||The Optomany card scheme ID for the card whose token is presented.|
|expirationMonth||Optional||String||The month, in digits, in which the card expires. For example, a card expiring in December would be “12”.|
|expirationYear||Optional||String||The year, in digits, in which the card expires. For example, a card expiring in 2022 would be “22”.|
The CSC must never be stored beyond the time taken to capture, encrypt and send the request. For more detail, please see Encrypting the Card Security Code (CSC)
Token Refund Response
|Field Name||Data Type||Description|
|id||String||Unique transaction ID. This ID should be stored as it is required for later transaction actions.|
|description||String||Descriptive text for the transaction.|
|phone||String||Phone number passed in the request.|
|amount||Decimal||Total amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account represents £1.00.|
|currency||String||Currency of the transaction.|
|invoiceId||String||Order/invoice/transaction/basket number generated by the host website, as passed in the request.|
|accountId||String||Unique reference for the store processing the transaction, as passed in the request.|
|authDateTimeUTC||String||Date and time of when the transaction was authorised with the acquirer.|
|responseCode||String||Returned by the acquirer detailing the result of the transaction. A full list of Response Codes can be found here.|
|success||Boolean||Confirms whether the transaction has been successful.|
|settled||Boolean||Confirms whether the transaction has been submitted for overnight settlement.|
|message||String||Message confirming the processing result of the transaction request.|
|authCode||String||Authorisation code issued for the transaction.|
|cscResult||String||Confirms the result of the Card Security Code (CSC) validation check.|
|payerAuthenticationResult||String||Result of the Payer Authentication process provided in the following format “enrolment result/authentication result”. As the Token Payment is not processed using Payer Authentication the result will always be the below.|
|optomanyTerminalId||String||Optomany Terminal ID used when authorising the transaction.|
|cardExpiryDate||String||Expiry date for the card used in the transaction. Provided in the “MM/YY” format.|
|cardPanStarred||String||Starred PAN for the card used in the transaction - for example ************9909.|
|cardTokenId||String||Optomany Token ID for the card presented.|
|cardSchemeId||Integer||Optomany Card Scheme ID for the card used in the transaction.|
|cardSchemeName||String||Name of the Card scheme for the card used in the transaction.|
|cardIssuingCountry||String||Country where the card was issued. This information will only be returned when this can be determined. This information is subject to change and as such we recommend only using this data as a guide.|
Encrypting the Card Security Code
The Card Security Code (CSC) should be encrypted with RSA-OAEP (sha256 is used as a hash function) algorithm using DNA Public Key (key length 4096 bits) with the OAuth token from the authentication process used as the label parameter and base64 encoded.
OAEP is parameterised by a hash function that is used as a random oracle. Encryption and decryption of a given message must use the same hash function (sha256.New() is used as a hash function).
The random parameter is used as a source of entropy to ensure that encrypting the same message twice does not result in the same ciphertext.
The label parameter may contain arbitrary data that will not be encrypted, but which gives important context to the message. For example, if a given public key is used to decrypt two types of messages then distinct label values could be used to ensure that a ciphertext for one purpose cannot be used for another by an attacker.
For the processing of test transactions the below RSA key should be used.
For live integrations, the live RSA Key will be issued by the Implementations team following the completion of Integration Approval.
Tokenisation Request and Response Examples
CSC Encryption Example
You can view and execute this code here
This code is provided as an example only, please ensure you understand any code you include in your project as you will be responsible for it.