Back

Server to Server - Tokenised Card

A returning customer can be allowed to save a card for later use if requested by the merchant and allowed by the cardholder. This applies to AUTH and PURS with CARD payment type.

The token creation has several steps 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

Flow - Card token creation

Use the one time purchase flow or the payment authorisation flow with tokenisation request so the card associated with the transaction is tokenised and, therefore, saved for future use for the same customer.

This page requires an SVG viewer.

See the World Wide Web Consortium (W3C) Web site for more information on SVG and available viewers.
Starting by creating the checkout

First, perform a server-to-server POST request, the same as Form Integration, to prepare the checkout with the required payment data and the tokenisation request.

The JSON of your POST body, can be composed of various Complex Types:

"merchant": {

"terminalId": {{terminalId}},

"channel": "web",

"merchantTransactionId": "{{mti}}"

"transactionDescription": "transaction short description"

"shopURL" : "https://mytest.e-shop.pl/"

}

For more info check API Market

"transaction": {

"transactionTimestamp": "Current Date",

"description": "transaction statement description",

"moto": false,

"paymentType": "PURS",

"amount": {

"value": 50.50,

"currency": "PLN"

},

"paymentMethod": [

"CARD",

]

}

For more info check API Market

"customer": {

"customerInfo": {

"customerName": "Client Name",

"customerEmail": "client.name@hostname.pt",

"shippingAddress": {

"street1": "Street address 1",

"street2": "Street address 2",

"city": "Lisbon",

"postcode": "1200-999",

"country": "PT"

},

"billingAddress": {

"street1": "Street address 1",

"street2": "",

"city": "Lisbon",

"postcode": "1200-999",

"country": "PT"

}

}

}

For more info check API Market

"recurringTransaction": {

"validityDate": "2022-09-28T17:37:31.4095147+00:00",

"amountQualifier": "DEFAULT",

"description" : "My transaction -> Order XPTO"

}

For more info check API Market

"tokenisation":{

"tokenisationRequest":{

"tokeniseCard":true

}

}

For more info check API Market


The response to a successful request is a JSON with a transactionID, which is required in the second step to create a transaction.

With the transactionID, will be present as well a transactionSignature that will be used on the following step

POST

Request URL:
/api/v1/payments
Request Headers:

Request Body:


Expected Response

A success response comprises of an HTTP-200 status, a transactionID and a transactionSignature

Any other HTTP status signals an unsuccessful request. The following statuses may occur:

  • HTTP-400 (Bad Request): The 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-401 (Unauthorized): The Authorisation: 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-403 (Forbidden): The 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-405 (Method Not Allowed): The HTTP Method used is not matching any of the API definitions available. Please check in API Market for the correct HTTP Method.
  • HTTP-429 (Too Many Requests): The API calls rate limit has been exceeded. Please check in API Market for information on the rate limits that apply to the API.
  • HTTP-500 (Internal Server Error): The 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-503 (Service Unavailable): The API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.
Next the transaction has to be generated:

Note that the following request needs an Authorisation Header with the transactionSignature returned from checkout operation and createToken parameter set to true.

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

Example:

Authorisation: Digest {transactionSignature}

Request URL:

/api/v1/payments/{transactionID}/card/purchase

Request Headers:

Authorisation: Digest {transactionSignature}

Request Body:


Expected Response

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

The paymentStatus in the response informs on whether the transaction itself was accepted, declined, still pending a final result, or requiring additional action to be taken.

  • Success: The purchase has been processed successfully and the customer has been debited. If the tokenisation info is present then the card token was successfully created
  • Declined: The purchase has been declined and the card has not been tokenised.
  • Pending: The final result of the purchase is not yet known. You will need to inquiry on the status of this transaction until it reaches a final state. If there is a token associated it will be returned in the response body.
  • Partial: The purchase is partially accepted, but requires additional actions to the completed (e.g. 3D-Secure authentication). The actionResponse element is provided for instructions on how to proceed.
Afterwards you can perform a Get Status

Once the payment has been processed or in doubt of the payment status, you can check the status of your transaction making a GET request. If there is a token associated it will be returned in the response body.

The Authorisation HTTP header is set to the Bearer token as it was used in the initial Checkout.

Request URL:
/api/v1/payments/{transactionID}/status
Request Headers:



What's Next

Present the saved card to the customer and perform a payment using the token.

or have a look at the other Card payment features you can use.