Token creation
For returning customers, the option to save a card for future use can be made available upon the request of the merchant and the cardholder’s consent. This functionality is applicable to both AUTH and PURS transactions with a CARD payment type.
The token creation has several stages and the merchant and the cardholder have some roles to play:
- In the checkout request the merchant allows the returning customer to save the card for future use and generates the card form with the “save card” option.
- The payment request carries the card data and the “save card” option requesting SIBS Gateway to process the payment and, on success, create a card token.
- The payment response returns a unique card token and PCI card data so the merchant can save it next to the customer data to user in payment based on card token.
How it works
Step 1: Create the order
The token creation process begins when you start creating the order, adding the following tokenization elements to the existing order body message.
Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments
Request Headers:
Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
Data Element
Type
Condition
Description
tokenisation
Tokenisation
Mandatory
Customer payment tokens. These tokens are provided at the end of a successful tokenization. Only present for Tokenization purposes.
tokenisationRequest
TokenisationRequest
Mandatory
Provided field on Checkout request to perform card tokenization.
tokeniseCard
Boolean
Mandatory
Indicates if a card tokenization is requested.
Example request including the tokenization information as follows:
Request:
{
"merchant": {
"terminalId": 24,
"channel": "web",
"merchantTransactionId": "Order Id: mg990kgc5c",
"transactionDescription": "transaction to create token",
"shopURL": "https://mytest.e-shop.pl/"
},
"transaction": {
"transactionTimestamp": "2023-05-23T07:54:20.418Z",
"description": "transaction statement description",
"moto": false,
"paymentType": "AUTH",
"amount": {
"value": 50.5,
"currency": "PLN"
},
"paymentMethod": [
"CARD"
]
},
"tokenisation": {
"tokenisationRequest": {
"tokeniseCard": true
}
}
}
Step 2: Generate the transaction
Note that the following request needs an Authorisation Header with the transactionSignature returned from checkout operation and createToken parameter set to true.
In this request, the Bearer Token is replaced by the checkout response transactionSignature.
At this step, it is necessary to add the following elements to the purchase:
Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/card/purchase
Request Headers:
Authorisation: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Data Element
Type
Condition
Description
cardInfo
CardInfo
Mandatory
Object that defines the payment operation request fields
PAN
string
Optional
secureCode
string
Mandatory
validationDate
ISODateTime
Mandatory
cardholderName
string
Mandatory
createToken
boolean
Mandatory
The request should contain:
"cardInfo": {
"PAN": "{{MCRegularCardNum}}",
"secureCode": "{{MCRegularCardCVV}}",
"validationDate": "{{MCRegularCardExpiry}}",
"cardholderName": "TKN {{trxDatetime}}",
"createToken": true
}
You should receive a successful technical response comprises of an HTTP-200 status, a returnStatus.statusCode=”000″ and, if the tokenisation succeeds, the token value, expiration date and masked card data.
The merchant must save the token value, expiration date and masked card data associated with the customer personal data (for example, associate with the user login data).
