3DS via Payments API
Introduction
You can use the 3D Secure via Payments API to authenticate a cardholder for online CNP purchase requests. This enables you to process mobile or browser-based transactions through the Payments API that are fully 3D Secure and SCA compliant.
Effective 15th October 2022, Visa, Mastercard and American Express will discontinue support for 3D Secure 1 and any transaction sent for Authentication with this version will result in an error. It is important to update your integration to 3D Secure 2 (EMV®3-D Secure) now if you are currently on 3D Secure 1 as deadlines are quickly approaching. Please refer to our ‘3D Secure 2’ Page for more information on what you can do to prepare your business: https://www.paysafe.com/en/3ds-2/
Steps in 3D Secure
APIs to use: Payment Handles + Payments
You would typically do the following:
- 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" }, "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" } ] }
- BROWSER
- APP
- THREERI
- 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 3DS1.0 and 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.
- The action parameter is set to REDIRECT (as 3Dsecure is enabled)
- 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.
A Payment Handle can be used in a payment request only if it has the status of PAYABLE.
- Use the paymentHandleToken to make Payments call.
threeDs Object Parameter
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: | This is the type of channel interface used to initiate the transaction. |
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 |