Skip to main content

Handle 3D Secure payments

3D Secure (3DS) is used to authenticate the customer during an online transaction, adding a layer of security and reducing fraud risk. The core objective of the 3DS phase is to verify the cardholder's identity before the transaction is sent for authorization. Since virtual cards can be used for online/e-commerce payments (also known as a card-not-present scenario), 3DS is a standard requirement.

  • Merchant's choice: after a customer enters their card details (Card PAN, expiry, CVV) on a merchant's e-commerce site, the merchant triggers 3DS. There are also scenarios where the merchant chooses to skip 3DS, e.g. to reduce friction during checkout.
  • Open Fabric integration: through the card networks, Open Fabric receives the request to authenticate the cardholder and forwards this to you. You can set up one of the following two flows:
    • 3DS Out of Band (OOB) challenge flow This flow allows you to challenge the shopper through mobile authentication, such as through a push notification, PIN or biometric verification
    • 3DS OTP flow This flow allows you to send an OTP to the shopper, which the shopper can use on the e-commerce site to continue their purchase
  • Liability: if an online transaction has not passed 3DS, your cardholder is allowed to initiate a chargeback if the transaction turned out to be fraudulent. If you did challenge the cardholder with 3DS, the merchant can no longer be held liable.

3DS Out of Band (OOB) challenge flow​

This flow consists of two main parts for your integration:

  1. Receive OOB Challenge request: Open Fabric sends a POST request with transaction details and identifiers (three_ds_challenge_id, transaction_amount, tenant_account_ref, etc.) to your system. Your system responds with 202 Accepted, after which you can initiate challenging to the customer. You can design the authentication challenge yourself, e.g. you can choose to send a push notification to the customer.

    See API Reference for more details.

  2. Send OOB Challenge response: after the customer approves or declines the transaction, your system sends a POST request to the Open Fabric /v1/3ds/responses endpoint. The response must include the original identifiers and the challenge_result (approved or declined), including a reason if declined. Open Fabric confirms receipt with 202 Accepted.

    See API Reference for more details

Examples

Receive OOB Challenge request
{
  "three_ds_challenge_id": "ffec5b38-74db-485b-a67a-d19adb5777e8",
  "tenant_customer_ref": "CUST001",
  "customer_id": "f5fc485d-9016-4f32-8b49-44e1124a6abc",
  "tenant_account_ref": "FR1234567890",
  "account_id": "9703ac3d-ea7d-492c-9af8-7fabdf88874b",
  "static_token_id": "36f125c2-b215-4d19-a800-d0845d715350",
  "merchant_name": "Amazon.com",
  "transaction_amount": 20.39,
  "transaction_currency": "USD",
  "creation_time": "2024-08-19T07:52:31.812Z"
}
Send OOB Challenge response
{
  "three_ds_challenge_id": "ffec5b38-74db-485b-a67a-d19adb5777e8",
  "static_token_id": "36f125c2-b215-4d19-a800-d0845d715350",
  "tenant_customer_ref": "CUST001",
  "tenant_account_ref": "FR1234567890",
  "challenge_result": "approved",
  "creation_time": "2024-08-19T07:52:31.812Z"
}

3DS OTP flow​

The 3DS OTP flow is an authentication mechanism where Open Fabric requests your system to send a One-Time Password (OTP) to the customer for transaction verification. After receiving the request containing transaction details and the generated OTP, your system must then deliver this OTP to the customer (typically via SMS or email) and respond with a 202 Accepted to Open Fabric. Afterwards the customer can enter the OTP on the merchant's site and Open Fabric will verify it with the card network to complete the authentication.

See API Reference for more details.

tip

You can choose the delivery mechanism of the OTP yourself. For instance via SMS, Email, WhatsApp or your own environment. As SMS tends to be costly, take this into consideration when choosing your options.

Example

Receive Send OTP request
{
  "three_ds_challenge_id": "ffec5b38-74db-485b-a67a-d19adb5777e8",
  "tenant_customer_ref": "CUST001",
  "customer_id": "f5fc485d-9016-4f32-8b49-44e1124a6abc",
  "tenant_account_ref": "FR1234567890",
  "account_id": "9703ac3d-ea7d-492c-9af8-7fabdf88874b",
  "static_token_id": "36f125c2-b215-4d19-a800-d0845d715350",
  "merchant_name": "Amazon.com",
  "transaction_amount": 20.39,
  "transaction_currency": "USD",
  "authentication_credential": "768721",
  "creation_time": "2024-08-19T07:52:31.812Z"
}
Receive Send OTP response
{
  "three_ds_challenge_id": "ffec5b38-74db-485b-a67a-d19adb5777e8",
  "masked_email": "e******s@g*********m",
  "masked_phone_number": "********7890"
}