Transacciones
Una transacción (referencia txn_…) es un movimiento de dinero. Se crea cuando un comprador paga una sesión.
Listar transacciones
GET /v1/transactionsAutenticación: clave secreta (Authorization: Bearer sk_…).
Parámetros de consulta
| Parámetro | Tipo | Descripción |
|---|---|---|
page | entero | Página (desde 1). Por defecto 1. |
pageSize | entero | Tamaño de página. Por defecto 10. |
status | string | Filtra por estado: approved, declined, failed, pending, refunded. |
Ejemplo
curl "https://api.seif.pagosripei.com/v1/transactions?status=declined&page=1&pageSize=20" \
-H "Authorization: Bearer sk_test_tu_clave"Respuesta 200
{
"data": [
{
"id": "b1d3...-aa",
"reference": "txn_2nFp9...Zk",
"amountCents": 105000,
"currency": "VES",
"status": "declined",
"cardBrand": "visa",
"cardLast4": "4242",
"description": "Pedido #1042",
"errorCode": "0051",
"errorReason": "Saldo insuficiente",
"createdAt": "2026-06-09T18:05:00.000Z"
}
],
"total": 1,
"page": 1,
"pageSize": 20
}| Campo | Descripción |
|---|---|
reference | Referencia pública (txn_…). |
amountCents | Monto en unidades menores. |
status | pending · approved · declined · failed · refunded. |
cardBrand / cardLast4 | Marca y últimos 4 dígitos (enmascarado). |
errorCode | Código del procesador, presente en declined/failed. |
errorReason | Motivo técnico para tu depuración (no es el mensaje del comprador). |
El errorReason te dice por qué falló un cobro sin tener que revisar logs.
Para la lista completa de códigos y cómo resolverlos, ver Errores.
Consultar el estado de una transacción
GET /v1/transactions/{referencia}/statusAutenticación: clave secreta (Authorization: Bearer sk_…) o tu sesión del
dashboard.
Respuesta liviana (sin traza de eventos) pensada para reconciliar un cobro:
es el endpoint que consultas para construir tu propio trabajo de confirmación.
Si la transacción sigue en pending, este endpoint la actualiza en el momento
contra la pasarela antes de responder (y dispara el webhook si ya se resolvió);
las transacciones ya terminadas responden directo desde nuestra base de datos.
Ejemplo
curl "https://api.seif.pagosripei.com/v1/transactions/txn_2nFp9...Zk/status" \
-H "Authorization: Bearer sk_test_tu_clave"Respuesta 200
{
"reference": "txn_2nFp9...Zk",
"status": "approved",
"amountCents": 105000,
"currency": "VES",
"processorReference": "9f3c...",
"authorizationCode": "123456",
"declineReason": null,
"errorCode": null,
"processedAt": "2026-06-09T18:05:03.000Z",
"updatedAt": "2026-06-09T18:05:03.000Z"
}| Campo | Descripción |
|---|---|
status | pending · approved · declined · failed · refunded · voided. |
processorReference | Referencia de la pasarela (para conciliación con tu banco). |
authorizationCode | Código de autorización, presente en approved. |
declineReason | Motivo en español, presente en declined/failed. |
processedAt | Cuándo llegó a un estado final (null si sigue pending). |
Un pending significa que el cobro se sigue confirmando. Vuelve a consultar en
unos segundos — o mejor, deja que el webhook te avise (ver abajo).
Estados de una transacción
| Estado | ¿Qué pasó? | ¿Acción? |
|---|---|---|
pending | En proceso. | Espera el webhook o consulta de nuevo. |
approved | Aprobada por el banco. | Entrega el producto/servicio. |
declined | Rechazada por el banco/tarjeta. | Muestra el motivo al comprador; sugiérele otra tarjeta. |
failed | No se pudo procesar (config/red/procesador). | Revisa errorReason; reintenta más tarde. |
refunded | Reembolsada. | — |
Para reaccionar en tiempo real, suscríbete a webhooks (charge.approved,
charge.declined, charge.failed) en vez de hacer polling. Ver
Webhooks. Si necesitas un trabajo de conciliación propio, usa
consultar el estado — reconcilia un
pending en el momento.