Skip to content

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:

  1. 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.
  2. 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.
  3. 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).