Card on file without a purchase

Card on File without Purchase offers you the ability to securely store payment card details without the need to make an immediate purchase.

With this Account Cardholder Verification (ACV) you can conveniently save the card information on file for future use, enabling quick transactions when needed. This feature streamlines the process of adding and managing cards, providing you with flexibility and convenience while maintaining the highest standards of security.

Step 1: Token Creation

Action 1: Create the order

Action 2: Generate the transaction

Action 3: Perform a Get Status

To begin using this feature, you first need to create the token when you start creating the order.

This token creation step ensures that your sensitive information is protected while enabling seamless and swift transactions.

Action 1

When creating an order, you must include tokenization elements as shown below. Please note that the Account Cardholder Verification Process is only applicable for transactions with the “AUTH” paymentType. Additionally, ensure that the amount value is set to 0.

Request URL:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments

Request Headers:

Authorization: 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.

Request example:

Run in Postman

{
    "merchant": {
        "terminalId": {{TerminalID}},
        "channel": "web",
        "merchantTransactionId": "1283798132" // Id mocked
    },
    "transaction": {
        "transactionTimestamp": "{{trxDatetime}}",
        "description": "Transaction for order number 4908 terminalId 100886",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 0,
            "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:

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 Element	Type	Condition	Description
cardInfo	CardInfo	Mandatory	Object that defines the payment operation request fields.
PAN	String	Mandatory	The Primary Account Number (credit card number).
secureCode	String	Optional	The security code (CVV/CVC) associated with the credit card.
validationDate	ISODateTime	Mandatory	The expiration date of the credit card.
cardholderName	String	Mandatory	The name of the cardholder as it appears on the credit card.
createToken	Boolean	Mandatory	A flag indicating whether to create a token for future use or not (true/false).

The request should contain:

Run in Postman

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

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 code	statusMsg	Description	Action
HTTP-200	Success	Success response.	n/a.
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	On 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-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.	You should wait and try again later.

Step 2: Token usage

Action 1: Create an 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:

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.

Action 1: Create an 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:

Run in Postman

{
    "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}}"
      }
    ]
  }
}

Action 2: Generate the transaction

After that, the transaction has to be generated by 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:

Run in Postman

"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 code	statusMsg	Description	Action
HTTP-200	Success	Success response.	n/a.
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	On 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-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.	You should wait and try again later.

Card on file without a purchase

Step 1: Token Creation

Action 1: Create the order

Action 2: Generate the transaction

Action 3: Perform a Get Status

Action 1

Action 2: Generate the transaction

Action 3: Perform a Get Status

Step 2: Token usage

Action 1: Create an order

Action 2: Generate the transaction

Action 3: Perform a Get Status

Action 1: Create an order

Action 2: Generate the transaction

Action 3: Perform a Get Status

On this page: