3DS 2.0 with Payments API

This guide describes how to implement 3D Secure 2.0 (3DS2 or 3DS 2.0) with our Payments API.

Using Payvision's Integrated 3DS Server

  • Merchants using Payments API with Pavision's integrated 3DS Server can choose between the Full-redirect and Embedded 3DS 2.0 flows.
  • For both options, Payvision minimizes the complexity for merchants and consumers. It handles the browser data collection and facilitates the frictionless, challenge or downgrade-to-3DS 1.0 flow, after which it processes the authorization as described in 3D Secure 2.0 workflow with Payvision
  • We recommend the Embedded 3DS 2.0 flow for a better customer experience as it avoids an additional redirection to collect the browser data and render the authentication challenge (if applicable).

Full-redirect flow

This flow consists of redirecting the consumer to a URL in Payvision's domain to collect the browser data, complete the challenge (if applicable) and process the authorization. Once the authorization is complete, the consumer will be redirected to the return page provided.

  1. The consumer enters their card information (card number, expiry date, etc.) and starts the payment process on the merchant's website.

  2. The merchant submits a Payment API request to AceHub with the card information as follows.

{
    "action": "authorize",
    "header": {
        "businessId": "{{YOUR_BUSINESS_ID}}"
    },
    "body": {
        "transaction": {
            "storeId": 1,
            "brandId": 1010,
            "trackingCode": "{{UNIQUE_ID}}",
            "amount": "1",
            "currencyCode": "EUR",
            "returnUrl": "https://merchant-website.com/paymentResult"
        },
        "card": {
            "number": "4000000000000002",
            "expiryMonth": "01",
            "expiryYear": "2022"
        },
        "customer": {
            "givenName": "John",
            "familyName": "Doe",
            "email": "[email protected]",
            "mobileNumber": "666777888"
        },
        "billingAddress": {
            "city": "Amsterdam",
            "street": "Molenpad",
            "countryCode": "NL",
            "zip": "1016GM",
            "houseNumber": "2"
        },
        "threeDSecure": {
            "version": "2.1.0"
        }
    }
}
  1. The Merchant receives a payment response from AceHub. The response contains a {redirect} block with {body.redirect.method} POST and {body.redirect.fields}.
{
  "result": 2,
  "description": "Pending",
  "header": {
    "requestTimestamp": "2020-01-24T08:54:32Z"
  },
  "body": {
    "card": {
      "expiryMonth": "1",
      "expiryYear": "2022",
      "firstSixDigits": "400000",
      "lastFourDigits": "0002"
    },
    "redirect": {
      "method": "POST",
      "url": "URL for collecting browser data",
      "fields": {
        "payload": "payload",
        "authUrl": "URL for authentication"
      }
    },
    "transaction": {
      "amount": 1,
      "currencyCode": "EUR",
      "action": "authorize",
      "id": "a51a5a57-75d2-41ee-8dc2-f4ef5cd0d7a3",
      "trackingCode": "131e0bf1-f43d-401b-a745-b6f3fab487b3",
      "brandId": 1010
    }
  }
}
{
  "result": -2,
  "description": "Failed",
  "header": {
    "requestTimestamp": "2020-02-04T14:05:05Z",
    "requestCode": "35cb2af9-dd13-4025-af94-faa92c846f9f"
  },
  "body": {
    "error": {
      "code": 1400,
      "message": "There is no authentication server configured.",
      "detailedMessage": "There is no authentication server configured."
    }
  }
}
  1. The merchant creates an HTML form with the key-value pairs in the {body.redirect.fields} as hidden form fields. This form should be submitted using POST to the URL in {body.redirect.url}. This will redirect the consumer to a page in the Payvision domain.
function postRedirectForm(redirectBlock) {
  const { fields = {}, method = 'POST', url = '', target = '_top' } = redirectBlock
  const form = document.createElement('form')
  form.setAttribute('method', method)
  form.setAttribute('action', url)
  form.setAttribute('target', target)
  for (const key of Object.keys(fields)) {
    const hiddenField = document.createElement('input')
    hiddenField.setAttribute('type', 'hidden')
    hiddenField.setAttribute('name', key)
    hiddenField.setAttribute('value', fields[key])
    form.appendChild(hiddenField)
  }
  document.body.appendChild(form)
  form.submit()
}
  1. AceHub takes care of requesting the exemption and facilitates the frictionless, challenge or downgrade-to-3DS 1.0 flow as described here. AceHub then proceeds to process the authorization.

  2. AceHub redirects the consumer to the {return_url} in the payment request.

  3. The Merchant can query the payment result with a GET Payment request.

Get the payment status

http://stagconnect.acehubpaymentservices.com/gateway/V3/payments/{{TRANSACTION_ID}}?businessId={{BUSINESS_ID}}
{
    "result": 0,
    "description": "Ok",
    "header": {
        "requestTimestamp": "2020-01-24T08:55:53Z"
    },
    "body": {
        "card": {
            "approvalCode": "386275",
            "cvvResult": "U",
            "expiryMonth": "1",
            "expiryYear": "2022",
            "firstSixDigits": "400000",
            "lastFourDigits": "0002"
        },
        "threeDSecure": {
            "enrollmentResult": "Y",
            "authenticationResult": "Y",
            "version": "2.0.0",
            "flow": "CHALLENGE"
        },
        "transaction": {
            "descriptor": "Name|city",
            "amount": 1,
            "currencyCode": "EUR",
            "action": "authorize",
            "id": "a51a5a57-75d2-41ee-8dc2-f4ef5cd0d7a3",
            "trackingCode": "131e0bf1-f43d-401b-a745-b6f3fab487b3",
            "brandId": 1010
        }
    }
}

