Pedidos do Merchant
Revise os pedidos de um Merchant no Dashboard — liste-os e filtre-os, abra um deles para ver o detalhe completo e emita um reembolso.
Um pedido é o registro de algo comprado: seus itens de linha, seu cliente e as transações que o pagaram. Esses endpoints sustentam a tela de pedidos do Dashboard.
Pedidos são criados por todos os caminhos de compra — uma cobrança direta via API, uma sessão de checkout concluída ou a renovação de uma assinatura — portanto, este é o único lugar que mostra o comércio em todos eles. Reembolsar aqui reverte os fundos capturados através do mesmo provedor que processou o pagamento.
Esses endpoints alimentam a Tokeflow Dashboard UI. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As requisições também carregam o cabeçalho x-merchant-id, identificando o Merchant em contexto, e o usuário autenticado deve ser um membro com acesso a ele.
Endpoints
GET/api/v1/merchant/orders
Auth: Dashboard session (JWT bearer). Merchant membership required.
Lista os pedidos do Merchant.
Parâmetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mínimo 1. |
limit | number | Não | Número de itens por página. Padrão 20, mínimo 1, máximo 100. |
status | array | Não | Lista de status de pedido separados por vírgula |
order_type | string | Não | Filtrar por tipo de pedido |
recurrence | string | Não | Filtrar por recorrência |
currency | string | Não | Filtrar por moeda (ISO 4217) |
search | string | Não | Buscar por ID do pedido, nome do cliente, e-mail ou ID externo do pedido |
start_date | string | Não | Data de início (ISO 8601) |
end_date | string | Não | Data de término (ISO 8601) |
mode | string | Não | live ou test. Apenas pedidos cujo pagamento mais recente que chegou a um provedor rodou em um conector de produção (ou de teste). Um pedido sem esse tipo de pagamento não corresponde a nenhum dos dois. |
subscription_id | string | Não | Filtrar por ID da assinatura |
Exemplo de requisição
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.
Obtém um pedido pelo ID.
O detalhe do pedido inclui as transações que o pagaram e cada uma das tentativas delas. Cada pedido e cada transação trazem um mode (live, test ou null quando nenhum pagamento chegou a um provedor), e cada tentativa traz is_test_mode. Uma tentativa que falhou também mostra decline_reason — o motivo da falha segundo a Tokeflow, o mesmo valor qualquer que seja o provedor que respondeu — ao lado de psp_decline_code e psp_error_type, o código e a classe de erro próprios do provedor, como ele os informou.
Parâmetros de caminho
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sim | — |
Exemplo de requisição
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.
Obtém a resposta bruta do PSP para uma tentativa.
Parâmetros de caminho
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sim | — |
attemptId | string | Sim | — |
Exemplo de requisição
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 um pedido.
Parâmetros de caminho
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sim | — |
Campos da requisição
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Não | Valor a reembolsar em unidades menores (reembolso parcial). Omita para reembolso total. |
reason | string | Não | Motivo do reembolso. Um dos seguintes: duplicate, fraudulent, requested_by_customer. |
Exemplo de requisição
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 os reembolsos de um pedido.
Parâmetros de caminho
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sim | — |
Parâmetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mínimo 1. |
limit | number | Não | Número de itens por página. Padrão 20, mínimo 1, máximo 100. |
Exemplo de requisição
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"Erros
Os erros usam o envelope padrão. Os casos mais comuns aqui:
| HTTP | Meaning |
|---|---|
400 | Parâmetros inválidos ou um estado que não permite esta operação. |
401 | Token de sessão do Dashboard ausente, expirado ou inválido. |
403 | Autenticado, mas o usuário autenticado não tem acesso a esta entidade. |
404 | O registro não existe ou não é visível para esta entidade. |