Skip to content

Storing card details

When a Merchant proposes a One Click Payment Creation to a logged-in Cardholder, the applicable Terms and Conditions are presented.

If the Cardholder accepts and provides their card data, they must perform 3D Secure Strong Customer Authentication as mandated. Once authentication is successful, the card is tokenized and registered with the International Payment System (IPS). The token is then delivered to the Merchant and recorded as a Card on File.

How it works

To perform a payment with 3DS authorization, first create the order as detailed in API Integration guide.

Note that you should include the additional OneClick and Tokenization parameters to the Order request, as shown below:

LocationData ElementTypeConditionDescription
Request Body.transactiononeClickOneClickMandatoryObject that defines a One Click Payment. Only present for Merchants with One Click Payment.
Request Body.transaction.oneClickcustomerAcceptanceBooleanMandatoryIndicates if Customer has accepted the One Click Payment Service Terms and Conditions, in order to continue with the payment.
Is set to ‘True‘ if One Click Payment Terms and Conditions were presented by Merchant and  explicitly accepted by Customer. Otherwise must set to ‘False‘. When not present, value ‘False’ must be assumed.
Request BodytokenisationTokenisationMandatoryCustomer payment tokens. This tokens are provided at the end of a successful tokenization. Only present for Tokenization purposes.
Request Body.tokenisationtokenisationRequestTokenisationRequestMandatoryProvided field on Checkout request to perform card tokenization. 
Request Body.tokenisation.tokenisationRequesttokeniseCardBooleanMandatoryIndicates if a card tokenization is requested.

Request example:

	{
	    "merchant": {
	        "terminalId": {{TerminalID}},
	        "channel": "web",
	        "merchantTransactionId": "Order Id: r7cxvi0saj"
	    },
	    "transaction": {
	        "transactionTimestamp": "{{trxDatetime}}",
	        "description": "Transaction for order number 4908 terminalId 100886",
	        "moto": false,
	        "paymentType": "PURS",
	        "amount": {
	            "value": 50.50,
	            "currency": "PLN"
	        },
	        "paymentMethod": [
	            "CARD"
	        ],
	        "oneClick": {
	            "customerAcceptance": true
	        }
	    },
	    "tokenisation": {
	        "tokenisationRequest": {
	            "tokeniseCard": true
	        }
	    }
	}

Then, you may proceed to make the payment.

You should include the additional DeviceInfo and OneClick parameters to the purchase request, as shown below.

LocationData ElementTypeConditionDescription
Request Body.infodeviceInfoDeviceInfoMandatoryObject that defines the customer device information.
Request Body.info.deviceInfobrowserAcceptHeaderStringOptionalBrowser Accept Header.
Request Body.info.deviceInfobrowserJavaEnabledStringOptionalBrowser Java Enabled.
Request Body.info.deviceInfobrowserJavascriptEnabledStringOptionalBrowser Javascript Enabled.
Request Body.info.deviceInfobrowserLanguageStringOptionalbrowser Language.
Request Body.info.deviceInfobrowserColorDepthStringOptionalbrowser Color Depth.
Request Body.info.deviceInfobrowserScreenHeightStringOptionalbrowser Screen Height.
Request Body.info.deviceInfobrowserScreenWidthStringOptionalbrowser Screen Width.
Request Body.info.deviceInfobrowserTZStringOptionalBrowser Time Zone.
Request Body.info.deviceInfobrowserUserAgentStringOptionalBrowser User Agent.
Request Body.info.deviceInfosystemFamilyStringOptionalSystem Family.
Request Body.info.deviceInfosystemVersionStringOptionalSystem Version.
Request Body.info.deviceInfosystemArchitectureStringOptionalSystem Architecture.
Request Body.info.deviceInfodeviceManufacturerStringOptionalDevice Manufacturer.
Request Body.info.deviceInfodeviceModelStringOptionalDevice Model.
Request Body.info.deviceInfodeviceIDStringOptionalDevice Unique Identification.
Request Body.info.deviceInfoapplicationNameStringOptionalApplication Name.
Request Body.info.deviceInfoapplicationVersionStringOptionalApplication Version.
Request Body.info.deviceInfogeoLocalizationStringOptionalGeolocation.
Request Body.info.deviceInfoipAddressStringOptionalIP Address.
Request BodyoneClickOneClickMandatoryObject that defines a One Click Payment.
Request Body.oneClickoneClickCreationBooleanMandatoryFor One Click creation. Indicates if customer requests the One Click Payment creation. The absence indicates the value ‘False‘.

