External 3DS for 3DS2.0 - Developer Centre

Introduction

You can pass the External 3D Secure Authentication object to Payments API to process online CNP purchase requests. You will use your own integration with 3DS provider such as Cardinal Commerce to get Authentication details. You will run Liability shift rules at your end to decide whether to proceed with the transaction and accordingly you will pass the Authentication object to Payments API.

Steps in External 3D Secure

APIs to use: Payment Handles + Payments

Do the following:

1. Create a Payment Handle. You have to pass the "authentication" object in the payment handle request.
   • For 3DS2.0, below is the "authentication" object structure

     3DS2.0 authenticaton object structure

     • Json

     "authentication": {
         "eci": 6,
         "cavv": "Y2FyZGluYWxjb21tZXJjZWF1dGg=",
         "threeDResult": "A",
         "threeDSecureVersion": "2.1.0",
         "directoryServerTransactionId": "faf2069e-d630-4625-948a-e0479c278af1"
       }

   • For 3DS1.0 Fallback cases in 3DS2.0, below is the "authentication" object structure

     3DS1.0 Fallback cases in 3DS2.0 object stricture

     • Json

     "authentication": {
        "eci": "5",
        "cavv": "AAABAWFlmQAAAABjRWWZEEFgFz8=",
        "xid": "Smg5UFcyYWF6TkowUlRsaUxvNTA=",
        "threeDResult": "Y",
        "signatureStatus": "Y",
        "threeDSecureVersion": "1.0.2"
      }

   • Below is paymenthandle request.

     paymenthandle request

     • Json

     {
       "merchantRefNum": "c2aff8e6-6265-4631-b186-1fcd2abd7978",
       "transactionType": "PAYMENT",
       "accountId": "1009688230",
       "authentication": {
         "eci": 6,
         "cavv": "Y2FyZGluYWxjb21tZXJjZWF1dGg=",
         "threeDResult": "A",
         "threeDSecureVersion": "2.1.0",
         "directoryServerTransactionId": "faf2069e-d630-4625-948a-e0479c278af1"
       },
       "card": {
         "cardNum": "4037112233000001",
         "cardExpiry": {
           "month": 12,
           "year": 2025
         },
         "cvv": "111",
         "holderName": "Dilip"
       },
       "paymentType": "CARD",
       "amount": 900,
       "currencyCode": "USD",
       "customerIp": "172.0.0.1",
       "billingDetails": {
         "nickName": "Home",
         "street": "100 Queen",
         "street2": "Unit 201",
         "city": "Toronto",
         "zip": "M5H 2N2",
         "country": "CA"
       },
       "merchantDescriptor": {
         "dynamicDescriptor": "OnlineStore",
         "phone": "12345678"
       },
       "returnLinks": [
         {
           "rel": "on_completed",
           "href": "https://usgaminggamblig.com/payment/return/success",
           "method": "GET"
         },
         {
           "rel": "on_failed",
           "href": "https://usgaminggamblig.com/payment/return/failed",
           "method": "GET"
         },
         {
           "rel": "default",
           "href": "https://api.qa.paysafe.com/checkout/v2/pages/redirect-success.html",
           "method": "GET"
         }
       ]
     }

2. In Paymenthandle API response, you will get "paymentHandleToken" which will be in Payable state.
3. Use the paymentHandleToken to process the Payment request via Payments API using the private key. You must initiate a POST request to the endpoint:
   • Post:paymenthub/v1/payments