Automatic transactions with 3RI protocol

With Wompi, you can create secure payment sources using the 3RI protocol for your automatic payments (3D Secure Requestor Initiated Authentication). This protocol is a feature of 3D Secure version 2.2 that allows merchants to perform authenticated transactions without direct interaction from the paying customer, i.e., recurring payments.

To use the 3RI protocol, you must create payment sources using the 3D Secure or 3DS protocol. This protocol adds an additional security layer to online transactions, allowing card issuers and acquirers to authenticate the cardholder before processing the transaction.

Important Notes

When creating a secure payment source with 3DS and using the resulting payment source ID in automatic transactions, these will be protected under the 3RI protocol. To continue using this functionality, it's necessary to request 3DS activation for payment sources from the fraud management team. We recommend contacting our support channels to resolve any questions.
The 3DS protocol for creating payment sources is available for Mastercard and Visa franchises.
The 3RI protocol is available for automatic transactions with Mastercard.
The availability of the 3DS protocol by franchise may vary depending on your business model (Gateway or Aggregator).
If you want to know the steps for creating payment sources without the 3DS protocol, you can go here: Payment Sources & Tokenization

Below, we'll show you the process to implement the 3DS protocol in creating a secure payment source with cards:

Step 1: Create a payment source

{
  "type": "CARD",
  "token": "tok_devint_1854_b9D8b065dF326f393aD27cc86fA373c8",
  "customer_email": "email@email.com",
  "acceptance_token": "eyJhbGciOiJIUzI1NiJ9.eyJjb250cmFjdF9pZCI6MzA5LCJwZXJtYWxpbmsiOiJodHRwczovL3dvbXBpLmNvbS9hc3NldHMvZG93bmxvYWRibGUvcmVnbGFtZW50by1Vc3Vhcmlvcy1Db2xvbWJpYS5wZGYiLCJmaWxlX2hhc2giOiJkMWVkMDI3NjhlNDEzZWEyMzFmNzAwMjc0N2Y0N2FhOSIsImppdCI6IjE3MzA4MjA1NjItODIxMjUiLCJlbWFpbCI6IiIsImV4cCI6MTczMDgyNDE2Mn0.mQL_Qz8nku2Y7sLCD3a_mBqT3Ez3PVy9IPemcEB7ZLA"
}

You must then start checking the card's authentication status through the payment_sources/{payment_source_id} endpoint by making a query every 2 seconds. As the different steps are executed, this will be reflected in the three_ds_auth field of the extra object in the response.

{
  "data": {
    "id": 71942,
    "public_data": {
      "bin": "230377",
      "last_four": "0275",
      "exp_month": "10",
      "exp_year": "31",
      "card_holder": "FRAUD TEST",
      "validity_ends_at": "2027-05-05T15:38:56.283+00:00",
      "type": "CARD"
    },
    "token": "tok_devint_1854_548891e34aCf33B2e042E9E1b2041c20",
    "type": "CARD",
    "status": "PENDING", // Payment source status
    "customer_email": "email@email.com",
    "extra": {
      "is_three_ds": true,
    }
  },
  "meta": {}
}

The process includes the following steps in order:

BrowserInfo
Fingerprint
Challenge
Authentication

Each step can have one of these states:

PENDING
ERROR
COMPLETED

Step 2: Browser Info

After querying the payment source status for some time, you'll find the three_ds_auth field as shown below:

current_step: Indicates the current step in the authentication flow (Browser Info, Fingerprint, Authentication, or Challenge)
current_step_status: Indicates the status of the current step (Pending or Completed)
three_ds_method_data: HTML content that must be rendered for direct integration with the ACS

{
  "data": {
    "id": 71942,
    "public_data": {
      "bin": "230377",
      "last_four": "0275",
      "exp_month": "10",
      "exp_year": "31",
      "card_holder": "FRAUD TEST",
      "validity_ends_at": "2027-05-05T15:38:56.283+00:00",
      "type": "CARD"
    },
    "token": "tok_devint_1854_548891e34aCf33B2e042E9E1b2041c20",
    "type": "CARD",
    "status": "PENDING",
    "customer_email": "email@email.com",
    "extra": {
      "is_three_ds": true,
      "three_ds_auth": {
        "current_step": "BROWSER_INFO",
        "current_step_status": "PENDING",
        "three_ds_method_data": "<!-- HTML content for browser information collection -->",
        // Other fields
      }
    }
  },
  "meta": {}
}

note

Note: The content within three_ds_method_data must first be "formatted" for proper rendering, as it comes as HTML with character entities or escape codes, i.e., with values like < or > instead of less than (<) or greater than (>) symbols in HTML tags.

