Create a 3DS Authenticated Payment

You can add an extra layer of security to your transactions and reduce the risk of fraud by implementing 3D Secure (3DS) authentication. This guide walks you through using the GetNet Regional API to verify a cardholder's identity before processing their payment.

Requirements

Before following the steps, you need to:

Create your account by contacting the Integration Support Team to get your API credentials (client_id and client_secret).
Generate your Bearer token with your credentials using the Access Token endpoint.
Ensure the customer's card brand is either Mastercard or Visa, as they are the currently supported schemes for 3DS authentication in Argentina, Chile, Mexico, Spain and Uruguay.

Important for European transactions: For all transactions within the European Economic Area (EEA), 3DS authentication is mandatory in compliance with PSD2 and Strong Customer Authentication (SCA) requirements. All card payments processed in Europe must be authenticated using 3DS, unless a valid SCA exemption is applied and accepted by the card issuer. For more information about SCA exemptions, see the Taxes and Regulations reference documentation.

Understanding the 3DS Authentication Process

The 3DS authentication flow is determined dynamically by the card issuer based on factors like risk assessment, card brand, and issuer capabilities. After initiating enrollment, you will receive a status field that indicates which scenario applies to your transaction.

Your implementation must handle three possible scenarios:

Direct Authentication - Authentication completes immediately (status: Authenticated or Attempt)
Challenge After Initial Enrollment - Customer verification required immediately (status: Pending Challenge)
Pending Enrollment Continue - Additional processing needed, which may result in either authentication or challenge (status: Pending Enrollment Continue)

The following diagram illustrates the authentication flow and decision points:

Quick Reference: Decision Flow

To help you quickly understand which steps to follow, use this decision tree based on the status returned from each endpoint:

After Step 2 (Initiate Enrollment):

Check the status field in the response:

"Authenticated" or "Attempt"
- Proceed to Step 4: Create the Payment
"Pending Challenge"
- Proceed to Step 3B: Validate Authentication, then Step 4: Create the Payment
"Pending Enrollment Continue"
- Proceed to Step 3C: Continue Enrollment
  - If the continue response returns "Authenticated"
    - Proceed to Step 4: Create the Payment
  - If the continue response returns "Pending Challenge"
    - Proceed to Step 3B: Validate Authentication, then Step 4: Create the Payment

Implementation Steps

Step 1: Obtain Access Token and Tokenize Card

Before initiating 3DS authentication, you must:

Request an access token using your API credentials
Tokenize the customer's card information using the token endpoint

Refer to the API reference - token for details on card tokenization.

Step 2: Initiate Enrollment

Call the 3DS - Init Authentication endpoint to check if the card is enrolled in a 3DS program. The response will include a status field that determines your next action.

Request example:

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/dpm/security-gwproxy/v2/enrolments-initial \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "currency": "CLP",
  "md": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0",
  "term_url": "123",
  "amount": 1,
  "payment_method": {
    "expiration_month": "05",
    "expiration_year": "25",
    "security_code": "282",
    "number_token": "4292b573ea94b257dcb132afe242b4a15c9866d16e2d4d64d8e571c877af0540c3946b8bddaf37c2c75a1810863fc6b0fe0e841ebbc752c1d23ccfb5fdaac3d1"
  },
  "description": "TEST",
  "operation": "CREDIT",
  "extra_fields": {
    "billing_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    },
    "shipping_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    }
  }
}'

Response example:

{
  "transaction_id": "502040201060404060506040",
  "md": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0",
  "tx_id": 280000000,
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
  "protocol": "3DS2.2.0",
  "status": "Pending Enrolment Continue",
  "operation": "CREDIT",
  "redirect_html_template": "",
  "tds_method_content": "...",
  "extra_fields": {
    "billing_address": { ... },
    "shipping_address": { ... }
  }
}

Step 3: Check Status and Follow the Appropriate Scenario

After receiving the enrollment response, check the status field to determine which scenario applies and follow the corresponding steps below.

Status: `Authenticated` or `Attempt`

