External 3DS

Si autenticas al tarjetahabiente con tu propio proveedor de 3DS antes de cobrar, ya tienes el resultado: el criptograma, el ECI y el ID de transacción del Directory Server. External 3DS te permite pasar ese resultado a Tonder dentro de la petición a /process/ que ya envías. Tonder no corre su propio 3DS — reenvía tus datos de autenticación al adquirente y procesa el pago.

En corto: tú autenticas → nos envías el resultado → nosotros cobramos con él.

Requisitos

• Tu integración API Direct actual — mismo endpoint, mismo Authorization: Token <API_KEY>, misma tarjeta tokenizada. No hay endpoint ni credenciales nuevos.
• Una autenticación 3DS completada con tu proveedor, de la que tengas el criptograma (CAVV o UCAF), el ECI y — para Mastercard — el ID de transacción del Directory Server.

Qué cambia en la petición

Una sola adición: un objeto threeDomainSecure en el nivel superior con tu resultado. También recomendamos mucho enviar card_brand dentro de payment_method (ver abajo). Todo lo demás queda exactamente igual.

threeDomainSecure

Dónde va cada cosa

Tres cosas viven en tres niveles distintos. Confundirlos es el error de integración más común:

Valores de ECI y reglas

Formato del criptograma. cavv / ucaf debe ser el criptograma en Base64 que devolvió tu proveedor, no en hex. Un string en hex se rechaza.

card_brand — recomendado. Tonder recibe una tarjeta tokenizada, no el PAN, así que no siempre puede determinar la red por sí mismo. Tú acabas de autenticar la tarjeta, así que la conoces — envíala:

• Con card_brand: Tonder valida threeDomainSecure contra la red desde el inicio y responde un 400 claro si algo es inconsistente (un ECI de Visa en una Mastercard, por ejemplo).
• Sin él: la validación es más ligera y una inconsistencia la detecta después el adquirente, como rechazo. card_brand te da errores más rápidos y más claros.

Valores aceptados: "visa", "mastercard" (sin distinguir mayúsculas).

Ejemplos

Mastercard

curl -X POST "https://stage.tonder.io/api/v1/process/" \
  -H "Authorization: Token YOUR_TONDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "payment",
    "amount": 150.00,
    "currency": "MXN",
    "customer": {
      "name": "Jane Doe",
      "email": "jane@testuser.com"
    },
    "payment_method": {
      "type": "CARD",
      "card_number": "9230-0892-4469-1474",
      "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
      "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
      "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
      "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063",
      "card_brand": "mastercard"
    },
    "threeDomainSecure": {
      "ucaf": "kCO52e75N318oAB3MPZU6EhB2Td6",
      "eci": "02",
      "directoryServerTransactionID": "9e8c4ff6-23d9-4fba-8446-6e8e9d13f42e",
      "specificationVersion": "2.2.0",
      "collectionIndicator": "2"
    },
    "client_reference": "ORD-001",
    "return_url": "https://tonder.io"
  }'

Visa

La misma petición, con cavv en lugar de ucaf y sin ID del Directory Server:

{
  "operation_type": "payment",
  "amount": 150.00,
  "currency": "MXN",
  "customer": { "name": "Jane Doe", "email": "jane@testuser.com" },
  "payment_method": {
    "type": "CARD",
    "card_number": "9230-0892-4469-1474",
    "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
    "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
    "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
    "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063",
    "card_brand": "visa"
  },
  "threeDomainSecure": {
    "cavv": "AAABBoVBaZKAR3BkdkFpELpWIiE=",
    "eci": "05",
    "specificationVersion": "2.2.0"
  },
  "client_reference": "ORD-002",
  "return_url": "https://tonder.io"
}

ECI no autenticado (acceptRisk)

Cuando el eci es 00 (Mastercard) o 07 (Visa) debes aceptar la responsabilidad de forma explícita, con acceptRisk: true dentro de threeDomainSecure:

"threeDomainSecure": {
  "ucaf": "kCO52e75N318oAB3MPZU6EhB2Td6",
  "eci": "00",
  "directoryServerTransactionID": "9e8c4ff6-23d9-4fba-8446-6e8e9d13f42e",
  "specificationVersion": "2.2.0",
  "collectionIndicator": "2",
  "acceptRisk": true
}

Qué esperar en la respuesta

• Un cobro exitoso regresa aprobado en una sola llamada, sin paso de reto — ya autenticaste al tarjetahabiente, así que Tonder no inicia su propio 3DS.
• Una respuesta Pending con next_action (un reto) significa que tus datos de autenticación no se aplicaron. Las causas habituales: threeDomainSecure anidado dentro de payment_method en lugar del nivel superior; tu cuenta no está habilitada para External 3DS; el objeto faltaba o iba vacío.

Errores comunes

Siguientes pasos