Search Overlay

Using an external 3DS service for 3DS 2.0

Introduction

You may use your preferred external 3D Secure service when processing online payments (card-not-present) with us if you already have one. This service allows the Paysafe Payment API  to accept purchase and authorization transactions where 3D Secure verification check is performed externally using an external MPI. By running Liability Shift rules at your end, you decide whether to proceed with the transaction, and accordingly, you pass the Authentication object to Payments API.

 

Steps in External 3D Secure

Perform the following steps:

  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

"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 structure
"authentication": {
"eci": "5",
"cavv": "AAABAWFlmQAAAABjRWWZEEFgFz8=",
"xid": "Smg5UFcyYWF6TkowUlRsaUxvNTA=",
"threeDResult": "Y",
"signatureStatus": "Y",
"threeDSecureVersion": "1.0.2"
}

Payment Handle Request

{
"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"
}
]
}
  1. In Paymenthandle API response, you will get "paymentHandleToken" which will be in Payable state.
  2. 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

A Payment Handle can be used in a payment request only if it has the status of PAYABLE.