Consultar estado de idempotencia

Esta sección detalla el uso del endpoint para consultar el estado de una x-idempotency-key. Utilízalo cuando se pierda la conexión o expire el tiempo de espera durante el flujo de pagos con 3DS, para saber en qué punto quedó el pago antes de decidir qué hacer.

⚠️

Ante un timeout nunca reintentes el POST a ciegas. Consulta primero el estado de la key.

Detalles del endpoint

Método: GET
URL: /api/v1/transactions/status

El endpoint devuelve el estado del registro de idempotencia asociado a la key enviada en el header. Solo responde sobre keys de tu propio comercio.

Este endpoint está limitado a 10 consultas por minuto por API Key. Las keys se conservan 3 minutos después de procesar el pago, y 10 minutos mientras hay un challenge 3DS pendiente.

Configuración de la solicitud

Headers

Header	Descripción
`X-API-KEY`	API Key generada en Cubo Admin.
`x-idempotency-key`	La key del pago que deseas consultar.

Ejemplos de uso

JavaScript


fetch('https://<CUBO_API_URL>/api/v1/transactions/status', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'TU_API_KEY_AQUI',
    'x-idempotency-key': '3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607',
  },
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Respuestas del servidor

✅ Respuesta exitosa


{
  "idempotencyData": {
    "status": "APPROVED",
    "channel": "API",
    "transactionId": 48213,
    "createdAt": "2026-09-17T14:21:05.113Z",
    "updatedAt": "2026-09-17T14:23:40.882Z",
    "expiresAt": "2026-09-17T14:31:05.113Z"
  },
  "paymentIntentToken": "pi_9f8a7b6c",
  "status": "SUCCEEDED",
  "referenceId": "REF123456",
  "authorizationCode": "A1B2C3",
  "processedAt": "2026-09-17T14:23:40.882Z"
}

Campo	Tipo	Descripción
`status`	`string`	Estado de la key. Ver tabla de estados.
`channel`	`string`	Canal por el que se originó el pago.
`transactionId`	`number \| null`	Identificador de la transacción, si ya fue creada.
`createdAt`	`string`	Fecha y hora en que se registró la key (formato ISO 8601).
`updatedAt`	`string`	Fecha y hora del último cambio de estado (formato ISO 8601).
`expiresAt`	`string`	Fecha y hora en que expira la key (formato ISO 8601).

Junto a idempotencyData, la respuesta incluye lo último que la API devolvió para esa key: con APPROVED o DECLINED, la transacción con su paymentIntentToken; con PENDING_3DS, el challenge de la solicitud inicial. Así puedes recuperar el resultado de un pago aunque hayas perdido la respuesta original.

Estados de la key

`status`	Qué pasó	Qué hacer
`PENDING_3DS`	El challenge está emitido, esperando la confirmación.	Continúa con el challenge o con la consulta del resultado.
`PROCESSING`	El cobro se está procesando en este momento.	Espera y vuelve a consultar.
`APPROVED`	El pago ya se cobró.	Listo. No repitas el `POST`.
`DECLINED`	El pago fue rechazado.	Inicia un flujo nuevo con una key nueva.
`NOT_FOUND`	La key expiró, nunca existió o pertenece a otro comercio.	Empieza de cero con una key nueva.

NOT_FOUND es ambiguo: una key que nunca existió y una que ya expiró se ven igual. Como las keys se conservan solo 3 minutos después de procesar el pago, consulta el estado lo antes posible tras un timeout. Si ya expiró, usa el paymentIntentToken para consultar la transacción si lo tienes, o revisa el pago en Cubo Admin antes de volver a cobrar.

❌ Respuesta de error


{
  "statusCode": 429,
  "message": "Too Many Requests"
}