Consultar resultado 3DS

Esta sección detalla el uso del endpoint para consultar el resultado de la autenticación 3D Secure una vez que el tarjetahabiente resolvió el challenge con su banco. Corresponde al paso 4 del flujo de pagos con 3DS.

Detalles del endpoint

Método: GET
URL: /api/v1/transactions/3ds-results/:transactionId

El endpoint devuelve la respuesta del proveedor 3DS con los datos necesarios para enviar la solicitud de confirmación. Consúltalo cada 2 o 3 segundos después del 3DS Method y mientras el challenge esté en curso, hasta obtener un estado final.

Configuración de la solicitud

Headers

Header	Descripción
`X-API-KEY`	API Key generada en Cubo Admin.
`3ds-token`	El `authenticationToken` devuelto en la solicitud inicial, no tu API Key.

Parámetros de ruta

Parámetro	Tipo	Descripción
`transactionId`	`string`	Valor de `authenticationResponse.transactionId` devuelto en la solicitud inicial.

Ejemplos de uso

JavaScript


fetch('https://<CUBO_API_URL>/api/v1/transactions/3ds-results/a3f9c2b1-...', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'TU_API_KEY_AQUI',
    '3ds-token': 'eyJhbGciOiJIUzI1NiIs...',
  },
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Respuestas del servidor

✅ Respuesta exitosa

La respuesta es la del proveedor 3DS tal cual. El campo status indica en qué punto está la autenticación:

`status`	Significado	Qué hacer
`C`	El emisor pide challenge.	Muestra un iframe que haga `POST` del campo `creq` a `acsURL` y sigue consultando.
`D`	Autenticación fuera del navegador en curso (por ejemplo, en la app del banco).	Sigue consultando. Es un estado transitorio.
`Y`	Autenticación exitosa.	Continúa con la solicitud de confirmación.
`A`	Intento de autenticación aceptado.	Continúa con la solicitud de confirmación, igual que con `Y`.
`N`, `U`, `R`	La autenticación falló o no está disponible.	Detén el flujo. No envíes la solicitud de confirmación.
Sin `status` u otro valor	La autenticación sigue en curso.	Sigue consultando hasta obtener un estado final.

Trata A como éxito, igual que Y: tomarlo como fallo deja sin cobrar pagos autenticados. Y no detengas el flujo en D, porque abortarías una autenticación que todavía podía completarse.

Con status Y o A, toma estos campos para la solicitud de confirmación:

Campo	Tipo	Descripción
`eci`	`string`	Indicador de comercio electrónico. Se envía como `eci`.
`authenticationValue`	`string`	Valor de verificación del tarjetahabiente. Se envía como `cavv`.
`dsTransId`	`string`	Identificador en el Directory Server. Se envía como `dsTransId` y como `xid`. La respuesta no trae un campo `xid` propio.
`protocolVersion`	`string`	Versión del protocolo 3DS utilizada. Se envía como `protocolVersion`.

⚠️

dsTransId cambia entre la respuesta C y la final. Toma los valores de la respuesta terminal (Y o A), no los del challenge: son valores distintos y usar el equivocado invalida la solicitud de confirmación.


{
  "status": "Y",
  "eci": "05",
  "authenticationValue": "AAABBJg0VhI0VniQEjRWAAAAAAA=",
  "dsTransId": "1d9a2b6e-0d6b-4f0e-9f11-01",
  "acsTransId": "7c1e0f52-3b7a-4a1e-9d2b-02",
  "protocolVersion": "2.2.0"
}

Mientras el emisor pide challenge, la respuesta incluye además la información para mostrarlo:


{
  "status": "C",
  "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6...",
  "acsURL": "https://acs.banco.com/challenge",
  "dsTransId": "1d9a2b6e-0d6b-4f0e-9f11-01",
  "protocolVersion": "2.2.0"
}

Con estos valores, continúa con la solicitud de confirmación para efectuar el cobro.

❌ Respuesta de error


{
  "statusCode": 404,
  "message": "Transaction not found"
}

Código	Descripción
`401`	API Key inválida o `3ds-token` inválido o expirado.
`404`	El `transactionId` no corresponde a una autenticación iniciada por tu comercio.