Request example:

	{
	    "info": {
	        "deviceInfo": {
	            "browserAcceptHeader": "application/json, text/plain, */*",
	            "browserJavaEnabled": "false",
	            "browserLanguage": "en",
	            "browserColorDepth": "24",
	            "browserScreenHeight": "1080",
	            "browserScreenWidth": "1920",
	            "browserTZ": "-60",
	            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
	            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
	            "systemFamily": "Windows",
	            "systemVersion": "Windows",
	            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
	            "applicationName": "Chrome",
	            "applicationVersion": "106"
	        },
	        "customerInfo": [
	            {
	                "key": "customerName",
	                "value": "User X"
	            },
	            {
	                "key": "customerEmail",
	                "value": "testingemail@gmail.com"
	            }
	        ]
	    },
	    "cardInfo": {
	        "PAN": "{{MC3DSCardNum}}",
	        "secureCode": "{{MC3DSCardCVV}}",
	        "validationDate": "{{MC3DSCardExpiry}}",
	        "cardholderName": "TKN {{trxDatetime}}",
	        "createToken": true
	    },
	    "oneClick": {
	        "oneClickCreation": true
	    }
	}
Notification

When storing card details, it’s important to note that you’ll need to go through the Challenge Flow as outlined on the 3D Secure page. This process helps ensure the security of the stored information and protects against unauthorized use.

You will receive a response comprising a paymentStatus in the message. It informs whether the transaction was accepted, declined, still pending a final result, or requires additional action.

  • Success: The purchase has been processed successfully and the customer has been debited.
  • Declined: The purchase has been declined.
  • 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, or you decide to cancel it.
  • 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.

If the PaymentStatus received is “Partial“, it indicates that an additional request for 3DS authentication (Challenge Flow) needs to be POSTed, before resubmitting the Card payment request.

The response will also include an actionResponse element with information on how to proceed, as shown in the example below.

Save the actionResponse.id to use in the resubmission of the payment request once the 3DS authentication terminates.

Action response example:

"actionResponse": {
"id": "be9b2788-3061-467c-b2a5-a36ad17f085c",
"type": "THREEDS_CHALLENGE",
"data": {
"url": "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample",
"params": [
{
"name": "creq",
"data": "eyJ0aHJlZURTU(...)"
}
]
}
}

You must perform three additional actions:

Action 1: Redirect the cardholder to the ACS for 3DS Authentication
Action 2: Resubmit the Transaction for final authorization
Action 3: Perform a Get Status
Action 1: Redirect the cardholder to the ACS for 3DS Authentication

The customer’s browser must be redirected via POST to the 3DS Access Control Server (ACS) URL indicated by actionResponse.data.url using the actionResponse.data.params as request parameters.

The cardholder’s browser is redirected back to your origin once the authentication is finished.

Javascript example of redirection to ACS

POST "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample"
creq: eyJ0aHJlZURTU(...)
Action 2: Resubmit the Transaction for final authorization

Note that the following request needs an Authorization Header with the transactionSignature returned from payment order operation.

In this purchase request, include the additional ActionProcessed and the OneClick parameters, as shown below:

LocationData ElementTypeConditionDescription
Request BodyactionProcessedActionProcessedMandatory
Request Body.ActionProcessedidStringMandatory
Request Body.ActionProcessedtypeStringMandatoryPossible values are (
“THREEDS_METHOD”,
“THREEDS_CHALLENGE”, “DCC”,
“INSTALLMENTS” ).
Request Body.ActionProcessedexecutedBooleanMandatory
Request BodyoneClickOneClickMandatoryObject that defines a One Click Payment.
Request Body.oneClickoneClickCreationBooleanMandatoryFor One Click creation. Indicates if customer requests the One Click Payment creation. The absence indicates the value ‘False‘.

Request example:

Request URL:

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

Request Headers:

Authorization: ‘Digest <transactionSignature>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json
	    "info": {
	        "deviceInfo": {
	            "browserAcceptHeader": "application/json, text/plain, */*",
	            "browserJavaEnabled": "false",
	            "browserLanguage": "en",
	            "browserColorDepth": "24",
	            "browserScreenHeight": "1080",
	            "browserScreenWidth": "1920",
	            "browserTZ": "-60",
	            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
	            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
	            "systemFamily": "Windows",
	            "systemVersion": "Windows",
	            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
	            "applicationName": "Chrome",
	            "applicationVersion": "106"
	        },
	        "customerInfo": [
	            {
	                "key": "customerName",
	                "value": "User X"
	            },
	            {
	                "key": "customerEmail",
	                "value": "testingemail@gmail.com"
	            }
	        ]
	    },
	    "cardInfo": {
	        "PAN": "{{MC3DSCardNum}}",
	        "secureCode": "{{MC3DSCardCVV}}",
	        "validationDate": "{{MC3DSCardExpiry}}",
	        "cardholderName": "TKN {{trxDatetime}}",
	        "createToken": true
	    },
	    "oneClick": {
	        "oneClickCreation": true
	    },
	    "actionProcessed": {
	        "id": "{{actionId}}",
	        "type": "THREEDS_CHALLENGE",
	        "executed": true
	    }
	}

Expected response:

As we’ve seen before, the paymentStatus in the response informs on whether the transaction itself was declined, processed successfully, or requires yet another action.

If the payment status is “Partial“, you should follow the same steps as before, starting from Action 1.

Action 3: Perform a Get Status

After the payment has been fully processed, 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.

Request URL:

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

Request Headers:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

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 responseN/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 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-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.

What’s next?

Check the next step on the Paying with stored card page.