Menu

Tokenization

Merchants have the option to accommodate returning customers by offering the facility to save their card details for future use. However, this can only be done upon explicit request from the customer and with their explicit permission. This convenient feature is applicable to transactions involving the AUTH and PURS payment types when using a card as the payment method.

Step 1: Token creation

Action 1: Create the order
Action 2: Generate the transaction
Action 3: Perform a Get Status

The token creation has several actions, 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 a user in payment based on the card token.
Action 1: Create the order

The token creation process begins when you start creating an order, adding the following tokenization elements to the existent order body message.

Run in Postman

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 ElementTypeConditionDescription
tokenisationTokenisationMandatoryCustomer payment tokens. These tokens are provided at the end of a successful tokenization. Only present for Tokenization purposes.
tokenisationRequestTokenisationRequestMandatoryProvided field on Checkout request to perform card tokenization.
tokeniseCardBooleanMandatoryIndicates if a card tokenization is requested.

Example request including the tokenization information as follows:

{
    "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
        }
    }
}
Action 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:

Run in Postman

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
Content-Type: application/json
Data ElementTypeConditionDescription
cardInfoCardInfoMandatoryObject that defines the payment operation request fields.
PANStringMandatoryThe Primary Account Number (credit card number).
secureCodeStringOptionalThe security code (CVV/CVC) associated with the credit card.
validationDateISODateTimeMandatoryThe expiration date of the credit card.
cardholderNameStringMandatoryThe name of the cardholder as it appears on the credit card.
createTokenBooleanMandatoryA flag indicating whether to create a token for future use or not (true / false).

The request should contain:

"cardInfo": {
  "PAN": "{{MCRegularCardNum}}",
  "secureCode": "{{MCRegularCardCVV}}",
  "validationDate": "{{MCRegularCardExpiry}}",
  "cardholderName": "TKN {{trxDatetime}}",
  "createToken": true
}
Action 3: Perform a Get Status

You can check the status of your transaction by sending a GET request.

Ensure that the Authorization HTTP header is set to the same Bearer token that was used in the initial payment Order.

Run in Postman

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Request Headers:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Here are some examples of the possible result codes:

Result codestatusMsgDescriptionAction
HTTP-200SuccessSuccess response.N/A.
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many RequestsThe API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

Step 2: Token usage

Action 1: Create the order
Action 2: Generate the transaction
Action 3: Perform a Get Status

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:

  1. 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 token creation flow.
  2. The customer identifies the desired card from the list and inputs the card’s CVV (Card Verification Value).
  3. 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.

Action 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.

Run in Postman

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 ElementTypeConditionDescription
tokenisationTokenisationMandatoryCustomer payment tokens. These tokens are provided at the end of a successful tokenization. Only present for Tokenization purposes.
paymentTokensPaymentTokensMandatoryToken value tuple.
tokenTypeStringMandatoryToken Type.
Possible values are (
“Card”,
“Email”,
“MobilePhone” ).
valueStringMandatoryToken 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}}"
      }
    ]
  }
}

The response will contain only the valid tokens that can be used on the next action:

"tokenList": [
        {
            "tokenName": "TKN 2023-06-20T11:22:11.474Z",
            "tokenType": "Card",
            "value": "ODI2YWQ1MGEtMzhlNC00NjA2LTk2YTAtNjdjYTRjY2JiMDU2",
            "maskedPAN": "520474******4390",
            "expireDate": "2025-12-01T00:00:00.000Z",
            "oneClickButton": "false"
        }
Action 2: Generate the transaction

After that, the transaction must 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.

Run in Postman

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 ElementTypeConditionDescription
tokenInfoTokenInfoMandatoryToken Information.
valueStringMandatoryToken value.
secureCodeStringOptionalToken Secure Code.
tokenTypeStringMandatoryToken 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"
}
Action 3: Perform a Get Status

You can check the status of your transaction by sending a GET request.

Ensure that the Authorization HTTP header is set to the same Bearer token that was used in the initial payment Order.

Run in Postman

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Request Headers:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Result codestatusMsgDescriptionAction
HTTP-200SuccessSuccess response.N/A.
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many RequestsThe API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

On this page: