Pagos con 3DS

Recolecta los datos del navegador

La solicitud inicial necesita el objeto threeDSParams con información del navegador del tarjetahabiente. Recolecta estos datos en tu frontend y envíalos a tu backend junto con el pago. Todos los campos son obligatorios y todos son string salvo los dos booleanos:

const threeDSParams = {
  browserAcceptHeader: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
  browserJavaScriptEnabled: true,
  browserJavaEnabled: navigator.javaEnabled(),
  browserLanguage: navigator.language,
  browserColorDepth: String(screen.colorDepth),
  browserTZ: String(new Date().getTimezoneOffset()),
  browserScreenWidth: String(screen.width),
  browserScreenHeight: String(screen.height),
  browserUserAgent: navigator.userAgent,
};

Envía la solicitud inicial

Genera una x-idempotency-key (UUID v4) y envía el pago a POST /api/v2/transactions con los mismos campos de procesar pagos más el objeto threeDSParams.

Usa datos de cliente reales y consistentes: el correo debe ser de un dominio existente (evita @example.com y similares) y clientName debería coincidir con cardHolder. Los datos de prueba inconsistentes pueden producir rechazos por reglas de riesgo que no tienen relación con tu integración.

const idempotencyKey = crypto.randomUUID(); // Guárdala: se reutiliza en la solicitud de confirmación
 
const body = {
  clientName: 'John Doe',
  clientEmail: '[email protected]',
  clientPhone: '+50322577777',
  description: 'Test API',
  amount: 100, // Monto en centavos (100 = $1.00)
  cardHolder: 'John Doe',
  cardNumber: '4000000000000416',
  cvv: '123',
  month: '12',
  year: '26',
  threeDSParams, // Objeto del paso 1
};
 
fetch('https://<CUBO_API_URL>/api/v2/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'TU_API_KEY_AQUI',
    'x-idempotency-key': idempotencyKey,
    'client-ip-address': '190.0.0.1', // IP pública del tarjetahabiente
  },
  body: JSON.stringify(body),
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

curl --location '/api/v2/transactions' \
--header 'X-API-KEY: TU_API_KEY_AQUI' \
--header 'x-idempotency-key: 3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607' \
--header 'client-ip-address: 190.0.0.1' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientName": "John Doe",
    "clientEmail": "[email protected]",
    "clientPhone": "+50322577777",
    "description": "Test API",
    "amount": 100,
    "cardHolder": "John Doe",
    "cardNumber": "4000000000000416",
    "cvv": "123",
    "month": "12",
    "year": "26",
    "threeDSParams": {
        "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "browserJavaScriptEnabled": true,
        "browserJavaEnabled": false,
        "browserLanguage": "es-SV",
        "browserColorDepth": "24",
        "browserTZ": "360",
        "browserScreenWidth": "1920",
        "browserScreenHeight": "1080",
        "browserUserAgent": "Mozilla/5.0"
    }
}'

Posibles respuestas

A) Hay challenge. La respuesta incluye authenticationToken. Continúa con el paso 3 y guarda authenticationToken y authenticationResponse.transactionId, ya que los necesitarás para consultar el resultado.

{
  "authenticationToken": "eyJhbGciOiJIUzI1NiIs...",
  "authenticationResponse": {
    "methodURL": "https://acs.banco.com/3ds-method",
    "protocolVersion": "2.2.0",
    "correlationId": "c-8891",
    "transactionId": "a3f9c2b1-...",
    "threeDSMethodData": "eyJ0aHJlZURTU2VydmVyVHJhb...",
    "scaIndicator": true
  }
}

En este punto todavía no existe ninguna transacción ni ningún cobro: esta solicitud no genera nada cobrable. Si la repites con la misma key y el mismo cuerpo, recibirás este mismo challenge.

B) No hubo challenge. La respuesta incluye paymentIntentToken. El emisor no exigió challenge y el pago ya se procesó; revisa status para saber si fue SUCCEEDED o REJECTED. El flujo termina aquí: no envíes la segunda solicitud.

{
  "paymentIntentToken": "pi_9f8a7b6c",
  "status": "SUCCEEDED",
  "referenceId": "REF123456",
  "authorizationCode": "A1B2C3",
  "processedAt": "2026-09-17T14:21:05.113Z"
}

Esta respuesta es idéntica a la de un comercio sin 3DS habilitado. Si no esperabas un flujo frictionless, verifica la configuración del comercio antes de buscar el problema en tu integración.

C) La autenticación falló. Recibes un 400 con el mensaje Fallo en autenticación. Detén el flujo y no reintentes con la misma key.

Resuelve el challenge con el banco

Con methodURL y threeDSMethodData de la respuesta anterior, ejecuta el paso de 3DS Method en tu frontend: un iframe oculto que hace POST del campo threeDSMethodData a methodURL. Si la respuesta no trae methodURL, omite este paso.

Luego consulta el resultado de la autenticación (paso 4). Si el emisor pide challenge, muestra al tarjetahabiente un iframe visible que haga POST del campo creq a acsURL.

El challenge ocurre entre el navegador del tarjetahabiente y el banco; la API de Cubo no participa.

Ambos iframes se alimentan igual: un <form> con método POST cuyo target es el iframe, que se envía automáticamente al montarse.

