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.

Steps in 3D Secure

Payment Handles + Payments

You would typically do the following:

  1. 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": "{{currency}}",
        "customerIp": "172.0.0.1",
        "billingDetails": {
            "nickName": "Home",
            "street": "{{street}}",
            "city": "{{city}}",
            "state": "{{state}}",
            "country": "{{country}}",
            "zip": "{{zip}}"
        },
        "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"
            }
        ]
    }
  2. 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
    • SDK
    • 3RI
    This is the type of channel interface used to initiate the transaction.
  3. 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.

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

    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.
  8. 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.

  9. 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 Failed
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
Did you find this page useful?