If the status is Authenticated or Attempt, authentication is complete. The response already contains the authentication data you need.

What to do:

Extract the authentication data from the response: xid, eci, cavv, ds_trans_id
Proceed directly to Step 4: Create the Payment

Note: If the status is Attempt, you should evaluate your risk tolerance to decide whether to proceed with the payment.

Status: `Pending Challenge`

If the status is Pending Challenge, the customer must complete authentication with their bank before you can process the payment.

What to do:

Extract the redirect_html_template from the response
Render the HTML template in your application to redirect the customer to their bank's authentication page
Wait for the customer to complete authentication and return to your site
Call the validations endpoint (see Step 3B: Validate Authentication)
Extract authentication data from the validation response
Proceed to Step 4: Create the Payment

Example of rendering the HTML template:

<!-- In your frontend application -->
<div id="challenge-container"></div>

<script>
// Receive the redirect_html_template from your backend
const redirectHtmlTemplate = response.redirect_html_template;

// Inject the HTML into your page
document.getElementById('challenge-container').innerHTML = redirectHtmlTemplate;

// The template contains a form that will automatically submit and redirect
// the customer to their bank's authentication page
</script>

Alternatively, you can render it server-side:

// Node.js/Express example
app.post('/initiate-3ds', async (req, res) => {
  const enrollmentResponse = await fetch('https://api-sbx.pre.globalgetnet.com/dpm/security-gwproxy/v2/enrolments-initial', {
    // ... request configuration
  });
  
  const data = await enrollmentResponse.json();
  
  if (data.status === 'Pending Challenge') {
    // Send the HTML template directly to the browser
    res.send(data.redirect_html_template);
  }
});

Status: `Pending Enrollment Continue`

If the status is Pending Enrollment Continue, you must call the enrollments-continue endpoint to complete the enrollment process.

What to do:

Call the enrollments-continue endpoint (see Step 3C: Continue Enrollment)
Check the status in the continue response:
- If status is Authenticated: Extract authentication data and proceed to Step 4: Create the Payment
- If status is Pending Challenge: Follow the steps for Status: Pending Challenge above (redirect customer, validate, then create payment)

Step 3B: Validate Authentication

This step is required when the status is Pending Challenge (either from the initial enrollment or after calling enrollments-continue).

After the customer completes authentication with their bank and returns to your site, you must capture the challenge response token and call the 3DS - Validate authentication endpoint to verify the authentication outcome.

Important: The challenge response token you need to send depends on the 3DS protocol version:

For 3DS 2.x: Use the cres token (Challenge Response) received in the callback after the customer completes the challenge
For 3DS 1.0: Use the pares token (PAYER Authentication Response) received in the callback

Request example (3DS 2.x with cres token):

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/dpm/security-gwproxy/v2/validations \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --data '{
  "transaction_id": "502040201060404060506040",
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
  "token": "<cres-token-from-challenge-callback>"
}'

Request example (3DS 1.0 with pares token):

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/dpm/security-gwproxy/v2/validations \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --data '{
  "transaction_id": "502040201060404060506040",
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
  "token": "<pares-token-from-challenge-callback>"
}'

Note: The API accepts the challenge response token in the token field. The value should be the cres token for 3DS 2.x or pares token for 3DS 1.0, depending on the protocol version used in the authentication flow.

Response example:

{
  "transaction_id": "502040201060404060506040",
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
  "status": "Authenticated",
  "eci": "05",
  "cavv": "aglgsCXwXPJDRA1aTlXIMVQnQakX",
  "ds_trans_id": "f7e5f76e-6388-43e6-b8cd-49b251a1f89c"
}

Extract the authentication data (xid, eci, cavv, ds_trans_id) from the response to use when creating the payment.

Step 3C: Continue Enrollment

This step is required when the initial enrollment status is Pending Enrollment Continue.

Call the 3DS - Banking Login Authentication Payload endpoint to complete the enrollment process.

Request example:

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/dpm/security-gwproxy/v2/enrolments-continue \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "transaction_id": "404030506040401010101060",
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA="
}'

