Pedidos del Merchant
Revisa los pedidos de un Merchant en el Dashboard — lístalos y fíltralos, abre uno para ver su detalle completo y emite un reembolso.
Un pedido es el registro de algo comprado: sus artículos de línea, su cliente y las transacciones que lo pagaron. Estos endpoints respaldan la pantalla de pedidos del Dashboard.
Los pedidos se crean a través de todas las rutas de compra — un cobro directo por API, una sesión de checkout completada o la renovación de una suscripción — por lo que este es el único lugar que muestra el comercio en todas ellas. Reembolsar aquí revierte los fondos capturados a través del mismo proveedor que procesó el pago.
Estos endpoints impulsan la Tokeflow Dashboard UI. 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 encabezado x-merchant-id, que identifica al Merchant en contexto, y el usuario que inició sesión debe ser un miembro con acceso a él.
Endpoints
GET/api/v1/merchant/orders
Auth: Dashboard session (JWT bearer). Merchant membership required.
Lista los pedidos del Merchant.
Parámetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mínimo 1. |
limit | number | No | Número de elementos por página. Predeterminado 20, mínimo 1, máximo 100. |
status | array | No | Lista de estados de pedido separados por comas |
order_type | string | No | Filtrar por tipo de pedido |
recurrence | string | No | Filtrar por recurrencia |
currency | string | No | Filtrar por moneda (ISO 4217) |
search | string | No | Buscar por ID del pedido, nombre del cliente, correo electrónico o ID externo del pedido |
start_date | string | No | Fecha de inicio (ISO 8601) |
end_date | string | No | Fecha de fin (ISO 8601) |
mode | string | No | live o test. Solo los pedidos cuyo pago más reciente que llegó a un proveedor se ejecutó en un conector en vivo (o de prueba). Un pedido sin un pago así no coincide con ninguno de los dos. |
subscription_id | string | No | Filtrar por ID de la suscripción |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/merchant/orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "status=['active']" \
--data-urlencode "order_type=api"GET/api/v1/merchant/orders/:id
Auth: Dashboard session (JWT bearer). Merchant membership required.
Obtiene un pedido por ID.
El detalle del pedido incluye las transacciones que lo pagaron y cada uno de sus intentos. Cada pedido y cada transacción llevan un mode (live, test, o null cuando ningún pago llegó a un proveedor), y cada intento lleva is_test_mode. Un intento fallido también muestra decline_reason — el motivo del fallo según Tokeflow, el mismo valor sea cual sea el proveedor que respondió — junto a psp_decline_code y psp_error_type, el código y la clase de error propios del proveedor tal como los informó.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchant/orders/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"GET/api/v1/merchant/orders/:id/attempts/:attemptId/raw-response
Auth: Dashboard session (JWT bearer). Merchant membership required.
Obtiene la respuesta sin procesar del PSP para un intento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
attemptId | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchant/orders/obj_1a2b3c4d/attempts/123/raw-response \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"POST/api/v1/merchant/orders/:id/refund
Auth: Dashboard session (JWT bearer). Merchant membership required.
Reembolsa un pedido.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | No | Monto a reembolsar en unidades menores (reembolso parcial). Omitir para reembolso total. |
reason | string | No | Motivo del reembolso. Uno de los siguientes: duplicate, fraudulent, requested_by_customer. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchant/orders/obj_1a2b3c4d/refund \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"reason": "requested_by_customer"
}'GET/api/v1/merchant/orders/:id/refunds
Auth: Dashboard session (JWT bearer). Merchant membership required.
Lista los reembolsos de un pedido.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Parámetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mínimo 1. |
limit | number | No | Número de elementos por página. Predeterminado 20, mínimo 1, máximo 100. |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/merchant/orders/obj_1a2b3c4d/refunds \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"Errores
Los errores usan el envelope estándar. Los casos más comunes aquí:
| HTTP | Meaning |
|---|---|
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. |