Resultado final de autenticación 3DS

EVENT<client-url>/threeds/v1/finalized-event

Resultado final de autenticación 3DS

Pomelo envía este webhook al concluir cada autenticación 3DS, independientemente del resultado.

Usá este evento para actualizar el estado de la transacción en tu sistema, registrar métricas de autenticación o tomar decisiones de negocio en tiempo real.

Status

El campo status tiene tres valores posibles:

`status`	Descripción
`SUCCESS`	La autenticación fue completada exitosamente.
`FAILED`	La autenticación no se completó (tarjeta inactiva, challenge fallido, cancelado, timeout, etc.).
`ERROR`	Ocurrió un error técnico durante el procesamiento.

Cuando status es FAILED o ERROR, el campo status_detail indica la causa específica.

Status detail

`status_detail`	`status`	Descripción
`CARD_NOT_ACTIVE`	`FAILED`	Tarjeta bloqueada o deshabilitada.
`RISK_REJECTED`	`FAILED`	El sistema de riesgo rechazó la transacción.
`CHALLENGE_ATTEMPTS_EXCEEDED`	`FAILED`	El usuario superó el máximo de intentos de OTP.
`CHALLENGE_RETRIES_EXCEEDED`	`FAILED`	El usuario superó el máximo de reenvíos de OTP.
`CHALLENGE_CONTACT_MISSING`	`FAILED`	No se encontró teléfono o email para entregar el challenge.
`CANCELLED_BY_CARDHOLDER`	`FAILED`	El usuario canceló el challenge.
`CANCELLED_BY_REQUESTOR`	`FAILED`	El comercio canceló la transacción.
`CHALLENGE_TIMEOUT`	`FAILED`	El usuario no completó el challenge a tiempo.
`ABORTED`	`FAILED`	El comercio no completó el flujo 3DS después de iniciarlo.
`NOTIFICATION_FAILED`	`ERROR`	No se pudo entregar el OTP al usuario.
`CONFIGURATION_ERROR`	`ERROR`	Configuración inválida o incompleta.
`PROTOCOL_ERROR`	`ERROR`	Error de protocolo EMV 3DS.
`INTERNAL_ERROR`	`ERROR`	Error interno del sistema de autenticación.

Challenge method

El campo challenge_method indica cómo se autenticó el usuario:

`challenge_method`	Descripción
`FRICTIONLESS`	Autenticación sin interacción del usuario.
`OTP`	El usuario ingresó un código OTP recibido por SMS o email.
`OOB`	Autenticación out-of-band (ej: aprobación desde la app bancaria).

Seguridad

Cada request incluye los mismos headers de firma que el webhook OTP. Ver la sección OTP para las recomendaciones de validación.

Reintentos

Pomelo espera una respuesta 2xx para considerar la entrega exitosa. Si el endpoint responde 4xx, 5xx o no responde a tiempo, el evento puede reenviarse. Respondé 409 si ya procesaste el idempotency_key para evitar reenvíos.

Parámetros disponibles

Header Parameters

X-Api-KeyStringrequired

X-SignatureStringrequired

X-TimestampStringrequired

X-EndpointStringrequired

Cuerpo de solicitud

application/json

threeds_transaction_idstringrequired

statusenumrequired

status_detailenum

challenge_methodenum

initiated_atstringdate-time

finalized_atstringdate-timerequired

cardobjectrequired2 propiedades

userobjectrequired1 propiedades

merchantobjectrequired4 propiedades

transactionobjectrequired2 propiedades

metadataobject2 propiedades

Ejemplo de solicitud

{
  "event_id": "3ds_finalized_event",
  "idempotency_key": "b1c35040-0668-4c8c-8d50-76273b6c4584",
  "threeds_transaction_id": "tds-1xEo90T0OMuKqpbZK7i7JCiE",
  "status": "FAILED",
  "status_detail": "CARD_NOT_ACTIVE",
  "challenge_method": "OTP",
  "initiated_at": "2026-04-27T17:44:36.448Z",
  "finalized_at": "2026-04-27T17:45:18.811Z",
  "card": {
    "id": "crd-2T5s6CzCarcg7zXmyihrTjSGNrn",
    "status": "BLOCKED"
  },
  "user": {
    "id": "usr-2M8sierTB62Gf8eDRJ7quLb5nBa"
  },
  "merchant": {
    "id": "010096327",
    "name": "AIRBNB.COM",
    "mcc": "5411",
    "country": "USA"
  },
  "transaction": {
    "amount": "99.00",
    "currency": "USD"
  },
  "metadata": {
    "device_ip": "102.106.127.181",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }
}

Entrega de código OTP 3DS