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:

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

   {
       "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"
           }
       ]
   }

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: BROWSER APP THREERI	This is the type of channel interface used to initiate the transaction.

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
     • Json

     {
         "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.

3. 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.
4. Upon successful authentication, the merchant gets notified at the URL specified in the on_completed parameter included in Payment Handle request.
5. Upon failed authentication , the merchant gets notified at the URL specified in the on_failed parameter included in Payment Handle request
6. 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.
7. 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.

8. Use the paymentHandleToken to make Payments call.

Payment Handle Status

Mastercard

Visa

Amex