Embedded flow

This flow offers a better customer experience by using our lightweight JavaScript library. This allows the merchant to avoid redirection of the customer from the merchant website to a URL in Payvision's domain for the customer's browser data collection and authentication.

With the embedded flow, the customer's browser data required for 3DS2 is collected within the merchant website by Payvision's JavaScript library. The authentication challenge (if applicable) is also rendered in the merchant's website. It requires minimal coding to integrate Payvision's JavaScript library.

Library setup

Install NPM package
Install Payvision 3DS 2.0 library from Payvision NPM repository

# with npm package manager
npm i @payvision/threedsecure2-library

# with yarn
yarn add @payvision/threedsecure2-library

Payvision CDN

Alternatively, the Payvision 3DS 2.0 library is also available from the Payvision CDN repository.

<html>
    <head>
        <script
            src="https://cdn.payvision.com/threedsecure2/1.1.3/threedsecure2-library.js"
            integrity="sha384-I1jv0U7t55Lh6EyDQNhEuo0U42TA+qNdFV1dOv2Ak2uivIDXWf7XEcA75rVZarDf"
            crossorigin="anonymous">
        </script>  
        <!-- your head definitions -->
    </head>
</html>

The initial steps of the embedded flow are identical to the full-redirection flow.

  1. The consumer's card details are collected by the merchant (step 1 from Full redirect flow.

  2. The merchant submits the payment request to AceHub (step 2 from Full redirect flow.

  3. The merchant gets a {redirect} object in AceHub response (step 3 from Full redirect flow.

  4. At this point, the embedded flow differs slightly from the full-redirection one. Instead of POSTing the redirect data form from the AceHub response (step 4 from Full redirect flow, the merchant must create an instance object of Payvision's JavaScript library and use this object to start the customer's data collection and authentication process by invoking authenticate method with {redirect} object.

async function handle3ds2() {
  try {
    // Step 4:
   /* The default is sandbox false, which should be used in PRODUCTION. 
    Sandbox can be set to true for STAGING*/
    const options = {sandbox:false}
    const threeDSecure2 = new ThreeDSecure2(options)
    const redirectResponse = await threeDSecure2.authenticate(redirect)
    // Step 5: 
    postRedirectForm(redirectResponse)
  } catch (e) {
    // Error handling
    // ...
  }
}

Please note that the merchant is responsible for handling any errors that may occur at the merchant's website.

  1. The authentication method returns a promise object. AceHub takes care of requesting the exemption and facilitates the frictionless, challenge or downgrade-to-3DS 1.0 flow as described here. AceHub then proceeds to process the authorization. In case of a Challenge, the library will handle the connection with 3DS Server and facilitate the Challenge flow in the Merchant's website.

  2. AceHub returns a new {redirect} object as a result of the authentication promise. With this object, the Merchant creates an HTML form with the key-value pairs in the {body.redirect.fields} as hidden form fields. This form should be submitted using POST to the URL in {body.redirect.url}. This will redirect the Consumer to the return url in the Merchant's domain.

  3. The Merchant can query the payment result with a GET Payment request.

Using an External 3DS Server

If you're authenticating with an external 3DS server, and wish to process the authorization via Payvision, the workflow is the same as 3DS 1.0. For 3DS 2.0, you'll need to additionally include the 3D Secure version and DSTransactionId (Mastercard only).

Steps:

  1. The consumer enters their card information (card number, expiry date, etc.) and starts the payment process on the merchant's website.
  2. The merchant performs the 3DS 2.0 authentication with an external 3DS Server.
  3. The merchant submits the payment to AceHub with the 3D Secure version and the 3DS 2.0 authentication data in the table below. During this step, it is possible to flag the applicable exemptions as described in the section How do you flag SCA exemptions? .
  4. The authorization is processed by AceHub and it returns a synchronous response.
  5. The merchant can query the payment result with a GET Payment request.

Required parameters with External 3DS Server

When using an external 3DS server, the following parameters must be provided in the ThreeDSecure block of the request:

Parameter name

Type

Description

threeDSecure.version

String

3D Secure version of the transaction. It should be in the format: '2.0.0'.

threeDSecure.eci

String

E-commerce indicator. Possible values:
00 - Internet Transaction (SecureCode)
01 - Authentication Attempted (SecureCode)
02 - Authenticated (SecureCode)
05 - Authenticated (VbV)
06 - Authentication Attempted (VbV)
07 - Internet Transaction (VbV)

The ThreeDSecure block must also contain one of the following parameters:

Parameter name

Type

Description

threeDSecure.avv

String

3D Secure Authentication verification value (CAVV or AAV), Base64 encoded.

threeDSecure.xid

String

3D Secure XID, Base64 encoded.

threeDSecure.dsTransactionId

String

Applicable for Mastercard. Unique transaction identifier assigned by the Directory Server to identify a single transaction.