Response example (Authenticated status):

{
  "transaction_id": "502040201060404060506040",
  "md": "nSWramKKPFOINFni0D2425aBsddViRuNK3CbR8W3DuHDTAlR",
  "tx_id": 39408201,
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA",
  "status": "Authenticated",
  "protocol": "3DS2.2.0",
  "operation": "CREDIT",
  "redirect_html_template": "",
  "ds_trans_id": "f7e5f76e-6388-43e6-b8cd-49b251a1f89c",
  "eci": "05",
  "cavv": "aglgsCXwXPJDRA1aTlXIMVQnQakX"
}

Response example (Pending Challenge status):

{
  "transaction_id": "502040201060404060506040",
  "md": "nSWramKKPFOINFni0D2425aBsddViRuNK3CbR8W3DuHDTAlR",
  "tx_id": 39408201,
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA",
  "status": "Pending Challenge",
  "protocol": "3DS2.2.0",
  "operation": "CREDIT",
  "redirect_html_template": "<html>...</html>"
}

After calling this endpoint, check the status field:

If Authenticated: Extract the authentication data and proceed to Step 4: Create the Payment
If Pending Challenge: Use the redirect_html_template to redirect the customer for authentication, then proceed to Step 3B: Validate Authentication

Step 4: Create the Payment

Once you have received a successful authentication status (Authenticated or Attempt) and extracted the authentication data, you can create the payment.

Call the Create - Authorize endpoint, including the standard payment details along with the 3DS authentication data you obtained:

xid - Transaction identifier
eci - Electronic Commerce Indicator
cavv - Cardholder Authentication Verification Value (if available)
ds_trans_id - Directory Server Transaction ID (for 3DS 2.x)

Request example:

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer '\
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "16c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "16ac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "123order",
  "data": {
    "amount": 118708,
    "currency": "CLP",
    "customer_id": "cassiano",
    "payment": {
      "payment_method": "CREDIT_AUTHORIZATION",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
      "eci": "24",
      "card": {
        "expiration_month": "05",
        "expiration_year": "25",
        "cardholder_name": "CARD HOLDER",
        "security_code": "282",
        "number_token": "775c2b646c11d5e0d0d75a722c558a14d24abdb1df3752fcbbe2d61e51fc25f28d028b3139622a78fb03256e7701c35f64cc4920bb2d5f3224c86f42e131a9f9"
      }
    }
  }
}'

Response example:

{
  "idempotency_key": "17c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "b4bd779a-98c3-4f99-a028-518de149ed16",
  "order_id": "123order1",
  "amount": 118708,
  "currency": "CLP",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_AUTHORIZATION",
  "received_at": "2025-08-13T10:34:01.239Z",
  "transaction_id": "MCC50204G3010",
  "original_transaction_id": "MCC50204G3010",
  "authorized_at": "2025-08-13T10:34:01.239Z",
  "reason_code": "00",
  "reason_message": "authorized",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "105020",
  "acquirer_transaction_id": "305020602020306050404010"
}

Next Steps

Now that you have successfully created a 3DS-authenticated payment, you can explore more features of the GetNet Regional API:

On this page

Create a 3DS Authenticated Payment

First Steps

Core Concepts

Reference

Card Payment Guides

Alternative Payment Methods

Handling payments

Modifying payments

Webhooks

Risk and Security

Country Features

Payment methods

Error Management and Notifications

Test your Integration

Create a 3DS Authenticated Payment

Requirements

Understanding the 3DS Authentication Process

Quick Reference: Decision Flow

Implementation Steps

Step 1: Obtain Access Token and Tokenize Card

Step 2: Initiate Enrollment

Step 3: Check Status and Follow the Appropriate Scenario

Status: Authenticated or Attempt

Status: Pending Challenge

Status: Pending Enrollment Continue

Step 3B: Validate Authentication

Step 3C: Continue Enrollment

Step 4: Create the Payment

Next Steps

Status: `Authenticated` or `Attempt`

Status: `Pending Challenge`

Status: `Pending Enrollment Continue`