Menu
Menu
Go Back

Store Card Details – First Payment

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 / Checkout Request, as shown below:

Location

Data Element

Type

Condition

Description

Request Body.transaction.oneClick

customerAcceptance

boolean

Mandatory

Indicates 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 Body.tokenisation

tokenisationRequest

TokenisationRequest

Conditional

Provided field on Checkout request to perform card tokenization. 

Request Body.tokenisation.tokenisationRequest

tokeniseCard

Boolean

Optional

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

Location

Data Element

Type

Condition

Description

Request Body.info

deviceInfo

DeviceInfo

Mandatory

Object that defines the customer device information.

Request Body.info.deviceInfo

browserAcceptHeader

string

Optional

Browser Accept Header

Request Body.info.deviceInfo

browserJavaEnabled

string

Optional

Browser Java Enabled

Request Body.info.deviceInfo

browserJavascriptEnabled

string

Optional

Browser Javascript Enabled

Request Body.info.deviceInfo

browserLanguage

string

Optional

Browser Language

Request Body.info.deviceInfo

browserColorDepth

string

Optional

Browser Color Depth

Request Body.info.deviceInfo

browserScreenHeight

string

Optional

Browser Screen Height

Request Body.info.deviceInfo

browserScreenWidth

string

Optional

Browser Screen Width

Request Body.info.deviceInfo

browserTZ

string

Optional

Browser Time Zone

Request Body.info.deviceInfo

browserUserAgent

string

Optional

Browser User Agent

Request Body.info.deviceInfo

systemFamily

string

Optional

System Family

Request Body.info.deviceInfo

systemVersion

string

Optional

System Version

Request Body.info.deviceInfo

systemArchitecture

string

Optional

System Architecture

Request Body.info.deviceInfo

deviceManufacturer

string

Optional

Device Manufacturer

Request Body.info.deviceInfo

deviceModel

string

Optional

Device Model

Request Body.info.deviceInfo

deviceID

string

Optional

Device Unique Identification

Request Body.info.deviceInfo

applicationName

string

Optional

Application Name

Request Body.info.deviceInfo

applicationVersion

string

Optional

Application Version

Request Body.info.deviceInfo

geoLocalization

string

Optional

Geolocation

Request Body.info.deviceInfo

ipAddress

string

Optional

IP Address

Request Body

oneClick

oneClick

Optional

Object that defines a One Click Payment.

Request Body.oneClick

oneClickCreation

boolean

Mandatory

For 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
    }
}
mssg_bell

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

Location

Data Element

Type

Condition

Description

Request Body

actionProcessed

ActionProcessed

Optional

Request Body.ActionProcessed

id

string

Optional

Request Body.ActionProcessed

type

string

Optional

Possible values are (“THREEDS_METHOD”, “THREEDS_CHALLENGE”, “DCC”, “INSTALLMENTS”).

Request Body.ActionProcessed

executed

boolean

Optional

Request Body

oneClick

OneClick

Optional

Object that defines a One Click Payment.

Request Body.oneClick

oneClickCreation

boolean

Mandatory

For One Click creation. Indicates if customer requests the One Click Payment creation. The absence indicates the value ‘False’.

	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

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
    },
    "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 step 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