Ir al contenido

Estado de transacción

Ver .md

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.

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?».

Parámetro de ruta Descripción
paymentGateway El payment_id que te devolvió generar el pago, o el id del cobro creado desde el panel
POSThttps://sag.efipay.co/api/v1/payment/transaction-status/your-generated-payment-id
Ventana de terminal
curl -X POST \
'/api/v1/payment/transaction-status/9af329f1-e96a-40ab-b466-94a412f12c4a' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"
200OK
{
"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

Sección titulada «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ó:

Situación status status_key transaction_id
El cobro sigue vigente, nadie ha pagado Pendiente pending null
El cobro venció sin que nadie pagara Rechazada rejected null

En el segundo caso también enviamos el webhook transaction.expired, si al generar el cobro configuraste result_urls.webhook. Esta consulta sigue sirviendo cuando ese aviso no llegó.

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

Cobro ya vencido, el mismo cuerpo que viaja en transaction del webhook transaction.expired:

{
"data": {
"transaction_id": null,
"status": "Rechazada",
"status_key": "rejected",
"description": "Transacción Rechazada: Tiempo de espera excedido o transacción no iniciada o usuario abandono la transacción"
}
}

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.

POSThttps://sag.efipay.co/api/v1/payment/all-transaction-status/your-generated-payment-id
200OK
{
"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"
}
}

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.

POSThttps://sag.efipay.co/api/v1/payment/transaction/20481
Ventana de terminal
curl -X POST \
'/api/v1/payment/transaction/20481' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"
404Not Found
status Qué significa ¿Puedes despachar?
Iniciada El cliente abrió el checkout pero aún no pagó No
Pendiente El pago está en curso; esperamos confirmación de la red o del banco No — espera el webhook
Por Pagar Se generó un cupón de pago en efectivo y el cliente aún no lo paga No
Aprobada El pago se completó. El dinero es tuyo Sí
Autorizada Es una reserva de cupo: hay fondos retenidos pero no cobrados Según tu negocio; el dinero aún no entró
Rechazada La red o el banco no autorizaron No
Fallida No se pudo procesar No
Anulada Se anuló el mismo día No
Reversada Se devolvió el dinero al cliente No

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

Última actualización: