Back

Server to Server - Cards 3D-Secure

Card payments are available for Visa and Mastercard cards, using a token or full card details.

Card payments flow may differ slightly depending on the exact use case:

  • One time purchase (learn more...)
  • Payment authorisation and subsequent charge only upon order delivery (total or partial) (learn more...)
  • Payment authorisation with 3DS authentication (frictionless or challenged)
  • Payment based on card token (learn more...)
  • Recurring, merchant initiated payment (learn more...)

How it Works

Flow - Payment with 3D-Secure authentication

The 3-D Secure authentication protocol is based on a three-domain model where the Acquirer Domain and Issuer Domain are connected by the Interoperability Domain for the purpose of authenticating a Cardholder during an e-commerce transaction or to provide identity verification and account confirmation.

This protocol applies to those who shop online at merchants who have online stores and adhere to 3D-Secure. For more details: https://www.emvco.com/emv-technologies/3d-secure/

This flow starts off as a regular authorisation or purchase flow, where the initial response to the POST /{id}/card/purchase will provide an indication that a 3D-Secure authentication is required. That indication is provided in the form of a paymentStatus: "Partial", followed by a new complex element - actionResponse.

3D-Secure authentications may be automatic and seamless (Frictionless) or require that the customer explicitly authenticates in his issuer's platform (Challenged).
Either way

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 data, where you should include the payment type, amount, currency and payment methods allowed.

If already sure that only Card payment is required, then only include "CARD" in the transaction.paymentMethod list.

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": "AUTH",

"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 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.
Next the transaction has to be generated:

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

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

Example:

Authorization: Digest {transactionSignature}

Request URL:

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

Request Headers:

Authorization: Digest {transactionSignature}

Request Body:


Expected Response

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

The paymentStatus in the response informs on whether the transaction itself was declined or requires additional action to be taken.

  • Declined: The authorisation has been declined.
  • Partial: The authorisation 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.

The paymentStatus: "Partial" indicates that an additional request for 3DS authentication 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.

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

}

]

}

}


For more info check API Market


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

Redirect the cardholder to the ACS for 3DS authentication

The customer's browser must then be redirected via POST to the 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.

INCLUDE JS EXAMPLE HERE

POST "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample"

creq: eyJ0aHJlZURTU(...)

Resubmit the transaction for final authorization

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

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

Example:

Authorization: Digest {transactionSignature}

Request URL:

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

Request Headers:

Authorization: Digest {transactionSignature}

Request Body:


Expected Response

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

The paymentStatus in the response informs on whether the transaction itself was declined, processed successfully, or requires yet another action.

  • Success: The authorisation has been accepted.
  • Declined: The authorisation has been declined.
  • Partial: The authorisation is still partially accepted, and requires another action to the completed (e.g. 3D-Secure authentication retry). Again, the actionResponse element provides instructions on how to proceed.

If getting a paymentStatus: "Partial" proceed as before:

  • Redirect the cardholder to actionResponse.data.url using all actionResponse.data.params
  • Save the actionResponse.id for using later when reposting the payment
Finally you may perform a Get Status

Once the payment has been completely processed, you can check the status of your transaction making a GET request.

The Authorization 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

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