# Estado de transacción --- - [Estado de transacción](#estado-de-transaccion) - [Overview](#overview) - [Último intento de un cobro](#status) - [Todos los intentos de un cobro](#all-status) - [Una transacción puntual](#transaction) - [Estados posibles](#estados) ## Overview [#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](/webhook-transaction)**: 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. :::note 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 [#status] `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](/generate-transaction), o el id del cobro creado desde el panel | `POST /api/v1/payment/transaction-status/your-generated-payment-id` ```bash curl -X POST \ '/api/v1/payment/transaction-status/9af329f1-e96a-40ab-b466-94a412f12c4a' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H "Content-type: application/json" ``` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json { "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ó: | 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` | ```json { "data": { "transaction_id": null, "status": "Pendiente", "status_key": "pending", "description": "Pago generado, esperando inicio de la transacción" } } ``` :::note **`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. ::: :::caution 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 [#all-status] `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. `POST /api/v1/payment/all-transaction-status/your-generated-payment-id` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json { "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 [#transaction] `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`. `POST /api/v1/payment/transaction/20481` ```bash 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 ::: Código de respuesta: 404 ## Estados posibles [#estados] | 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](/mit-pre-authorization): 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](/resources#status-transaction). :::caution `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. :::