Payment with 3DS Authentication
The 3-D Secure authentication protocol follows a three-domain model, in which the Acquirer Domain and Issuer Domain are linked by the Interoperability Domain. The primary objective of this model is to authenticate a cardholder during an e-commerce transaction or provide identity verification and account confirmation.
This protocol applies to customers who shop online at merchants with online stores that comply with 3D-Secure guidelines. For further information, please visit https://www.emvco.com/emv-technologies/3d-secure/.
The flow begins with a standard authorization or purchase flow, where the initial response to the POST /{id}/card/purchase request indicates that 3D-Secure authentication is required. This indication is provided in the form of a paymentStatus: “Partial,” followed by a new complex element called “actionResponse.”
3D-Secure authentications may occur automatically and seamlessly (Frictionless Flow) or require explicit authentication by the customer on their issuer’s platform (Challenge Flow).
How it works
To perform a payment with 3DS authorization, first create the order as detailed in API Integration Guide.
Then, you may proceed to Make the Payment.
Note that you should add the DeviceInfo object to the request message:
Data Element
Type
Condition
Description
deviceInfo
DeviceInfo
Mandatory
Object that defines the customer device information.
browserAcceptHeader
string
Optional
Browser Accept Header
browserJavaEnabled
string
Optional
Browser Java Enabled
browserJavascriptEnabled
string
Optional
Browser Javascript Enabled
browserLanguage
string
Optional
Browser Language
browserColorDepth
string
Optional
Browser Color Depth
browserScreenHeight
string
Optional
Browser Screen Height
browserScreenWidth
string
Optional
Browser Screen Width
browserTZ
string
Optional
Browser Time Zone
browserUserAgent
string
Optional
Browser User Agent
systemFamily
string
Optional
System Family
systemVersion
string
Optional
System Version
systemArchitecture
string
Optional
System Architecture
deviceManufacturer
string
Optional
Device Manufacturer
deviceModel
string
Optional
Device Model
deviceID
string
Optional
Device Unique Identification
applicationName
string
Optional
Application Name
applicationVersion
string
Optional
Application Version
geoLocalization
string
Optional
Geolocation
ipAddress
string
Optional
IP Address
After that, 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.
For the Frictionless Flow you will not receive a “Partial” PaymentStatus and you should proceed to perform the Get Status.
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
In this purchase request, add the ActionProcessed object as shown below:
Data Element
Type
Condition
Description
actionProcessed
ActionProcessed
Optional
id
string
Mandatory
type
string
Mandatory
Possible values are (“THREEDS_METHOD”, “THREEDS_CHALLENGE”, “DCC”, “INSTALLMENTS”).
executed
boolean
Mandatory
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": "Diogo M"
},
{
"key": "customerEmail",
"value": "{{CustomerEmail}}"
}
]
},
"cardInfo": {
"PAN": "{{MC3DSCardNum}}",
"secureCode": "{{MC3DSCardCVV}}",
"validationDate": "{{MC3DSCardExpiry}}",
"cardholderName": "TKN {{trxDatetime}}",
"createToken": 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.
A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.
If the payment status is ‘Partial’, proceed as before, 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>’
