Using 3DS to run transactions

You can enable 3DS (three-domain secure) using Nexio's ecommerce iframe or directly through the API.

For information about running transactions without 3DS, see Creating a card checkout page with the iframe, Creating a card checkout page with your own form, and Running a card transaction with the API.

For more information about 3DS, see the following pages:

Using 3DS with iframe

  1. Request a One-time-use Token

    Send a POST request to the ecommerce Create one-time-use token endpoint.

    Nexio recommends that you also send the appropriate paymentType value as part of the request. For more information, see Payment type (paymentType) in Constant transaction values.

    Example Request
    curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic [Base64_encoded_login]'
      -d '{
      "data": {
        "amount": 29.99,
        "currency": "USD",
      },
      "processingOptions": {
        "check3ds": true,
        "paymentType": "initialScheduled"
      }
    }'
    
    Example 200 Response
    {
      "expiration": "2018-09-18T15:43:05.664Z",
      "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
      "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
    }
    

  2. Load the Iframe

    Use the token from the response above to send a GET request to the Run card transaction with iframe endpoint:

    Example Request
    curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
      -H 'Accept: application/json' \
      -H 'One-time-use Token: API_KEY'
    

  3. Redirect and Complete the Transaction

    If the transaction requires 3DS authentication Nexio’s iframe will prompt shoppers to confirm they are being redirected for authentication.
    Upon confirmation, the iframe will open a new tab in which authentication will be completed.

    Once users have successfully authenticated, the transaction will be attempted.
    Upon completion, the response will be returned as a message to the browser.

    Example 200 Response
    {
      "amount": 34.25,
      "authCode": "035410",
      "card": {...},
      "currency": "USD",
      "data": {...},
      "gatewayResponse": {...},
      "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
      "kountResponse": {...},
      "merchantId": "100039",
      "token": {...},
      "transactionDate": "2019-01-15T13:19:39.329Z",
      "transactionStatus": "pending",
      "transactionType": "sale"
    }
    

    Notes:

    • The response schema will be the same as that of a standard POST request to the Run card transaction endpoint
    • The page does not generate a default confirmation page. We recommend using our response to create your own confirmation page

Using 3DS with Nexio API

  1. Post Transaction Information

    Send a POST request to the Run card transaction endpoint.
    Include the parameter processingOptions.customerRedirectUrl in the body of your request.
    This is the URL to which the shopper will be redirected after completing the 3DS authentication. Nexio recommends that you also send the appropriate paymentType value as part of the request. For more information, see Payment type (paymentType) in Constant transaction values.

    Example Request
    curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic [Base64_encoded_login]'
      -d '{
      "data": {},
      "tokenex": {
        "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
      },
      "processingOptions": {
        "customerRedirectUrl": "https://[your-ecommerce-website]",
        "check3ds": true,
        "paymentType": "initialScheduled"
      }
    }'
    

    If the payment requires 3DS authentication, Nexio's response will include a redirectUrl.

    Example 200 Response
    {
        "status": "redirect",
        "message": "Provide redirect url to shopper to complete 3ds authentication and transaction",
        "redirectUrl": "https://api.nexiopaysandbox.com/pay/v3/threeDS/frame?token=4c0e5734-63f6-4ada-9fc5-e632109e2a77"
    }
    

  2. Redirect the User

    Display the redirectUrl from the response above in a browser.
    Shoppers will be prompted to confirm they are being redirected for authentication.

  3. User Authenticates

    Once users have successfully authenticated, the transaction will be attempted.
    Upon completion, the user will be redirected to the customerRedirectUrl provided in step 1.
    The transaction id and status will be returned to the browser.

    Example 200 Response
    {
        "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
        "status": "pending"
    }
    

    Notes:

    • The response schema will be the same as that of a standard POST request to the Run card transaction endpoint.
    • The page does not generate a default confirmation page. We recommend using our response to create your own confirmation page.