3DS

Introduction

The 3D Secure via Payments API can authenticate a cardholder for online transactions (card-not-present) requests. Through the Payments API, you can process mobile or browser-based transactions that are fully 3D Secure and SCA compliant.

Steps in 3D Secure

Perform the following steps:

Create a Payment Handle. You have to add "threeDs" object in request.

{

    "merchantRefNum": "58936a12-012d-49f4-ba56-a58ede19bff9",

    "transactionType": "PAYMENT",

    "threeDs": {

        "merchantUrl": "https://api.qa.paysafe.com/checkout/v2/index.html#/desktop",

        "deviceChannel": "BROWSER",

        "messageCategory": "PAYMENT",

        "transactionIntent": "GOODS_OR_SERVICE_PURCHASE",

        "authenticationPurpose": "PAYMENT_TRANSACTION"

    }

    "card": {

        "cardNum": "4000000000001091",

        "cardExpiry": {

            "month": 10,

            "year": 2025

        },

        "cvv": "111",

        "holderName": "Dilip"

    },

    "paymentType": "CARD",

    "amount": 500,

    "currencyCode": "USD",

    "customerIp": "172.0.0.1",

    "billingDetails": {

        "nickName": "Home",

        "street": "abcd",

        "city": "defg",

        "state": "AL",

        "country": "US",

        "zip": "32456"

    },

    "merchantDescriptor": {

        "dynamicDescriptor": "OnlineStoreeeeeeeee",

        "phone": "1234567899"

    },

    "returnLinks": [{

            "rel": "default",

            "href": "https://usgaminggamblig.com/payment/return/",

            "method": "GET"

        }, {

            "rel": "on_completed",

            "href": "https://usgaminggamblig.com/payment/return/success",

            "method": "GET"

        }, {

            "rel": "on_failed",

            "href": "https://usgaminggamblig.com/payment/return/failed",

            "method": "GET"

        }

    ]

}

3DS Object Parameters

Element	Type	Description
merchantUrl	string, Mandatory length =2048	This is the fully qualified URL of the merchant's commercial or customer care website
deviceChannel	enum, Mandatory, Possible Values: BROWSER APP THREERI	This is the type of channel interface used to initiate the transaction.
messageCategory	enum, Mandatory	This is the category of the message for a specific use case. Possible values are: PAYMENT NON_PAYMENT
authenticationPurpose	enum, Mandatory	This is a type of authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request. Possible values are: PAYMENT_TRANSACTION RECURRING_TRANSACTION INSTALMENT_TRANSACTION ADD_CARDMAINTAIN_CARD EMV_TOKEN_VERIFICATION

2. Paysafe returns a response with the following:

The action parameter is set to REDIRECT (as 3Dsecure is enabled)
- "action": "REDIRECT"
A payment_redirect link points to the 3D Secure authentication URL

{

    "id": "81f04f91-7894-4a24-8720-7cb073a360c0",

    "paymentType": "CARD",

    "paymentHandleToken": "SCGtj9C3K6vNxWMm",

    "merchantRefNum": "58936a12-012d-49f4-ba56-a58ede19bff9",

    "currencyCode": "USD",

    "txnTime": "2021-11-15T11:55:57Z",

    "billingDetails": {

        "nickName": "Home",

        "street": "TEST",

        "city": "CA",

        "zip": "12345",

        "state": "CA",

        "country": "US"

    },

    "customerIp": "172.0.0.1",

    "status": "INITIATED",

    "links": [

        {

            "method": "GET",

            "rel": "redirect_payment",

            "href": "https://api.qa.paysafe.com/cardadapter/v1/authentication/app/index.html?id=81f04f91-7894-4a24-8720-7cb073a360c0"

        }

    ],

    "amount": 500,

    "action": "REDIRECT",

    "usage": "SINGLE_USE",

    "timeToLiveSeconds": 299,

    "transactionType": "PAYMENT",

    "executionMode": "SYNCHRONOUS",

    "card": {

        "cardExpiry": {

            "month": "10",

            "year": "2025"

        },

        "holderName": "Dilip",

        "cardType": "VI",

        "cardBin": "400000",

        "lastDigits": "1091",

        "cardCategory": "CREDIT"

    },

    "merchantDescriptor": {

        "dynamicDescriptor": "OnlineStoreeeeeeeee",

        "phone": "1234567899"

    },

    "returnLinks": [

        {

            "rel": "default",

            "href": "https://usgaminggamblig.com/payment/return/",

            "method": "GET"

        },

        {

            "rel": "on_completed",

            "href": "https://usgaminggamblig.com/payment/return/success",

            "method": "GET"

        },

        {

            "rel": "on_failed",

            "href": "https://usgaminggamblig.com/payment/return/failed",

            "method": "GET"

        }

    ],

    "skip3ds": false,

    "threeDs": {

        "merchantUrl": "https://api.qa.paysafe.com/checkout/v2/index.html#/desktop",

        "deviceChannel": "BROWSER",

        "messageCategory": "PAYMENT",

        "transactionIntent": "GOODS_OR_SERVICE_PURCHASE",

        "authenticationPurpose": "PAYMENT_TRANSACTION"

    }

}

