Crear un pago autenticado con 3DS

Puede añadir una capa adicional de seguridad a sus transacciones y reducir el riesgo de fraude mediante la implementación de la autenticación 3D Secure (3DS). Esta guía explica cómo usar la API regional de GetNet para verificar la identidad del titular de la tarjeta antes de procesar su pago.

Requerimientos

Antes de seguir los pasos, es necesario:

Crea tu cuenta poniéndote en contacto con el equipo de soporte de integración para obtener tus credenciales de API (client_id y client_secret).
Genere su token de portador con sus credenciales mediante el punto final del token de acceso.
Asegúrese de que la marca de la tarjeta del cliente sea Mastercard o Visa, ya que son los esquemas actualmente compatibles para la autenticación 3DS en Argentina, Chile, México, España y Uruguay.

Importante para las transacciones europeas: Para todas las transacciones dentro del Espacio Económico Europeo (EEE), la autenticación 3DS es obligatoria de conformidad con los requisitos de PSD2 y de autenticación reforzada de clientes (SCA). Todos los pagos con tarjeta que se procesen en Europa deben autenticarse con la 3DS, a menos que el emisor de la tarjeta aplique y acepte una exención válida de la SCA. Para obtener más información acerca de las exenciones de la SCA, consulte Taxes and Regulations documentación de referencia.

Descripción del proceso de autenticación de 3DS

El emisor de la tarjeta determina dinámicamente el flujo de autenticación de la 3DS en función de factores como la evaluación de riesgos, la marca de la tarjeta y las capacidades del emisor. Tras iniciar la inscripción, recibirá un status campo que indica qué escenario se aplica a su transacción.

Su implementación debe gestionar tres escenarios posibles:

Autenticación directa - La autenticación se completa inmediatamente (estado: Authenticated o Attempt)
Desafío después de la inscripción inicial - Se requiere la verificación del cliente de inmediato (estado: Pending Challenge)
Continúa la inscripción pendiente - Se necesita un procesamiento adicional, que puede provocar la autenticación o la impugnación (estado: Pending Enrollment Continue)

El siguiente diagrama ilustra el flujo de autenticación y los puntos de decisión:

Referencia rápida: Flujo de decisiones

Para ayudarlo a comprender rápidamente los pasos a seguir, utilice este árbol de decisiones en función del estado devuelto por cada punto final:

Después del paso 2 (iniciar la inscripción):

Consulta el status campo en la respuesta:

«Autenticado» o «intento»
- Proceder a Step 4: Create the Payment
«Desafío pendiente»
- Proceder a Step 3B: Validate Authentication, entonces Step 4: Create the Payment
«Continúa la inscripción pendiente»
- Proceder a Step 3C: Continue Enrollment
  - Si se devuelve la respuesta de continuación «Autenticado»
    - Proceder a Step 4: Create the Payment
  - Si se devuelve la respuesta de continuación «Desafío pendiente»
    - Proceder a Step 3B: Validate Authentication, entonces Step 4: Create the Payment

Pasos de implementación

Paso 1: Obtenga el token de acceso y la tarjeta tokenize

Antes de iniciar la autenticación 3DS, debe:

Solicita un token de acceso con tus credenciales de API
Tokeniza la información de la tarjeta del cliente mediante el punto final del token

Consulte el API reference - token para obtener más información sobre la tokenización de tarjetas.

Paso 2: Iniciar la inscripción

Llame al 3DS - Init Authentication punto final para comprobar si la tarjeta está inscrita en un programa 3DS. La respuesta incluirá un status campo que determina tu próxima acción.

Ejemplo de solicitud:

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"
    }
  }
}'

Ejemplo de respuesta:

{
  "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": { ... }
  }
}

Paso 3: Verifique el estado y siga el escenario apropiado

Tras recibir la respuesta a la inscripción, compruebe la status campo para determinar qué escenario se aplica y siga los pasos correspondientes que se indican a continuación.

Estado: `Authenticated` o `Attempt`

Si el estado es Authenticated o Attempt, la autenticación está completa. La respuesta ya contiene los datos de autenticación que necesita.

Qué hacer:

Extraiga los datos de autenticación de la respuesta: xid, eci, cavv, ds_trans_id
Diríjase directamente a Step 4: Create the Payment

Nota: Si el estado es Attempt, debe evaluar su tolerancia al riesgo para decidir si desea continuar con el pago.

Estado: `Pending Challenge`

Si el estado es Pending Challenge, el cliente debe completar la autenticación con su banco antes de que puedas procesar el pago.

Qué hacer:

Extrae el redirect_html_template de la respuesta
Muestre la plantilla HTML en su aplicación para redirigir al cliente a la página de autenticación de su banco
Espera a que el cliente complete la autenticación y regrese a tu sitio
Llame al punto final de la validación (consulte Step 3B: Validate Authentication)
Extraer los datos de autenticación de la respuesta de validación
Proceder a Step 4: Create the Payment

