Estado de transacción

• Estado de transacción
  • Overview
  • Último intento de un cobro
  • Todos los intentos de un cobro
  • Una transacción puntual
  • Estados posibles

Overview

Cuando generas un cobro y rediriges a tu cliente al checkout, tú no ves el resultado: lo ve él. Estos endpoints existen para que tu sistema pueda averiguarlo.

Lo recomendable es el webhook: te avisamos nosotros y no tienes que preguntar. Consulta el estado cuando el webhook no llegó, cuando quieres confirmar antes de despachar un pedido, o cuando reconstruyes el estado de un cobro antiguo.

{info} Un mismo cobro puede tener varios intentos: el cliente puede haber sido rechazado y reintentado. Por eso hay un endpoint para el último intento y otro para todos.

Último intento de un cobro

POST /api/v1/payment/transaction-status/{paymentGateway}

Descripción: Devuelve la transacción más reciente asociada al cobro. Es lo que quieres el 90 % de las veces: «¿cómo quedó esto?».

curl -X POST \
'/api/v1/payment/transaction-status/9af329f1-e96a-40ab-b466-94a412f12c4a' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"

{success} Respuesta satisfactoria code: 200

{
"data": {
"transaction_id": 20481,
"amount": 120000,
"currency_type": "COP",
"value_cop": 120000,
"payment_method": "credit",
"payment_method_source": "Visa",
"trazability_id": "320000303129",
"authorization_code": "005077",
"status": "Aprobada",
"approved_at": "2026-07-15T14:32:10.000000Z",
"production": true,
"created_at": "2026-07-15T14:32:05.000000Z",
"description": "Aprobada"
}
}

Cuando el cobro todavía no tiene transacción

Si nadie llegó a pagar, no hay transaction_id que devolver. La respuesta llega igual, con los campos en null y un status que dice en qué quedó:

{
    "data": {
        "transaction_id": null,
        "status": "Pendiente",
        "status_key": "pending",
        "description": "Pago generado, esperando inicio de la transacción"
    }
}

{info} transaction_id solo falta en este caso. En cuanto existe una transacción —aprobada, rechazada o pendiente— el consecutivo viene siempre. Si necesitas un identificador de correlación antes de eso, usa el payment_id del cobro: lo tienes desde que lo generaste, y las respuestas del checkout también lo devuelven.

{warning} No confundas Pendiente con «pendiente de confirmación de la red». Aquí significa nadie ha intentado pagar todavía: el cobro sigue abierto.

Todos los intentos de un cobro

POST /api/v1/payment/all-transaction-status/{paymentGateway}

Descripción: Devuelve todos los intentos del cobro, del más reciente al más antiguo, más el último por separado en last. Úsalo para auditar: ver cuántas veces intentó tu cliente y por qué le rechazaron antes de aprobar.

{success} Respuesta satisfactoria code: 200

{
"transactions": [
{
"transaction_id": 20481,
"status": "Aprobada",
"payment_method_source": "Visa",
"authorization_code": "005077",
"created_at": "2026-07-15T14:32:05.000000Z",
"description": "Aprobada"
},
{
"transaction_id": 20479,
"status": "Rechazada",
"payment_method_source": "Visa",
"authorization_code": null,
"created_at": "2026-07-15T14:28:41.000000Z",
"description": "Transacción declinada. Fondos insuficientes"
}
],
"last": {
"transaction_id": 20481,
"status": "Aprobada",
"description": "Aprobada"
}
}

Una transacción puntual

POST /api/v1/payment/transaction/{transaction}

Descripción: Devuelve una transacción por su transaction_id (el número consecutivo) o por su id (el UUID). Sirve cuando ya tienes identificada la transacción —por ejemplo, la que te llegó por webhook— y quieres releerla.

Solo devuelve transacciones de tu comercio; cualquier otra da 404.

curl -X POST \
'/api/v1/payment/transaction/20481' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"

{danger} La transacción no existe o no es de tu comercio code: 404

Estados posibles

El catálogo completo, con etiquetas y colores, está en GET /api/v1/resources/get-status-transaction — ver Recursos.

{warning} Pendiente no es «rechazada». Si marcas el pedido como fallido al ver un Pendiente, vas a rechazar pagos que sí se aprueban segundos después. Espera el webhook.