For all cases of 3DS2.0 (including Frictionless Authentication), you will always receive Redirection URL in Payment Handle Response.
Redirection URL and Payment Handle token remains valid for 299 seconds.

Redirect the customer to the 3D Secure authentication URL.
- If it is Frictionless Authentication case then user will be redirected on_completed URL
- For other cases, user will be shown 3DS authentication page.
Upon successful authentication, the merchant gets notified at the URL specified in the on_completed parameter included in Payment Handle request.
Upon failed authentication , the merchant gets notified at the URL specified in the on_failed parameter included in Payment Handle request
Below are the statuses of Payment Handle.
- INTIATED on creation
- PAYABLE on successful authentication. You can make Payment Request only if Payment Handle is Payable.
- FAILED on failed authentication
- EXPIRED after 299 seconds from INITIATED
How to know if Payment handle is Payable?
- You will receive a webhook when Payment Handle becomes Payable.
- If user is redirected to "on_completed" URL then Payment Handle will be Payable. You send "on_completed" URL as a part of Payment Handle request.
- You can do a GET call on Payment Handle ID received in Payment Handle response.
Use the paymentHandleToken returned in response to process the Payment request.
Use the paymentHandleToken to make Payments call

Payment Handle Status

Mastercard

ThreeDResult	ECI	CAVV	Authentication Experience	Liability (for disputed transaction or chargebacks)	Recommended Action	Payment Handle
A - Authentication attempted	1	Present	Frictionless	Card Issuer	Proceed to Card Authorization	Payable
N - Authentication failed	0	Not Present	Challenge/Frictionless	Merchant	Do not proceed with the transaction	Failed
R - Authentication rejected	0	Not Present	Frictionless	Merchant	Do not proceed with the transaction	Failed
U - Authentication unavailable	0	Not Present	Challenge/Frictionless	Merchant	Do not proceed with the transaction	Failed
Y - Authentication successful	2	Present	Challenge/Frictionless	Card Issuer	Proceed to Card Authorization	Payable

Visa

ThreeDResult	ECI	CAVV	Authentication Experience	Liability (for disputed transaction or chargebacks)	Recommended Action	Payment Handle
Y - Authentication successful	5	Present	Challenge/Frictionless	Card Issuer	Proceed to Card Authorization	Payable
A - Authentication attempted	6	Present	Frictionless	Card Issuer	Proceed to Card Authorization	Payable
N - Authentication failed	7	Not Present	Challenge/Frictionless	Merchant	Do not proceed with the transaction	Failed
U - Authentication unavailable	7	Not Present	Challenge/Frictionless	Merchant	Do not proceed with the transaction	Failed
R - Authentication rejected	7	Not Present	Frictionless	Merchant	Do not proceed with the transaction	Failed

Amex

ThreeDResult	ECI	CAVV	Authentication Experience	Liability (for disputed transaction or chargebacks)	Recommended Action	Payment Handle
Y - Authentication successful	5	Present	Challenge/Frictionless	Card Issuer	Proceed to Card Authorization	Payable
A - Authentication attempted	6	Present	Frictionless	Card Issuer	Proceed to Card Authorization	Payable
N - Authentication failed	7	Not Present	Challenge/Frictionless	Merchant	Do not proceed with the transaction	Failed
U - Authentication unavailable	7	Not Present	Challenge/Frictionless	Merchant	Do not proceed with the transaction	Failed
R - Authentication rejected	7	Not Present	Frictionless	Merchant	Do not proceed with the transaction	Failed

Was this page helpful?

On this Page

Introduction
Steps in 3D Secure
3DS Object Parameters
Payment Handle Status

Search Overlay

3DS

Mastercard

­­­Visa

Amex

Was this page helpful?

Thank you for your response!

Visa