// Monta un iframe y le envía un formulario por POST. Para el 3DS Method el iframe va oculto
// (threeDSMethodData → methodURL); para el challenge va visible (creq → acsURL).
// Devuelve el iframe para que puedas retirarlo después.
const postToIframe = (url, fields, { visible }) => {
  const name = visible ? 'threeDSChallenge' : 'threeDSMethod';
 
  // Si ya existe un iframe con este nombre (por ejemplo, al reabrir el modal), lo retira
  // antes de montar uno nuevo; de lo contrario se apilan.
  document.getElementsByName(name).forEach(existing => existing.remove());
 
  const iframe = document.createElement('iframe');
  iframe.name = name;
  iframe.hidden = !visible;
  iframe.allow = 'payment *; publickey-credentials-get *';
  if (visible) Object.assign(iframe.style, { width: '90%', height: '90%', border: '0' });
  document.body.appendChild(iframe);
 
  const form = document.createElement('form');
  form.method = 'POST';
  form.action = url;
  form.target = iframe.name;
  Object.entries(fields).forEach(([name, value]) => {
    const input = document.createElement('input');
    input.type = 'hidden';
    input.name = name;
    input.value = value;
    form.appendChild(input);
  });
  document.body.appendChild(form);
 
  // Espera ~100 ms antes de enviar: el iframe necesita montar su documento para recibir el POST.
  setTimeout(() => {
    form.submit();
    form.remove();
  }, 100);
 
  return iframe;
};
 
// Paso 3a: 3DS Method (oculto). Retíralo a los 15 segundos.
const methodFrame = postToIframe(methodURL, { threeDSMethodData }, { visible: false });
setTimeout(() => methodFrame.remove(), 15000);
 
// Paso 3b: challenge (visible), cuando el paso 4 devuelve status "C".
// Retíralo cuando el resultado deje de ser "C".
const challengeFrame = postToIframe(acsURL, { creq }, { visible: true });

El ejemplo contempla dos detalles que fallan en silencio si se omiten: esperar unos 100 ms antes del submit() para que el iframe termine de montarse, y limpiar el contenedor antes de montar el challenge, porque reabrir el modal apila iframes.

El banco redirige dentro del iframe cuando el tarjetahabiente termina. No necesitas escuchar ese evento: el fin del challenge lo detectas cuando el resultado del paso 4 deja de ser C. Muestra el iframe del challenge centrado y sobre el resto de la página, como un modal.

Consulta el resultado de la autenticación

Consulta el endpoint de resultado 3DS enviando el transactionId del paso 2 en la ruta y el authenticationToken en el header 3ds-token. Repite la consulta cada 2 o 3 segundos hasta obtener un estado final:

• status: "C": el emisor pide challenge. La respuesta trae creq y acsURL; muestra el iframe del challenge (paso 3) y sigue consultando.
• status: "D": autenticación fuera del navegador en curso (por ejemplo, en la app del banco). Es un estado transitorio: no detengas el flujo aquí, sigue consultando.
• Sin status o con cualquier otro valor: la autenticación sigue en curso. Sigue consultando.
• status: "Y" o "A": autenticación completada. A habilita el cobro igual que Y; tratarlo como fallo deja sin cobrar pagos autenticados. Toma eci, authenticationValue, dsTransId y protocolVersion para el paso 5.
• status: "N", "U" o "R": la autenticación falló. Detén el flujo.

Envía la solicitud de confirmación

Envía el mismo endpoint, el mismo cuerpo del paso 2 y la misma x-idempotency-key, agregando los resultados de la autenticación.

No hace falta reenviar threeDSParams en esta solicitud: la comparación de cuerpos lo ignora, así que omitirlo no rompe la igualdad con el paso 2.

fetch('https://<CUBO_API_URL>/api/v2/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'TU_API_KEY_AQUI',
    'x-idempotency-key': idempotencyKey, // La misma del paso 2
    'client-ip-address': '190.0.0.1',
  },
  body: JSON.stringify({
    ...body, // El mismo cuerpo del paso 2
    threeDSEvaluated: true,
    eci: '05',
    xid: '1d9a2b6e-0d6b-4f0e-9f11-01',
    cavv: 'AAABBJg0VhI0VniQEjRWAAAAAAA=',
    dsTransId: '1d9a2b6e-0d6b-4f0e-9f11-01',
    protocolVersion: '2.2.0',
  }),
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

curl --location '/api/v2/transactions' \
--header 'X-API-KEY: TU_API_KEY_AQUI' \
--header 'x-idempotency-key: 3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607' \
--header 'client-ip-address: 190.0.0.1' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientName": "John Doe",
    "clientEmail": "[email protected]",
    "clientPhone": "+50322577777",
    "description": "Test API",
    "amount": 100,
    "cardHolder": "John Doe",
    "cardNumber": "4000000000000416",
    "cvv": "123",
    "month": "12",
    "year": "26",
    "threeDSEvaluated": true,
    "eci": "05",
    "xid": "1d9a2b6e-0d6b-4f0e-9f11-01",
    "cavv": "AAABBJg0VhI0VniQEjRWAAAAAAA=",
    "dsTransId": "1d9a2b6e-0d6b-4f0e-9f11-01",
    "protocolVersion": "2.2.0"
}'

Respuesta

{
  "paymentIntentToken": "pi_9f8a7b6c",
  "status": "SUCCEEDED",
  "referenceId": "REF123456",
  "authorizationCode": "A1B2C3",
  "processedAt": "2026-09-17T14:23:40.882Z"
}

status puede ser SUCCEEDED o REJECTED. Guarda el paymentIntentToken: es el valor con el que podrás consultar la transacción más adelante. Si repites esta solicitud con la misma key y el mismo cuerpo dentro de los 3 minutos siguientes, recibirás esta misma respuesta sin que se genere un nuevo cobro.

Un REJECTED aquí no es un fallo de 3DS: la autenticación ya se completó y lo que falló es el cobro (fondos insuficientes, límites o restricciones del emisor). Esto también te permite ejercitar el flujo completo sin mover dinero, usando un monto que no pueda aprobarse.