Ejemplo de representación de la plantilla HTML:

<!-- 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>

Como alternativa, puede renderizarlo en el lado del servidor:

// 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);
  }
});

Estado: `Pending Enrollment Continue`

Si el estado es Pending Enrollment Continue, debe llamar al punto final de continuación de inscripciones para completar el proceso de inscripción.

Qué hacer:

Llame al punto final de continuación de las inscripciones (consulte Step 3C: Continue Enrollment)
Comprueba el estado en la respuesta de continuación:
- Si el estado es Authenticated: Extraiga los datos de autenticación y proceda a Step 4: Create the Payment
- Si el estado es Pending Challenge: Siga los pasos para Status: Pending Challenge arriba (redirigir al cliente, validar y, a continuación, crear el pago)

Paso 3B: Validar la autenticación

Este paso es obligatorio cuando el estado es Pending Challenge (ya sea desde la inscripción inicial o después de llamar a Enrollments-continue).

Cuando el cliente complete la autenticación con su banco y regrese a tu sitio, debes capturar el token de respuesta al desafío y llamar al 3DS - Validate authentication punto final para verificar el resultado de la autenticación.

Importante: El token de respuesta al desafío que debe enviar depende de la versión del protocolo 3DS:

Para 3DS 2.x: Usa el cres token (respuesta al desafío) recibido en la devolución de llamada después de que el cliente complete el desafío
Para 3DS 1.0: Usa el pares token (respuesta de autenticación de PAYER) recibido en la devolución de llamada

Ejemplo de solicitud (3DS 2.x con token cres):

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>"
}'

Ejemplo de solicitud (3DS 1.0 con token de pares):

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>"
}'

Nota: La API acepta el token de respuesta al desafío en token campo. El valor debe ser el cres token para 3DS 2.x o pares token para 3DS 1.0, según la versión del protocolo utilizada en el flujo de autenticación.

Ejemplo de respuesta:

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

Extraiga los datos de autenticación (xid, eci, cavv, ds_trans_id) de la respuesta que se utilizará al crear el pago.

Paso 3C: Continuar con la inscripción

Este paso es obligatorio cuando el estado de inscripción inicial es Pending Enrollment Continue.

Llame al 3DS - Banking Login Authentication Payload punto final para completar el proceso de inscripción.

Ejemplo de solicitud:

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="
}'

Ejemplo de respuesta (estado autenticado):

{
  "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"
}

Ejemplo de respuesta (estado de desafío pendiente):

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

Tras llamar a este punto final, compruebe la status campo:

Si Authenticated: Extraiga los datos de autenticación y proceda a Step 4: Create the Payment
Si Pending Challenge: Usa el redirect_html_template para redirigir al cliente para su autenticación y, a continuación, vaya a Step 3B: Validate Authentication

Paso 4: Crear el pago

Una vez que haya recibido un estado de autenticación exitoso (Authenticated o Attempt) y extraídos los datos de autenticación, puede crear el pago.

Llame al Create - Authorize punto final, incluidos los detalles de pago estándar junto con los datos de autenticación de la 3DS que ha obtenido:

xid - Identificador de transacción
eci - Indicador de comercio electrónico
cavv - Valor de verificación de autenticación del titular de la tarjeta (si está disponible)
ds_trans_id - ID de transacción del servidor de directorios (para 3DS 2.x)

Ejemplo de solicitud:

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"
      }
    }
  }
}'

Ejemplo de respuesta:

{
  "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"
}

Próximos pasos

Ahora que ha creado correctamente un pago autenticado por 3DS, puede explorar más funciones de la API regional de GetNet:

En esta página

Crear un pago autenticado con 3DS

Primeros Pasos

Core Concepts

Referencia

Guías de Pagos

Métodos de pago alternativos

Gestión de pagos

Modificación de pagos

Webhooks

Riesgo y seguridad

Funcionalidades por País

Métodos de pago

Administración de errores y notificaciones

Pon a prueba tu integración

Crear un pago autenticado con 3DS

Requerimientos

Descripción del proceso de autenticación de 3DS

Referencia rápida: Flujo de decisiones

Pasos de implementación

Paso 1: Obtenga el token de acceso y la tarjeta tokenize

Paso 2: Iniciar la inscripción

Paso 3: Verifique el estado y siga el escenario apropiado

Estado: Authenticated o Attempt

Estado: Pending Challenge

Estado: Pending Enrollment Continue

Paso 3B: Validar la autenticación

Paso 3C: Continuar con la inscripción

Paso 4: Crear el pago

Próximos pasos

Estado: `Authenticated` o `Attempt`

Estado: `Pending Challenge`

Estado: `Pending Enrollment Continue`