Transações da Organization
Revise as transações de todos os Merchants da Organization a partir do Dashboard — inspecione tentativas, reembolse e cancele (void).
Esses endpoints consolidam transações de todos os Merchants da Organization: filtre e abra uma cobrança, percorra sua linha do tempo de roteamento por tentativa e aja sobre ela — reembolse fundos capturados ou cancele (void) uma autorização.
É a janela para toda a atividade de pagamento da Organization. O objeto transação e sua linha do tempo correspondem aos da API pública; esta visão os agrega entre Merchants para supervisão e suporte.
Esses endpoints alimentam a interface do Tokeflow Dashboard no nível da Organization. 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 solicitações também carregam o header x-organization-id, e o usuário autenticado deve ser membro dessa Organization.
O objeto transação
Retornado pelos endpoints de listagem e recuperação desta página.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID da transação. |
organization_id | string | ID da Organization. |
merchant_id | string | ID do Merchant. |
order_id | string | null | ID do pedido criado automaticamente. |
subscription_id | string | null | Assinatura criada a partir desta CIT, quando a oferta subjacente é recorrente. Null para cobranças avulsas e para pedidos não recorrentes. |
external_order_id | string | null | ID de pedido externo do sistema do Merchant. |
customer_id | string | null | ID do cliente. |
payment_instrument_id | string | null | ID do instrumento de pagamento usado na transação. |
amount_authorized | number | Valor autorizado em unidades menores. |
amount_captured | number | Valor capturado em unidades menores. |
currency | string | Código de moeda ISO 4217. |
payment_method | string | Método de pagamento. Um de credit_card, debit_card, pix, boleto, wallet. |
charge_type | string | Tipo de cobrança. Um de payment, setup_verification. |
country | string | Código de país ISO 3166-1 alpha-2. |
status | string | Status da transação. Um de pending, pre_authorized, authorized, failed, canceled, voided, charged_back, refund_pending, capture_pending, refunded, partially_refunded, expired. |
applied_routing_rule_id | string | null | Nó da regra de roteamento que produziu a tentativa bem-sucedida. |
mode | string | null | live ou test — se o pagamento rodou com credenciais de provedor de produção ou de teste (o conector da tentativa final). Null quando nenhuma tentativa foi feita. |
timeline | array | Linha do tempo das tentativas da transação com fallbacks de roteamento. |
payment_instructions | object | null | Instruções de pagamento para métodos assíncronos (PIX, boleto). Null para transações síncronas de cartão. |
metadata | object | null | Metadados fornecidos pelo Merchant. |
created_at | string | Timestamp de criação. (ISO 8601 UTC). |
updated_at | string | Timestamp da última atualização. (ISO 8601 UTC). |
Endpoints
GET/api/v1/org/transactions
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Lista as transações do Merchant.
Parâmetros de consulta
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mín. 1. |
limit | number | Não | Número de itens por página. Padrão 20, mín. 1, máx. 100. |
status | array | Não | Lista separada por vírgulas de status de transação para filtrar |
merchant_id | string | Não | Filtra as transações por ID do Merchant |
customer_reference | string | Não | Filtra as transações por referência do cliente |
order_id | string | Não | Filtra as transações por ID do pedido |
date_from | string | Não | Filtra transações criadas após esta data (ISO 8601) |
date_to | string | Não | Filtra transações criadas antes desta data (ISO 8601) |
payment_method | string | Não | Filtra as transações por método de pagamento |
currency | string | Não | Filtra as transações por moeda (ISO 4217) |
Exemplo de requisição
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). É necessário ser membro da Organization.
Obtém uma transação pelo ID.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Exemplo de requisição
curl https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"Exemplo de resposta — 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). É necessário ser membro da Organization.
Lista as tentativas da transação.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Exemplo de requisição
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). É necessário ser membro da Organization.
Captura uma transação autorizada.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | Não | Valor opcional a capturar em centavos/unidade menor. Se não for fornecido, o valor autorizado total será capturado. Para captura parcial, deve ser menor ou igual a amount_authorized. |
Exemplo de requisição
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
}'Exemplo de resposta — 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). É necessário ser membro da Organization.
Reembolsa uma transação capturada.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | Não | Valor a reembolsar em centavos/unidade menor. Se não for fornecido, o valor total será reembolsado. |
reason | string | Não | Motivo do reembolso. Um de duplicate, fraudulent, requested_by_customer. |
Exemplo de requisição
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"
}'Exemplo de resposta — 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). É necessário ser membro da Organization.
Lista os reembolsos de uma transação.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Parâmetros de consulta
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mín. 1. |
limit | number | Não | Número de itens por página. Padrão 20, mín. 1, máx. 100. |
Exemplo de requisição
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). É necessário ser membro da Organization.
Cancela (void) uma transação autorizada.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Exemplo de requisição
curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/void \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"Exemplo de resposta — 200
{
"id": "tx_777",
"status": "voided",
"updated_at": "2025-11-28T13:06:00Z"
}Erros
Os erros usam o envelope padrão. Os casos mais comuns aqui:
| HTTP | Significado |
|---|---|
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. |