Transacciones de la Organization
Revisa las transacciones de todos los Merchants de la Organization desde el Dashboard — inspecciona intentos, reembolsa y anula (void).
Estos endpoints consolidan transacciones de todos los Merchants de la Organization: filtra y abre un cobro, recorre su cronología de enrutamiento por intento y actúa sobre él — reembolsa fondos capturados o anula (void) una autorización.
Es la ventana a toda la actividad de pago de la Organization. El objeto transacción y su cronología coinciden con los de la API pública; esta vista los agrega entre Merchants para supervisión y soporte.
Estos endpoints impulsan la interfaz del Tokeflow Dashboard a nivel de la Organization. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-organization-id, y el usuario que inició sesión debe ser miembro de esa Organization.
El objeto transacción
Devuelto por los endpoints de listado y recuperación de esta página.
| Campo | Tipo | Descripción |
|---|---|---|
id | string | ID de la transacción. |
organization_id | string | ID de la Organization. |
merchant_id | string | ID del Merchant. |
order_id | string | null | ID del pedido creado automáticamente. |
subscription_id | string | null | Suscripción creada a partir de esta CIT, cuando la oferta subyacente es recurrente. Null para cobros únicos y para pedidos no recurrentes. |
external_order_id | string | null | ID de pedido externo del sistema del Merchant. |
customer_id | string | null | ID del cliente. |
payment_instrument_id | string | null | ID del instrumento de pago usado en la transacción. |
amount_authorized | number | Importe autorizado en unidades menores. |
amount_captured | number | Importe capturado en unidades menores. |
currency | string | Código de moneda ISO 4217. |
payment_method | string | Método de pago. Uno de credit_card, debit_card, pix, boleto, wallet. |
charge_type | string | Tipo de cobro. Uno de payment, setup_verification. |
country | string | Código de país ISO 3166-1 alpha-2. |
status | string | Estado de la transacción. Uno de pending, pre_authorized, authorized, failed, canceled, voided, charged_back, refund_pending, capture_pending, refunded, partially_refunded, expired. |
applied_routing_rule_id | string | null | Nodo de la regla de enrutamiento que produjo el intento exitoso. |
mode | string | null | live o test — si el pago se ejecutó con credenciales de proveedor en vivo o de prueba (el conector del intento final). Null cuando no se hizo ningún intento. |
timeline | array | Cronología de los intentos de la transacción con fallbacks de enrutamiento. |
payment_instructions | object | null | Instrucciones de pago para métodos asíncronos (PIX, boleto). Null para transacciones síncronas de tarjeta. |
metadata | object | null | Metadatos proporcionados por el Merchant. |
created_at | string | Marca de tiempo de creación. (ISO 8601 UTC). |
updated_at | string | Marca de tiempo de la última actualización. (ISO 8601 UTC). |
Endpoints
GET/api/v1/org/transactions
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Lista las transacciones del Merchant.
Parámetros de consulta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mín. 1. |
limit | number | No | Cantidad de elementos por página. Predeterminado 20, mín. 1, máx. 100. |
status | array | No | Lista separada por comas de estados de transacción para filtrar |
merchant_id | string | No | Filtra las transacciones por ID del Merchant |
customer_reference | string | No | Filtra las transacciones por referencia del cliente |
order_id | string | No | Filtra las transacciones por ID del pedido |
date_from | string | No | Filtra transacciones creadas después de esta fecha (ISO 8601) |
date_to | string | No | Filtra transacciones creadas antes de esta fecha (ISO 8601) |
payment_method | string | No | Filtra las transacciones por método de pago |
currency | string | No | Filtra las transacciones por moneda (ISO 4217) |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/transactions \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "status=pending,authorized,failed" \
--data-urlencode "merchant_id=mrc_123"GET/api/v1/org/transactions/:id
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Obtiene una transacción por ID.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"Ejemplo de respuesta — 200
{
"id": "tx_777",
"organization_id": "org_123",
"merchant_id": "mrc_123",
"order_id": "ord_001",
"subscription_id": "sub_001",
"external_order_id": "order_888",
"customer_id": "cust_123",
"payment_instrument_id": "pi_123",
"amount_authorized": 15000,
"amount_captured": 15000,
"currency": "BRL",
"payment_method": "credit_card",
"charge_type": "payment",
"country": "BR",
"status": "authorized",
"applied_routing_rule_id": "node_2",
"mode": "live",
"timeline": [
{
"attempt_number": 1,
"is_fallback": false,
"connector_id": "conn_a1b2c3",
"provider_slug": "provider_b",
"status": "success",
"error_category": "TECH_ERROR",
"error_code": "TIMEOUT",
"decline_reason": "timeout",
"started_at": "2025-11-28T13:00:00Z",
"finished_at": "2025-11-28T13:00:05Z"
}
],
"payment_instructions": {
"type": "pix",
"qr_code_text": "00020126580014BR.GOV.BCB.PIX...",
"qr_code_url": "https://psp-url.com/qrcode/image.png",
"barcode": "string",
"boleto_url": "https://example.com/webhooks/tokeflow",
"due_date": "string",
"expires_at": "2025-11-28T13:30:00Z"
},
"metadata": {},
"created_at": "2025-11-28T13:00:00Z",
"updated_at": "2025-11-28T13:00:09Z"
}GET/api/v1/org/transactions/:id/attempts
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Lista los intentos de la transacción.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/attempts \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"POST/api/v1/org/transactions/:id/capture
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Captura una transacción autorizada.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
amount | number | No | Importe opcional a capturar en centavos/unidad menor. Si no se proporciona, se capturará el importe autorizado completo. Para captura parcial, debe ser menor o igual a amount_authorized. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/capture \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000
}'Ejemplo de respuesta — 200
{
"id": "tx_777",
"organization_id": "org_123",
"merchant_id": "mrc_123",
"order_id": "ord_001",
"subscription_id": "sub_001",
"external_order_id": "order_888",
"customer_id": "cust_123",
"payment_instrument_id": "pi_123",
"amount_authorized": 15000,
"amount_captured": 15000,
"currency": "BRL",
"payment_method": "credit_card",
"charge_type": "payment",
"country": "BR",
"status": "authorized",
"applied_routing_rule_id": "node_2",
"mode": "live",
"timeline": [
{
"attempt_number": 1,
"is_fallback": false,
"connector_id": "conn_a1b2c3",
"provider_slug": "provider_b",
"status": "success",
"error_category": "TECH_ERROR",
"error_code": "TIMEOUT",
"decline_reason": "timeout",
"started_at": "2025-11-28T13:00:00Z",
"finished_at": "2025-11-28T13:00:05Z"
}
],
"payment_instructions": {
"type": "pix",
"qr_code_text": "00020126580014BR.GOV.BCB.PIX...",
"qr_code_url": "https://psp-url.com/qrcode/image.png",
"barcode": "string",
"boleto_url": "https://example.com/webhooks/tokeflow",
"due_date": "string",
"expires_at": "2025-11-28T13:30:00Z"
},
"metadata": {},
"created_at": "2025-11-28T13:00:00Z",
"updated_at": "2025-11-28T13:00:09Z"
}POST/api/v1/org/transactions/:id/refund
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Reembolsa una transacción capturada.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
amount | number | No | Importe a reembolsar en centavos/unidad menor. Si no se proporciona, se reembolsará el importe completo. |
reason | string | No | Motivo del reembolso. Uno de duplicate, fraudulent, requested_by_customer. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/refund \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"reason": "requested_by_customer"
}'Ejemplo de respuesta — 200
{
"id": "tx_777",
"refund_id": "ref_abc123",
"status": "refund_pending",
"amount_captured": 15000,
"amount_refunded": 5000,
"total_refunded": 5000,
"updated_at": "2025-11-28T13:07:00Z"
}GET/api/v1/org/transactions/:id/refunds
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Lista los reembolsos de una transacción.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Parámetros de consulta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mín. 1. |
limit | number | No | Cantidad de elementos por página. Predeterminado 20, mín. 1, máx. 100. |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/refunds \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"POST/api/v1/org/transactions/:id/void
Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.
Anula (void) una transacción autorizada.
Parámetros de ruta
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/void \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"Ejemplo de respuesta — 200
{
"id": "tx_777",
"status": "voided",
"updated_at": "2025-11-28T13:06:00Z"
}Errores
Los errores usan el envelope estándar. Los casos más comunes aquí:
| HTTP | Significado |
|---|---|
400 | Parámetros inválidos o un estado que no permite esta operación. |
401 | Token de sesión del Dashboard ausente, expirado o inválido. |
403 | Autenticado, pero el usuario que inició sesión no tiene acceso a esta entidad. |
404 | El registro no existe o no es visible para esta entidad. |