After rendering the BROWSER INFO and if everything went well, Wompi will receive the necessary information and proceed to update the status to FINGERPRINT. While we do this, you will need to continue periodically checking the payment source status (For this and all other steps)

Step 3: Fingerprint

Once the previous flow is completed, you'll find yourself in the FINGERPRINT step. The response will include the same fields as the others, only the content of the three_ds_auth object in the extra field will change:

{
  "data": {
    "id": 71942,
    "public_data": {
      "bin": "230377",
      "last_four": "0275",
      "exp_month": "10",
      "exp_year": "31",
      "card_holder": "FRAUD TEST",
      "validity_ends_at": "2027-05-05T15:38:56.283+00:00",
      "type": "CARD"
    },
    "token": "tok_devint_1854_548891e34aCf33B2e042E9E1b2041c20",
    "type": "CARD",
    "status": "PENDING",
    "customer_email": "email@email.com",
    "extra": {
      "is_three_ds": true,
      "three_ds_auth": {
        "current_step": "FINGERPRINT",
        "current_step_status": "PENDING",
        "three_ds_method_data": "<!-- HTML content for device information collection -->",
        // Other fields
      }
    }
  },
  "meta": {}
}

Step 4: Challenge

Once the previous flow is completed, you'll find yourself in the CHALLENGE step. The content rendered in this step will be stipulated by the card's issuing bank, therefore, it may vary depending on the bank.

***** Note: In the previous steps, the content of three_ds_method_data is HTML that does NOT require direct interaction with the payer, as it executes automatically when rendered. For this particular step, we WILL need interaction with the user, as they will need to answer a question, enter data, select from options presented on screen, etc., as determined by the payer's bank.

{
  "data": {
    "id": 71942,
    "public_data": {
      "bin": "230377",
      "last_four": "0275",
      "exp_month": "10",
      "exp_year": "31",
      "card_holder": "FRAUD TEST",
      "validity_ends_at": "2027-05-05T15:38:56.283+00:00",
      "type": "CARD"
    },
    "token": "tok_devint_1854_548891e34aCf33B2e042E9E1b2041c20",
    "type": "CARD",
    "status": "PENDING",
    "customer_email": "email@email.com",
    "extra": {
      "is_three_ds": true,
      "three_ds_auth": {
        "current_step": "CHALLENGE",
        "current_step_status": "PENDING",
        "three_ds_method_data": "<!-- HTML content provided by the bank to authenticate the payer -->",
        // Other fields
      }
    }
  },
  "meta": {}
}

Step 5: Final Result

Depending on the challenge result, the authentication of the payment source with the 3DS protocol will (or will not) successfully complete once the entire flow is finished:

{
  "data": {
    "id": 71942,
    "public_data": {
      "bin": "230377",
      "last_four": "0275",
      "exp_month": "10",
      "exp_year": "31",
      "card_holder": "FRAUD TEST",
      "validity_ends_at": "2027-05-05T15:38:56.283+00:00",
      "type": "CARD"
    },
    "token": "tok_devint_1854_548891e34aCf33B2e042E9E1b2041c20",
    "type": "CARD",
    "status": "AVAILABLE", // AVAILABLE, DECLINED or ERROR
    "customer_email": "email@email.com",
    "extra": {
      "is_three_ds": true,
      "three_ds_auth": {
        "current_step": "AUTHENTICATION",
        "current_step_status": "COMPLETED",
        // Other fields
      }
    }
  },
  "meta": {}
}

What if something fails? 🚒

We know that not everything is perfect, so here are the most common day-to-day scenarios and how to proceed:

The user abandons the flow: This case is quite common in the CHALLENGE step, when during the authentication process, the user may leave the screen, page, etc. without completing the presented challenge.

What to do? Nothing, Wompi has a time limit to complete the entire authentication flow with the 3DS protocol. If this limit is exceeded, the payment source will remain in ERROR state and the current_step_status in ABANDONED

The payer's card is not supported by the protocol The 3DS protocol may not support the payer's card bin. This validation is done before the Browser Info step, so if this scenario occurs, the payment source won't even reach this first step.

What to do? The payment source will remain in DECLINED state and the flow will end.

When creating a secure payment source with 3DS and using the resulting payment source ID in automatic transactions, these will be protected under the 3RI protocol.

Important Notes​

Step 1: Create a payment source​

Step 2: Browser Info​

Step 3: Fingerprint​

Step 4: Challenge​

Step 5: Final Result​

What if something fails? 🚒​