Token usage

For a returning customer, the option to pay with a previously tokenized card associated with their account on the merchant store can be made available, using either the AUTH or PURS method.

The token usage process can be illustrated through the following stages:

The merchant presents a list of available cards to the customer, displaying masked PAN (Partial Account Number) and expiration date. This information is provided by the service provider gateway (SPG) during the tokenization flow.
The customer identifies the desired card from the list and inputs the card’s CVV (Card Verification Value).
The merchant proceeds with the checkout and payment process, utilizing the selected tokenized card for the transaction.

This ensures a smooth transaction experience by securely utilizing the stored token for payment processing.

How it works

Step 1: Create the order

The token usage process is initiated when you begin creating the order, incorporating an additional token element within 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.

paymentTokens

PaymentTokens

Mandatory

Token value tuple.

tokenType

string

Mandatory

Token Type.
Possible values are (“Card”, “Email”, “MobilePhone”)

value

string

Mandatory

Token value.

Request example should contain the following “tokenisation” object to include the payment token:

{
 "merchant": {
 "terminalId": 24,
 "channel": "web",
 "merchantTransactionId": "Order Id: bwatdhbew2",
 "transactionDescription": "transaction with 3DS",
 "shopURL": "https://mytest.e-shop.pl/"
 },
 "transaction": {
 "transactionTimestamp": "2023-05-23T08:06:07.231Z",
 "description": "transaction statement description",
 "moto": false,
 "paymentType": "AUTH",
 "amount": {
 "value": 50.5,
 "currency": "PLN"
 },
 "paymentMethod": [
 "CARD"
 ]
},
"tokenisation": {
 "paymentTokens": [
 {
 "tokenType": "Card",
 "value": "{{tokenValue}}"  }
 ]
 }
}

Step 2: Generate the transaction

After that, the transaction has to be generated adding the tokeninfo element.

Note that the following request needs an Authorisation Header with the transactionSignature returned from checkout operation.

In this request, the Bearer Token is replaced by the checkout response transactionSignature.

Request URL: 
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/token/purchase
Request Headers:
Authorisation: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json

Data Element

Type

Condition

Description

tokenInfo

TokenInfo

Mandatory

Token Information.

value

string

Mandatory

Token value.

secureCode

string

Optional

Token Secure Code.

tokenType

string

Mandatory

Token Type.
Possible values are (“Card”, “Email”, “MobilePhone”).

Request example should contain the following “tokenInfo” object to include the necessary token information:

"tokenInfo": {
 "value": "{{tokenValue}}",
 "secureCode": "536", 
 "tokenType": "Card"
}