3DSecure Transactions

Introduction

In this guide, you will learn how to perform a transaction using the 3D Secure protocol. 3D Secure is an authentication system that adds an additional layer of security to online transactions. Through this protocol, card issuers and acquirers can authenticate the cardholder before processing the transaction.

Helping to protect your business and your money is one of our priorities. For this reason, we want to provide you with some security recommendations here.

Workflow

The process of a 3D Secure transaction with Wompi generally follows these steps:

1. Transaction initiation: The customer selects the products or services and proceeds to the payment process on your platform.
2. Redirect to authentication page: After entering the card details, the customer will be automatically redirected to the card issuer's authentication page.
3. Cardholder authentication: The card issuer will request the cardholder to enter a password or a unique verification code. This can be a password, a one-time password (OTP) code, or a fingerprint, depending on the implemented authentication method.
4. Transaction authorization: Once the cardholder has been successfully authenticated, the card issuer will generate a successful authentication message and send it to the acquirer.
5. Transaction processing: The acquirer receives the successful authentication message and proceeds to authorize the transaction. It verifies if there are sufficient funds in the cardholder's account and if the transaction complies with card limits and fraud rules.
6. Transaction confirmation: Once the transaction has been processed and successfully authorized, a confirmation will be displayed to the customer indicating that the transaction has been completed.

General information on 3D Secure for your business here and for your customer here.

Implementing 3D Secure on Your Platform

Requirements

Before you begin your deployment, make sure you have the following requirements:

• Authentication keys: In this section, we will only use the public key, which we will send as a Bearer token in the headers of the requests.
• Test data.
• Execution environment URLs (Sandbox).

Step 1. Get a pre-signed acceptance token.

Step 2. Tokenize your payment method (Card).

Step 3. Create the transaction:

To create a transaction we must make a POST /transactions request, with the following JSON body:

{
  "acceptance_token": "acceptance_token", // Generated in step 1
  "amount_in_cents": 100,
  "currency": "USD",
  "customer_email": "pepito_perez@example.com",
  "reference": "AHJDFDSFK184", // Unique value to identify the transaction
  "payment_method": {
    "type": "CARD",
    "token": "token" // Generated in step 2
  }
}

Note: To use external authentication servers, Wompi receives authorization data in the three_ds_auth_external_provider field as shown below:

{
  "acceptance_token": "acceptance_token", // Generated in step 1
  "amount_in_cents": 100,
  "currency": "USD",
  "customer_email": "pepito_perez@example.com",
  "reference": "AHJDFDSFK184", // Unique value to identify the transaction
  "payment_method": {
    "type": "CARD",
    "token": "token", // Generated in step 2
    "extra_three_ds_aut_external_provider": {
      "message_version": "{{VERSION}}",
      "trans_status": "{{VALID_VALUE_STATUS}}",
      "authentication_value": "{{AUTH_VALUE}}",
      "three_ds_server_trans_id": "{{SERVER_DIRECTORY}}"
    }
  }
}

Important: To be able to use third-party authorization servers, prior authorization must be requested.

We will get back the following JSON:

{
  "data": {
    "id": "1196-1688604884-42949",
    "amount_in_cents": 100,
    "reference": "AHJDFDSFK184",
    "currency": "USD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "bin": "497011",
        "name": "VISA-1029",
        "brand": "VISA",
        "exp_year": "29",
        "exp_month": "06",
        "last_four": "1029",
        "card_holder": "Pedro Pérez",
        "is_three_ds": false
      },
      "installments": 1
    },
    "status": "PENDING",
    "status_message": null,
    "billing_data": null,
    "shipping_address": null,
    "redirect_url": null,
    "payment_source_id": null,
    "payment_link_id": null,
    "customer_data": null,
    "bill_id": null,
    "taxes": []
  }
}

Step 4. Make periodic queries of the transaction to verify the status and ensure its correct execution.

Step 5. Render IFRAME to continue the authentication process:

We will observe that in the transaction, the payment_method key contains relevant additional information. Specifically, we will focus on the three_ds_method_data key, which includes an HTML code snippet. This is an IFRAME block that should be integrated and displayed on the page to securely carry out the card authentication process. Additionally, we will also find the current_step key, which indicates the current state of authentication and may refer to the specific type of authentication required to verify the cardholder's identity. Here is how these elements appear in the transaction response:

{
  "id": "1196-1688604884-42949",
  "created_at": "2023-07-06T00:54:50.207Z",
  "amount_in_cents": 100,
  "reference": "JSAGDF7329",
  "currency": "USD",
  "payment_method_type": "CARD",
  "payment_method": {
    "type": "CARD",
    "extra": {
      "name": "VISA-0031",
      "brand": "VISA",
      "last_four": "0031",
      "three_ds_auth": {
        "current_step": "BROWSER_INFO", // Refers to the type of authentication: (BROWSER_INFO - CHALLENGE)
        "current_step_status": "PENDING",
        "three_ds_method_data": "<iframe>...</iframe><form>...</form>" // HTML to be rendered for card authentication
      }
    },
    "installments": 1
  },
  "redirect_url": null,
  "status": "PENDING",
  "status_message": null,
  "merchant": {
    "name": "Tests SandBox",
    "legal_name": "Tests SandBox",
    "contact_name": "Pepito Perez",
    "phone_number": "+50732345634",
    "logo_url": null,
    "legal_id_type": "RUC",
    "email": "pepito@test.com",
    "legal_id": "2452345-5"
  },
  "taxes": []
}

Step 6. Don't forget to perform periodic queries of the transaction until it reaches a final status.

This is how an approved transaction looks like.

{
  "data": {
    "id": "1196-1689602000-65841",
    "created_at": "2023-07-17T13:53:24.308Z",
    "amount_in_cents": 100,
    "reference": "TEST34502",
    "currency": "USD",
    "payment_method_type": "CARD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "name": "VISA-0031",
        "type": "CAPTURE", // Indicates that the transaction is a capture
        "brand": "VISA",
        "last_four": "0031",
        "is_three_ds": false,
        "three_ds_auth": null,
        "external_identifier": "QtcGZjh9nX",
        "processor_response_code": "00"
      }
    },
    "redirect_url": null,
    "status": "APPROVED", // Final status of the transaction
    "status_message": null,
    "merchant": {
      "name": "Pruebas SandBox",
      "legal_name": "Pruebas SandBox",
      "contact_name": "Pepito Perez",
      "phone_number": "+50732345634",
      "logo_url": null,
      "legal_id_type": "RUC",
      "email": "prueba@test.com",
      "legal_id": "2452345-5"
    },
    "taxes": []
  }
}