Integración de Transacciones con 3D Secure externo

Introduction

In this guide, you will learn how to integrate transactions with external 3D Secure using the Wompi API. Through this integration, you can offer your customers an additional layer of security during the payment process by using an external 3D Secure provider.

Important!

This guide is only for merchants that already have an external 3D Secure solution and want to integrate it with Wompi. If your merchant is not yet integrated with 3D Secure and you want to do it through Wompi, you can use the following guide to integrate 3DS with Wompi

Prerequisites

Before starting the implementation, make sure you have the following requirements:

• Authentication keys: In this section we will use only the public key, which we will send as a Bearer token in the request headers.
• Execution environment URLs.

---

Step 1. Obtain a pre-signed acceptance token.

Step 2. Tokenize the payment method (Card).

Step 3. Have at hand the 3D Secure authentication information provided by your external 3D Secure provider.

The structure of this information must comply with the following contract:

Field name	Data type	Required?
trans_status	string	✅ YES
three_ds_server_trans_id	string	✅ YES
message_version	string	✅ YES
authentication_value	string	✅ YES
eci	string	✅ YES

Or seen in JSON format:

{
  "trans_status": "Y",
  "three_ds_server_trans_id": "d873-abc123-ghr678...",
  "message_version": "2.0",
  "authentication_value": "BwABApFSYsssd4l2eQQFJjAAAAAAA=",
  "eci": "02"
}

Step 4. Create the transaction:

To create the transaction you must make a POST /transactions request with the following JSON body, including the 3D Secure information obtained in the previous step inside the extra_three_ds_aut_external_provider field which in turn goes inside the payment_method object:

{
  "acceptance_token": "acceptance_token", // Generated in step 1
  "amount_in_cents": 1000000,
  "currency": "COP",
  "customer_email": "pepito_perez@example.com",
  "reference": "AHJDFDSFK184", // Unique value to identify the transaction
  "payment_method": {
    "type": "CARD",
    "token": "token_val_12345...", // Generated in step 2
    "installments": 1, // Number of installments
    "extra_three_ds_aut_external_provider": { // 3DS information provided by the external provider
      "eci": "001",
      "trans_status": "Y",
      "message_version": "v1",
      "authentication_value": "g5f4d3s2a1",
      "three_ds_server_trans_id": "A1S2D3FG4H5"
    }
  },
  "is_three_ds": true // We indicate that 3D Secure is being used
  // other fields...
}

After making the POST request, you will receive back a JSON similar to the following:

{
  "data": {
    "id": "11854-1728506262-27959",
    "created_at": "2024-10-09T20:37:43.075Z",
    "finalized_at": null,
    "amount_in_cents": 1000000,
    "reference": "AHJDFDSFK184",
    "customer_email": "pepito_perez@example.com",
    "currency": "COP",
    "payment_method_type": "CARD",
    "payment_method": {
      "type": "CARD",
      "extra": {
        "bin": "400000",
        "name": "MASTERCARD-0002",
        "brand": "MASTERCARD",
        "exp_year": "29",
        "exp_month": "06",
        "last_four": "0002",
        "card_holder": "Pedro Pérez",
        "is_three_ds": true
      },
      "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 5. Perform periodic transaction queries to check the status and ensure its correct execution.

You can perform periodic queries to the transaction using the endpoint GET /transactions/{transaction_id} to verify its status.