Authentication

Overview

This guide provides a comprehensive resource for implementing 3D Secure (3DS) authentication with Tap Payments, a security protocol that adds an extra layer of authentication to online credit and debit card transactions to reduce fraud and enhance customer trust. It details how Tap Payments handles 3DS authentication, including both internal processing (where Tap manages the authentication flow) and external authentication (where merchants provide pre-existing 3DS data). The guide explains how to integrate third-party authentication with Tap’s API by including an authentication object in the request body for the Charge or Authorize APIs, enabling seamless compatibility with external systems.

What is 3DS Authentication?

3DS Authentication adds a step where the cardholder verifies their identity with their issuing bank during an online transaction, typically via a password, PIN, or biometric method. Tap Payments supports this to comply with security standards and to protect against unauthorized transactions.

How It Works

Tap Payments’ 3DS implementation involves:

• Initiation: The merchant initiates a payment with 3DS enabled.
• Authentication: The cardholder is redirected to their bank’s authentication page (or it occurs within an iframe, depending on Tap’s flow).
• Verification: The bank authenticates the cardholder and returns a result.
• Completion: Tap processes the payment based on the authentication outcome.

3DS authentication can be handled in two ways:

• Internal Authentication: All Customer-initiated Transaction (CIT) transactions are 3DS enforced as true by default, Tap Payments handles the entire 3DS authentication process internally without requiring merchants to include additional objects in the request.

• External Authentication: Merchants can include an authentication object in the payment request body for (Charge APIs or Authorize APIs) to provide specific 3DS parameters, such as the Electronic Commerce Indicator (ECI), authentication token, and transaction identifiers. This approach allows merchants to pre-supply authentication details, streamlining the process when integrating with external systems like Google Pay or other payment providers.

Internal Authentication

All Customer-initiated Transaction (CIT) transactions are 3DS enforced as true by default, Tap Payments handles the entire 3DS authentication process internally without requiring merchants to include additional objects in the request. When the threeDSecure flag is set to true, Tap automatically coordinates with the cardholder’s issuing bank to complete the authentication, directing the customer to the bank’s authentication page or iframe as needed. For detailed information on merchant-initiated transactions, refer to the Merchant-initiated Transaction (MIT) docs.

External Authentication

Merchants can include an authentication object in the payment request body for (Charge APIs or Authorize APIs) to provide specific 3DS parameters, the authentication object in the API response provides critical details about the 3DS authentication outcome. This object can also be included in the request body for external authentication to specify 3DS parameters. Here’s an explanation of its fields:

Example Authentication Object

{
  "authentication": {
                "version": "3DS2",
                "acsEci": "02",
                "authentication_token": "kBOpcLYk1LgtmTJklvMrTmghbuWo",
                "transaction_id": "e568f7d7-63f1-4b56-9cce-49dca7bbc965",
                "protocol_version": "2.2.0",
                "transaction_status": "Y",
                "ds_transaction_id": "ec29dea6-3ebb-47cc-86f2-18e1b7adfefe",
                "threeds_server_transaction_id": "ec29dea6-3ebb-47cc-86f2-18e1b7adfefe"
            },
}

Initiating Charges with the Authentication Object

Initiate a Payment Request

Merchants can also include anauthentication object in the request body to provide additional 3DS details, such as the Electronic Commerce Indicator (ECI), authentication token, and transaction identifiers, to streamline the authentication process. Tap Payments will automatically determine whether 3DS authentication is required based on the card type and merchant configuration.

Example Request (Charge API)

curl --request POST \
     --url https://api.tap.company/v2/charges/ \
     --header 'Authorization: Bearer sk_test_XKokBfNWv6FIYuTMg5sLPjhJ' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 1,
  "currency": "KWD",
  "customer_initiated": true,
  "threeDSecure": true,
  "save_card": false,
  "description": "Test Description",
  "metadata": {
    "udf1": "Metadata 1"
  },
  "receipt": {
    "email": false,
    "sms": false
  },
  "reference": {
    "transaction": "txn_01",
    "order": "ord_01"
  },
  "customer": {
    "first_name": "test",
    "middle_name": "test",
    "last_name": "test",
    "email": "[email protected]",
    "phone": {
      "country_code": 965,
      "number": 51234567
    }
  },
  "merchant": {
    "id": "1234"
  },
  "source": {
    "id": "token_id"
  },
  "authentication": {
        "version": "3DS2",
        "acsEci": "02",
        "authentication_token": "kBOpcLYk1LgtmTJklvMrTmghbuWo",
        "transaction_id": "e568f7d7-63f1-4b56-9cce-49dca7bbc965",
        "protocol_version": "2.2.0",
        "transaction_status": "Y",
        "ds_transaction_id": "ec29dea6-3ebb-47cc-86f2-18e1b7adfefe",
        "threeds_server_transaction_id": "ec29dea6-3ebb-47cc-86f2-18e1b7adfefe"
    },
  "post": {
    "url": "http://your_website.com/post_url"
  },
  "redirect": {
    "url": "http://your_website.com/redirect_url"
  }
}
'

Initiating an Authorize with the Authentication Object

Example Request (Authorize API)

The request includes merchant details, amount, currency, customer information, and an optionalauthentication object to specify 3DS parameters.

curl --request POST \
     --url https://api.tap.company/v2/authorize/ \
     --header 'Authorization: Bearer sk_test_XKokBfNWv6FIYuTMg5sLPjhJ' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 1,
  "currency": "KWD",
  "customer_initiated": true,
  "threeDSecure": true,
  "save_card": false,
  "statement_descriptor": "sample",
  "receipt": {
    "email": true,
    "sms": true
  },
  "metadata": {
    "udf1": "test_data_1",
    "udf2": "test_data_2",
    "udf3": "test_data_3"
  },
  "reference": {
    "transaction": "txn_0001",
    "order": "ord_0001"
  },
  "customer": {
    "first_name": "Test",
    "middle_name": "Test",
    "last_name": "Test",
    "email": "[email protected]",
    "phone": {
      "country_code": "965",
      "number": "50000000"
    }
  },
  "merchant": {
    "id": "1234"
  },
  "source": {
    "id": "src_card"
  },
  "authorize_debit": false,
  "auto": {
    "type": "VOID",
    "time": 100
  },
  "authentication": {
        "version": "3DS2",
        "acsEci": "02",
        "authentication_token": "kBOpcLYk1LgtmTJklvMrTmghbuWo",
        "transaction_id": "e568f7d7-63f1-4b56-9cce-49dca7bbc965",
        "protocol_version": "2.2.0",
        "transaction_status": "Y",
        "ds_transaction_id": "ec29dea6-3ebb-47cc-86f2-18e1b7adfefe",
        "threeds_server_transaction_id": "ec29dea6-3ebb-47cc-86f2-18e1b7adfefe"
    },
  "post": {
    "url": "http://your_website.com/posturl"
  },
  "redirect": {
    "url": "http://your_website.com/redirecturl"
  }
}
'