Transações

Crie, liste, capture e cancele transações de pagamento através do motor de orquestração da Tokeflow — com roteamento inteligente, linhas do tempo de fallback e criação idempotente.

Uma transação é uma única tentativa de movimentar dinheiro para um pedido através do motor de orquestração da Tokeflow. Você descreve a intenção — valor, moeda, método de pagamento, país e a origem do cartão — e a Tokeflow roteia a cobrança entre os provedores de pagamento que você conectou, aplicando suas regras de roteamento e encadeando em cascata para um provedor de fallback quando um deles recusa ou dá erro.

A Tokeflow orquestra a cobrança; ela não processa nem liquida fundos. Autorização, captura e liquidação são realizadas pelos provedores de pagamento conectados. A Tokeflow normaliza o comportamento deles atrás de um objeto de transação único e consistente, para que sua integração permaneça a mesma independentemente de qual provedor processe o pagamento.

Toda transação registra uma linha do tempo de tentativas de roteamento — qual conector foi tentado, em que ordem e como cada um respondeu. Essa linha do tempo é sua trilha de auditoria e sua ferramenta de depuração. Veja A linha do tempo.

Como uma transação flui

Uma única chamada de API pode se ramificar para vários provedores nos bastidores. Os formatos de requisição e resposta são estáveis independentemente de qual provedor acaba autorizando a cobrança.

O objeto de transação

Field	Type	Description
`id`	string	ID da transação, prefixado com `tx_`.
`organization_id`	string	Organization proprietária, prefixada com `org_`.
`merchant_id`	string	Merchant proprietário, prefixado com `mrc_`.
`order_id`	string \| null	Pedido ao qual esta cobrança pertence, prefixado com `ord_`. A Tokeflow cria um pedido automaticamente para cobranças diretas via API.
`subscription_id`	string \| null	Assinatura criada a partir desta cobrança quando a oferta subjacente é recorrente, prefixada com `sub_`. Nula caso contrário.
`external_order_id`	string \| null	Sua própria referência de pedido, devolvida para reconciliação.
`customer_id`	string \| null	Cliente ao qual a cobrança é atribuída, prefixado com `cust_`.
`payment_instrument_id`	string \| null	Instrumento salvo utilizado, prefixado com `pi_`. Nulo para cobranças avulsas de cartão ou assíncronas.
`amount_authorized`	integer	Valor autorizado, em unidades menores.
`amount_captured`	integer	Valor capturado, em unidades menores.
`currency`	string	Código de moeda ISO 4217.
`payment_method`	string	Um de `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`.
`charge_type`	string	`payment` ou `setup_verification`.
`country`	string	Código de país ISO 3166-1 alpha-2.
`status`	string	Status atual da transação. Veja Ciclo de vida do status.
`applied_routing_rule_id`	string \| null	O 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, conforme o conector da tentativa final. Nulo quando nenhuma tentativa foi feita (a cobrança foi recusada antes do roteamento).
`timeline`	array	Lista ordenada de tentativas de roteamento. Veja A linha do tempo.
`payment_instructions`	object \| null	Instruções voltadas ao cliente para métodos assíncronos (PIX, boleto). Nulo para cobranças síncronas de cartão.
`metadata`	object \| null	Pares chave-valor arbitrários que você anexou na criação.
`created_at`	string	Timestamp de criação (ISO 8601 UTC).
`updated_at`	string	Timestamp da última atualização (ISO 8601 UTC).

A linha do tempo

A timeline é o registro ordenado de cada tentativa de provedor que a Tokeflow realizou para esta transação. É como a cascata e o fallback se tornam observáveis.

Field	Type	Description
`attempt_number`	integer	Número sequencial da tentativa, começando em 1.
`is_fallback`	boolean	`true` se esta tentativa só foi executada porque uma tentativa anterior falhou.
`connector_id`	string	O conector usado para esta tentativa.
`provider_slug`	string	Slug neutro para o provedor por trás do conector.
`status`	string	`pending`, `success`, `failed` ou `error`.
`started_at`	string	Quando a tentativa começou (ISO 8601 UTC).
`finished_at`	string \| null	Quando a tentativa foi resolvida (ISO 8601 UTC), ou nulo se ainda pendente.
`error_category`	string \| null	Classe de erro de alto nível quando a tentativa não teve sucesso.
`error_code`	string \| null	Código de erro normalizado quando a tentativa não teve sucesso.
`decline_reason`	string \| null	Por que a tentativa falhou, nas palavras da própria Tokeflow — o mesmo valor qualquer que seja o provedor que respondeu. Veja Motivos de recusa. Nulo quando nenhum motivo é conhecido.

Para uma visão mais rica, por tentativa — incluindo status de 3DS, mensagens de erro normalizadas e taxas de gateway — chame GET /transactions/:id/attempts.

Ciclo de vida do status

O enum status completo:

pending, pre_authorized, authorized, failed, canceled, voided, charged_back, refund_pending, capture_pending, refunded, partially_refunded, expired.

Uma cobrança que falha não é um erro HTTP. Quando um provedor recusa, a Tokeflow ainda retorna 201 Created com status: "failed" e uma linha do tempo explicando o motivo. Sempre ramifique com base no campo status — nunca presuma que uma resposta 2xx significa que o dinheiro foi autorizado.

Quando o provedor não dá resposta

Uma cobrança de cartão também pode voltar como pending. Isso acontece quando o provedor foi solicitado a movimentar dinheiro, mas não deu um veredito — um timeout, uma resposta ilegível ou um erro de servidor do lado dele. A cobrança pode ou não ter sido efetivada, então a Tokeflow não a trata como uma recusa: não encadeia em cascata para um conector de fallback (isso poderia cobrar o cliente duas vezes) e não inicia o dunning em uma renovação. A transação permanece pending enquanto a Tokeflow apura o resultado com o provedor e, em seguida, passa para o status final, que chega até você pelos webhooks de transação habituais. Uma sessão de checkout paga por uma cobrança assim é liquidada no mesmo momento.

Não repita uma cobrança de cartão pending com uma nova chave de idempotência. Aguarde o status final ou leia-o de volta com GET /transactions/:id.

Motivos de recusa

Toda tentativa que falha traz um decline_reason: o nome que a Tokeflow dá ao motivo da falha. Os códigos de recusa próprios de cada provedor são mapeados para esse vocabulário único, de modo que insufficient_funds significa a mesma coisa qualquer que seja o conector que respondeu. error_category e error_code continuam sendo os campos que guiam as retentativas; decline_reason é o que você mostra ao seu time de suporte, agrupa em relatórios ou transforma em uma mensagem para o cliente.

Grupo	Motivos
Emissor	`do_not_honor`, `generic_decline`, `call_issuer`, `try_again_later`, `issuer_unavailable`, `invalid_transaction`, `transaction_not_permitted`, `do_not_retry`
Saldo e limites	`insufficient_funds`, `limit_exceeded`, `max_attempts`
Dados do cartão	`invalid_card_number`, `invalid_cvv`, `invalid_expiry`, `incorrect_pin`, `invalid_amount`, `invalid_installments`
Situação do cartão	`card_expired`, `lost_or_stolen`, `pickup_card`, `card_restricted`, `card_inactive`, `account_closed`, `account_updated`, `authorization_revoked`, `card_not_supported`, `currency_not_supported`, `test_card_used`
Fraude e risco	`fraud_suspected`, `risk_blocked`, `blocklisted`
Autenticação	`authentication_required`, `authentication_failed`
Requisição	`duplicate_transaction`, `invalid_request`, `invalid_token`
Provedor	`processing_error`, `provider_unavailable`, `timeout`, `rate_limited`, `invalid_credentials`
Não mapeado	`other` — o provedor deu um motivo que ainda não tem nome na Tokeflow.

A lista só cresce: um motivo nunca é renomeado nem removido, e novos motivos são adicionados com o tempo. Armazene o valor como string e trate um valor desconhecido como other.

O motivo também decide como a Tokeflow roteia a recusa, da mesma forma para todos os provedores:

Em uma cobrança iniciada pelo cliente, recusas temporárias do emissor e de saldo (do_not_honor, generic_decline, try_again_later, issuer_unavailable, insufficient_funds) são retentadas uma vez no mesmo conector e depois encadeadas em cascata para os seus fallbacks. Todos os outros motivos de recusa interrompem a cobrança sem cascata — dados do cartão, situação do cartão, fraude e risco, e respostas do emissor como call_issuer ou transaction_not_permitted, que outra tentativa agora não mudaria. O cliente precisa corrigir o cartão, falar com o banco ou usar outro cartão.
Em uma renovação de assinatura, nada é retentado dentro da requisição. Um motivo que diz que o cartão nunca mais poderá ser cobrado (lost_or_stolen, pickup_card, card_restricted, account_closed, account_updated, authorization_revoked, card_not_supported, currency_not_supported, test_card_used, do_not_retry, fraud_suspected, blocklisted) cancela a assinatura. Todas as outras recusas — incluindo cartões vencidos, dados de cartão incorretos e risk_blocked — levam a assinatura ao dunning, para que o cliente ainda possa atualizar o cartão.

Tipo de cobrança

Value	Meaning
`payment`	Uma cobrança real por bens ou serviços. Usa `amount`.
`setup_verification`	Uma verificação de valor zero ou nominal usada para validar e armazenar um cartão para cobranças futuras, sem cobrar o cliente.

Origens de cartão

Toda cobrança de cartão precisa de uma origem de cartão. Escolha a combinação que corresponde ao seu cenário:

Cenário	Campo a enviar	Observações
Cartão novo	`card_ciphertext_id`	A referência de cartão criptografada de uso único (`tok_…`) retornada pelo Bridge SDK. Adicione `save_payment_instrument: true` para também salvar o cartão para depois.
Cartão salvo, cliente redigita o CVV	`payment_instrument_id` + `card_ciphertext_id`	Um instrumento armazenado, prefixado com `pi_`, mais um ciphertext novo do mesmo cartão.
Cartão salvo, um clique	`payment_instrument_id` + `credential_on_file: true`	Cobra a credencial do provedor guardada no cadastro. Sem dados de cartão, sem CVV. Veja Cobranças com credencial armazenada.
Checkout	`checkout_session_id`	Cobre uma sessão de checkout concluída, prefixada com `cks_`.
Checkout, cartão salvo	`checkout_session_id` + `payment_instrument_id` + `credential_on_file: true`	Paga a sessão com o cartão salvo do cliente, sem redigitar o cartão. Exige o opt-in `saved_card_checkout_enabled` do merchant. Veja Checkout com cartão salvo.

payment_instrument_id sozinho é recusado com 400. Um cartão salvo é cobrado com credential_on_file: true ou com um card_ciphertext_id novo — um dos dois precisa dizer como o cartão está sendo apresentado.

Nunca envie dados brutos de cartão para este endpoint. Os campos seguros da Tokeflow são executados dentro de iframes isolados de origem cruzada; os dados do cartão são criptografados no navegador e nunca tocam seus servidores. O navegador recebe uma referência de cartão criptografada de uso único (tok_…), que você passa como card_ciphertext_id. Para os métodos PIX, boleto e wallet, nenhuma origem de cartão é necessária.

Precisa de um tok_… para testar este endpoint? Use o testador hospedado do Bridge SDK em card.tokeflow.com: execute-o contra seu merchant com uma chave pública, depois copie a referência de cartão criptografada retornada e envie-a aqui como card_ciphertext_id. Veja Teste o Bridge SDK sem código.

Cobranças com credencial armazenada (one-click)

Duas flags booleanas transformam uma cobrança comum nas duas metades de um fluxo em um clique — o padrão por trás dos upsells e downsells pós-compra. O guia passo a passo é Upsells e downsells em um clique; esta seção é a referência dos campos.

`save_payment_instrument`

Salva o cartão por trás de card_ciphertext_id como um instrumento de pagamento do customer_id antes de a cobrança rodar e, em seguida, cobra o ciphertext enviado. Quando o provedor aprova, a credencial reutilizável dele para o cartão fica guardada nesse conector, para que cobranças credential_on_file posteriores possam usá-la. A resposta traz o novo payment_instrument_id.

Regra	Detalhe
Exige	`card_ciphertext_id` emitido com `purpose=instrument_enrollment` — pelo Bridge SDK com `purpose: 'instrument_enrollment'` (standalone) ou `saveCard: true` (dentro de uma sessão de checkout). `customer_id`. Um método de pagamento com cartão.
Recusado com	`checkout_session_id` (lá quem governa é o `save_card` da sessão), `payment_instrument_id`, `credential_on_file`.
Ciphertext `one_time`	`400 validation_error` — o token não pode ser salvo. Nada é cobrado.
Cartão já existente	Se o cliente já tem esse cartão em arquivo, o instrumento existente é reutilizado.

`credential_on_file`

Cobra o payment_instrument_id salvo com a credencial do provedor guardada no cadastro — sem dados de cartão, sem CVV. Destinado a cobranças com o cliente presente e não agendadas, como um upsell em um clique; cobranças agendadas pertencem às assinaturas.

Regra	Detalhe
Exige	`payment_instrument_id` (deve pertencer ao cliente e estar `active`) e um método de pagamento com cartão. Sem uma sessão de checkout, também `customer_id`.
Recusado com	`card_ciphertext_id`, `save_payment_instrument`, `capture: false`.
Com `checkout_session_id`	Paga a sessão com o cartão salvo: a sessão fornece valor, moeda, cliente e parcelas. Exige o opt-in `saved_card_checkout_enabled` do merchant. Veja Checkout com cartão salvo.
Pré-requisito	O instrumento guarda uma credencial obtida em uma cobrança com o portador presente ou uma verificação de cartão bem-sucedida em um conector cujo provedor suporte cobranças com credencial armazenada. Caso contrário, `400 validation_error`.
Roteamento	Fixado no conector ativo que guarda a credencial utilizável mais recente do instrumento. Regras de roteamento e cascata não se aplicam; se esse conector não puder receber a cobrança (moeda, parcelas), a requisição é recusada com `422`.
Captura	Sempre autorização + captura.
Pedido	Criado com `recurrence: "unscheduled"`.
Metadados	`stored_credential_usage: "customer_initiated"` é mesclado em `metadata`.
Autenticação	Uma cobrança com credencial armazenada não consegue executar um desafio 3-D Secure. Um emissor que a exija recusa com `error_code: "AUTHENTICATION_REQUIRED"` — volte para um ciphertext novo.

Checkout com cartão salvo

Um cliente recorrente pode pagar uma sessão de checkout com um cartão que salvou antes, sem digitá-lo de novo. Seu servidor cobra a sessão com o instrumento salvo:

{
  "checkout_session_id": "cks_a1b2c3d4e5",
  "payment_instrument_id": "pi_123",
  "credential_on_file": true,
  "payment_method": "credit_card",
  "charge_type": "payment",
  "country": "BR"
}

Regra	Detalhe
Opt-in	O merchant precisa estar com `saved_card_checkout_enabled` ativado. Ele vem desativado por padrão. Ativá-lo declara que você autentica o cliente antes de identificá-lo na sessão — em uma sessão, a Tokeflow nunca vê o portador do cartão, então é o seu servidor que responde por ele.
O que o opt-in cobre	Qualquer uso de um `payment_instrument_id` salvo em uma sessão de checkout sem um `card_ciphertext_id` novo: a cobrança `credential_on_file` e um trial de valor zero iniciado apenas a partir do cartão salvo. Uma cobrança com um ciphertext novo (cartão redigitado) não precisa de opt-in.
Valor e cliente	Vêm da sessão; qualquer `amount`, `currency` ou `customer_id` que você enviar não é usado.
Conector	Fixado no conector que guarda a credencial armazenada do cartão, como em qualquer cobrança `credential_on_file`. Em uma oferta recorrente, a assinatura começa nesse conector.
Opt-in desativado	`400` — colete o cartão de novo e cobre a sessão com um `card_ciphertext_id` novo. Se a mensagem disser que o recurso está desativado por uma configuração da Tokeflow, alterar `saved_card_checkout_enabled` não vai liberá-lo; entre em contato com a equipe da Tokeflow.

Para decidir se deve oferecer "pagar com este cartão salvo", leia o contexto de checkout no navegador: savedCardCheckoutEnabled e a flag reusable de cada instrumento salvo indicam quais cartões podem ser cobrados nesta sessão. São indicações; a cobrança em si continua sendo a palavra final e ainda pode ser recusada.

Endpoints

POST`/api/v1/transactions`

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant. Escopo: transactions:write.

Cria e submete uma transação de pagamento. A Tokeflow avalia suas regras de roteamento, tenta a cobrança (encadeando em cascata para um provedor de fallback em caso de falha) e cria automaticamente um pedido para a cobrança.

Campos da requisição

Field	Type	Required	Description
`payment_method`	string	Sim	Um de `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`.
`charge_type`	string	Sim	`payment` ou `setup_verification`.
`country`	string	Sim	Código de país ISO 3166-1 alpha-2. Usado para roteamento e seleção de adquirente.
`amount`	integer	Condicional	Valor em unidades menores (ex.: R$150,00 = `15000`). Use `0` para `setup_verification`. Obrigatório a menos que `checkout_session_id` seja fornecido.
`currency`	string	Condicional	Código de moeda ISO 4217. Obrigatório a menos que `checkout_session_id` seja fornecido.
`merchant_id`	string	Condicional	Merchant de destino. Obrigatório com uma chave de Organization; inferido a partir de uma chave de Merchant.
`card_ciphertext_id`	string	Condicional	A referência de cartão criptografada de uso único (`tok_…`) retornada pelo Bridge SDK quando você tokeniza um cartão novo. Obrigatório para um cartão novo e para um cartão salvo cobrado com CVV redigitado.
`payment_instrument_id`	string	Condicional	Instrumento salvo a ser cobrado (`pi_…`). Envie-o com um `card_ciphertext_id` novo ou com `credential_on_file: true` — nunca sozinho.
`credential_on_file`	boolean	Não	`true` cobra o `payment_instrument_id` com a credencial do provedor guardada no cadastro — sem dados de cartão, sem CVV. Apenas cobranças com o cliente presente e não agendadas. Exige `customer_id`, a menos que um `checkout_session_id` seja enviado; com uma sessão, precisa do opt-in `saved_card_checkout_enabled` do merchant. Não combina com `card_ciphertext_id`, `save_payment_instrument` nem `capture: false`. Padrão `false`. Veja Cobranças com credencial armazenada.
`save_payment_instrument`	boolean	Não	`true` salva o cartão por trás de `card_ciphertext_id` para o `customer_id` antes de cobrar, para que cobranças `credential_on_file` posteriores possam reutilizá-lo. O ciphertext deve ter sido emitido com `purpose=instrument_enrollment`. Não usado com `checkout_session_id`. Padrão `false`.
`checkout_session_id`	string	Condicional	Sessão de checkout concluída a ser cobrada. Quando fornecida, `amount` e `currency` são derivados da sessão e quaisquer valores enviados são ignorados.
`wallet_type`	string	Condicional	Obrigatório quando `payment_method` é `wallet`.
`customer_id`	string	Condicional	Cliente ao qual atribuir a cobrança. Obrigatório com `save_payment_instrument` e com `credential_on_file` fora de uma sessão de checkout; recomendado nos demais casos para resolução de credenciais salvas.
`payer_ip`	string	Não	O endereço IP do pagador (IPv4 ou IPv6) — de onde o cliente está comprando, nunca o do seu servidor. Alguns provedores o exigem em cobranças com cartão. Quando omitido e a cobrança pertence a uma sessão de checkout, a Tokeflow usa o IP com que o pagador abriu a sessão do Bridge SDK.
`external_order_id`	string	Não	Sua referência de pedido, armazenada para reconciliação.
`capture`	boolean	Não	`true` (padrão) = auth + captura em uma única etapa. `false` = apenas pré-autorizar; capturar depois.
`risk_score`	integer	Não	Pontuação de fraude pré-autorização de `0` a `100`. Armazenada na transação.
`installments`	object	Não	Detalhes do plano de parcelamento, onde suportado.
`payer_token_id`	string	Não	Token de pagador (`ptk_…`) de `pix.tokenize()` ou `boleto.tokenize()` do Bridge SDK. Fornece o pagador de uma cobrança PIX ou boleto, para que seu servidor nunca manipule o CPF/CNPJ nem o endereço. Uso único, vinculado ao seu método de pagamento e à sua sessão de checkout. Veja Pagadores de PIX e boleto.
`boleto`	object	Não	Opções de boleto, lidas apenas quando `payment_method` é `boleto`. `expires_in_days`: dias até o vencimento do boleto, de `1` a `30`, padrão `3`. Um vencimento que cai em fim de semana passa para o próximo dia útil.
`idempotency_key`	string	Não	Evita cobranças duplicadas. Também pode ser enviado como o cabeçalho `Idempotency-Key`.
`metadata`	object	Não	Pares chave-valor arbitrários armazenados na transação.

Sempre envie uma chave de idempotência na criação. Passe um valor único por tentativa de cobrança como o cabeçalho Idempotency-Key (ou idempotency_key no corpo). Se um soluço de rede fizer você repetir a tentativa, reenviar a mesma chave retorna a transação original (HTTP 200) em vez de cobrar o cliente duas vezes. Veja Idempotência e limites de taxa.

Códigos de resposta

Code	When
`201 Created`	Primeira submissão desta transação. Inspecione `status` para o resultado.
`200 OK`	Replay idempotente — a mesma `Idempotency-Key` foi vista antes; a transação original é retornada.
`400 Bad Request`	Parâmetros inválidos ou campos obrigatórios ausentes.
`401 Unauthorized`	Chave de API ausente ou inválida.
`403 Forbidden`	Autenticado, mas sem o escopo necessário.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345_attempt_1" \
  -d '{
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR",
    "amount": 15000,
    "currency": "BRL",
    "customer_id": "cust_123",
    "external_order_id": "order_888",
    "card_ciphertext_id": "tok_8f3c2a1b9d4e",
    "capture": true,
    "metadata": { "campaign": "black_friday" }
  }'

Exemplo de resposta — 201 Created

{
  "success": true,
  "data": {
    "id": "tx_777",
    "organization_id": "org_123",
    "merchant_id": "mrc_123",
    "order_id": "ord_001",
    "subscription_id": null,
    "external_order_id": "order_888",
    "customer_id": "cust_123",
    "payment_instrument_id": null,
    "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": "acquirer_a",
        "status": "failed",
        "started_at": "2026-01-15T12:30:00.000Z",
        "finished_at": "2026-01-15T12:30:02.000Z",
        "error_category": "SOFT_DECLINE",
        "error_code": "INSUFFICIENT_FUNDS",
        "decline_reason": "insufficient_funds"
      },
      {
        "attempt_number": 2,
        "is_fallback": true,
        "connector_id": "conn_d4e5f6",
        "provider_slug": "acquirer_b",
        "status": "success",
        "started_at": "2026-01-15T12:30:02.000Z",
        "finished_at": "2026-01-15T12:30:04.000Z",
        "error_category": null,
        "error_code": null,
        "decline_reason": null
      }
    ],
    "payment_instructions": null,
    "metadata": { "campaign": "black_friday" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:04.000Z"
  },
  "request_id": "req_8f3c",
  "timestamp": "2026-01-15T12:30:04.000Z"
}

O exemplo acima mostra uma cascata: o conector primário recusou, e o fallback da Tokeflow autorizou a cobrança — tudo em uma única chamada de API.

Uma recusa de provedor retorna 201 com status: "failed" e uma linha do tempo explicativa, não um erro HTTP. Ramifique com base em status. Veja A linha do tempo para os campos que explicam uma falha.

Métodos assíncronos (PIX e boleto)

Para PIX e boleto, a resposta carrega payment_instructions em vez de uma autorização imediata. A transação permanece pending até o cliente pagar; o status final chega via webhook. Devolva payment_instructions ao navegador para que o cliente possa pagar.

Campo	Método	Descrição
`type`	ambos	`pix` ou `boleto`.
`qr_code_text`	PIX	O código "copia e cola".
`qr_code_url`	PIX	Imagem do QR code hospedada pelo provedor.
`digitable_line`	Boleto	A linha digitável — os 47 dígitos que o pagador digita no app do banco.
`barcode`	Boleto	O conteúdo do código de barras de 44 dígitos.
`boleto_url`	Boleto	Boleto hospedado pelo provedor (PDF ou página de instruções).
`due_date`	Boleto	Data de vencimento no horário de Brasília, `YYYY-MM-DD`, após eventual adiamento de fim de semana.
`expires_at`	ambos	Quando o pagamento deixa de poder ser feito (ISO 8601).

{
  "success": true,
  "data": {
    "id": "tx_778",
    "status": "pending",
    "payment_method": "pix",
    "amount_authorized": 0,
    "amount_captured": 0,
    "currency": "BRL",
    "payment_instructions": {
      "type": "pix",
      "qr_code_text": "00020126580014BR.GOV.BCB.PIX…",
      "qr_code_url": "https://example.com/qrcode/image.png",
      "expires_at": "2026-01-15T13:00:00.000Z"
    },
    "timeline": [
      {
        "attempt_number": 1,
        "is_fallback": false,
        "connector_id": "conn_a1b2c3",
        "provider_slug": "acquirer_a",
        "status": "pending",
        "started_at": "2026-01-15T12:30:00.000Z",
        "finished_at": null,
        "error_category": null,
        "error_code": null,
        "decline_reason": null
      }
    ],
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_9a2d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Uma cobrança de boleto devolve o boleto em vez disso:

"payment_instructions": {
  "type": "boleto",
  "digitable_line": "23793381286000782713695000063305975520000370000",
  "barcode": "23799755200003700003381260007827139500006330",
  "boleto_url": "https://example.com/boleto/tx_779.pdf",
  "due_date": "2026-10-29",
  "expires_at": "2026-10-30T02:59:59.000Z"
}

Pagadores de PIX e boleto

PIX e boleto precisam dos dados do pagador — nome, e-mail e CPF/CNPJ, além de um endereço de cobrança completo para boleto. A forma recomendada de coletá-los é um token de pagador: o Bridge SDK registra o pagador a partir do navegador e devolve um ptk_…, e seu servidor o cobra com payer_token_id:

{
  "payment_method": "boleto",
  "charge_type": "payment",
  "country": "BR",
  "amount": 10000,
  "currency": "BRL",
  "external_order_id": "order_123",
  "payer_token_id": "ptk_abc123",
  "boleto": { "expires_in_days": 3 }
}

Regra	Detalhe
Uso único	Um token é consumido pela cobrança que o usa — mesmo uma que falhe — e expira 30 minutos após a criação. Envie uma `Idempotency-Key` para que uma requisição repetida reproduza a cobrança em vez de exigir um novo token.
Vinculado	O token só é válido para o `payment_method` para o qual foi coletado e, quando coletado dentro de uma sessão de checkout, apenas com aquele `checkout_session_id`.
Recusado	Um token desconhecido, já usado, expirado, coletado para o outro método ou para outra sessão é recusado com `400` e `code` `INVALID_PAYER_TOKEN`. Nada é cobrado.
Cliente	O e-mail do token sozinho nunca vincula a cobrança a um cliente existente, já que qualquer pessoa pode digitar qualquer e-mail em um navegador. Para atribuir a cobrança, envie `customer_id`, ou envie o mesmo e-mail a partir do seu servidor.
Precedência	Os dados do pagador do token prevalecem sobre os dados do pagador enviados pelo seu servidor.

Sem um token de pagador, o pagador vem do cliente que você indica com customer_id e dos dados armazenados dele. Um boleto cujo pagador não tem um campo obrigatório é recusado antes de chegar a um provedor.

GET`/api/v1/transactions`

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant. Escopo: transactions:read.

Retorna uma lista paginada de transações, das mais novas para as mais antigas.

Parâmetros de consulta

Field	Type	Required	Description
`status`	string	Não	Filtra por status. Repetível ou separado por vírgulas para vários (ex.: `status=refunded,partially_refunded`).
`merchant_id`	string	Condicional	Obrigatório com uma chave de Organization; inferido a partir de uma chave de Merchant.
`customer_reference`	string	Não	Filtra por referência de cliente.
`order_id`	string	Não	Filtra por pedido.
`payment_method`	string	Não	Filtra por método de pagamento.
`currency`	string	Não	Filtra por código de moeda ISO 4217.
`date_from`	string	Não	Criado nesta data/hora ou depois dela (ISO 8601).
`date_to`	string	Não	Criado nesta data/hora ou antes dela (ISO 8601).
`page`	integer	Não	Número da página (padrão `1`, mín. `1`).
`limit`	integer	Não	Itens por página (padrão `20`, máx. `100`).

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "status=authorized,refunded" \
  --data-urlencode "currency=BRL" \
  --data-urlencode "date_from=2026-01-01T00:00:00Z" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Exemplo de resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "id": "tx_777",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "order_id": "ord_001",
      "external_order_id": "order_888",
      "customer_id": "cust_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": "acquirer_a",
          "status": "success",
          "started_at": "2026-01-15T12:30:00.000Z",
          "finished_at": "2026-01-15T12:30:02.000Z",
          "error_category": null,
          "error_code": null,
          "decline_reason": null
        }
      ],
      "payment_instructions": null,
      "metadata": {},
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:02.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_3b7e",
  "timestamp": "2026-01-15T12:30:05.000Z"
}

GET`/api/v1/transactions/:id`

OrgMerchant

Auth: Chave de Organization (qualquer transação na organização) ou chave de Merchant (suas próprias transações). Escopo: transactions:read.

Recupera uma única transação, incluindo sua linha do tempo de roteamento completa. Retorna o objeto de transação.

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/transactions/tx_777 \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200 OK

{
  "success": true,
  "data": {
    "id": "tx_777",
    "merchant_id": "mrc_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": "acquirer_a",
        "status": "success",
        "started_at": "2026-01-15T12:30:00.000Z",
        "finished_at": "2026-01-15T12:30:02.000Z",
        "error_category": null,
        "error_code": null,
        "decline_reason": null
      }
    ],
    "payment_instructions": null,
    "metadata": {},
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:02.000Z"
  },
  "request_id": "req_5c1a",
  "timestamp": "2026-01-15T12:30:06.000Z"
}

Um 404 (not_found_error) é retornado se a transação não existir ou não pertencer ao merchant autenticado.

GET`/api/v1/transactions/:id/attempts`

OrgMerchant

Auth: Chave de Organization (qualquer transação na organização) ou chave de Merchant (suas próprias transações). Escopo: transactions:read.

Retorna cada tentativa individual de provedor para uma transação, com mais detalhes do que a timeline embutida — incluindo status de 3DS, mensagens de erro normalizadas e taxas de gateway. Use-a para depurar recusas e analisar o comportamento de roteamento.

Campos da tentativa

Field	Type	Description
`id`	string	ID da tentativa.
`payment_transaction_id`	string	Transação pai, prefixada com `tx_`.
`merchant_connector_id`	string	Conector usado para esta tentativa.
`provider_slug`	string	Slug neutro do provedor.
`attempt_number`	integer	Número sequencial, começando em 1.
`is_fallback`	boolean	Se a tentativa foi executada como fallback.
`status`	string	`pending`, `success`, `failed` ou `error`.
`three_ds_status`	string \| null	Resultado da autenticação 3DS, quando aplicável.
`error_category`	string \| null	Classe de erro de alto nível, em caso de falha.
`error_code`	string \| null	Código de erro normalizado, em caso de falha.
`decline_reason`	string \| null	O motivo da falha segundo a Tokeflow, o mesmo valor qualquer que seja o provedor que respondeu. Veja Motivos de recusa.
`error_message`	string \| null	Erro legível por humanos, em caso de falha.
`psp_transaction_id`	string \| null	Referência de transação do lado do provedor.
`gateway_fee`	integer \| null	Taxa de processamento conforme informada pelo provedor, em unidades menores. Nula quando o provedor não informou nenhuma; alguns provedores só a informam depois, e ela é preenchida quando chega.
`started_at`	string	Quando a tentativa começou (ISO 8601 UTC).
`finished_at`	string \| null	Quando a tentativa foi resolvida (ISO 8601 UTC).

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/transactions/tx_777/attempts \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "id": "att_1",
      "payment_transaction_id": "tx_777",
      "merchant_connector_id": "conn_a1b2c3",
      "provider_slug": "acquirer_a",
      "attempt_number": 1,
      "is_fallback": false,
      "status": "failed",
      "three_ds_status": null,
      "error_category": "SOFT_DECLINE",
      "error_code": "INSUFFICIENT_FUNDS",
      "decline_reason": "insufficient_funds",
      "error_message": "Issuer declined: insufficient funds",
      "psp_transaction_id": "psp_tx_123",
      "gateway_fee": null,
      "started_at": "2026-01-15T12:30:00.000Z",
      "finished_at": "2026-01-15T12:30:02.000Z"
    },
    {
      "id": "att_2",
      "payment_transaction_id": "tx_777",
      "merchant_connector_id": "conn_d4e5f6",
      "provider_slug": "acquirer_b",
      "attempt_number": 2,
      "is_fallback": true,
      "status": "success",
      "three_ds_status": "authenticated",
      "error_category": null,
      "error_code": null,
      "decline_reason": null,
      "error_message": null,
      "psp_transaction_id": "psp_tx_456",
      "gateway_fee": 45,
      "started_at": "2026-01-15T12:30:02.000Z",
      "finished_at": "2026-01-15T12:30:04.000Z"
    }
  ],
  "request_id": "req_7d2f",
  "timestamp": "2026-01-15T12:30:07.000Z"
}

POST`/api/v1/transactions/:id/capture`

OrgMerchant

Auth: Chave de Organization (qualquer transação na organização) ou chave de Merchant (suas próprias transações). Escopo: transactions:write.

Captura uma transação que foi pré-autorizada com capture: false. A transação deve estar no status capture_pending; após uma captura bem-sucedida, ela se torna authorized.

Campos da requisição

Field	Type	Required	Description
`amount`	integer	Não	Valor a capturar, em unidades menores. Omita para capturar o valor total autorizado. Para uma captura parcial, deve ser ≤ `amount_authorized`.

A maioria dos provedores permite apenas uma captura por autorização. Em uma captura parcial, o restante não capturado é liberado automaticamente.

Captura e cancelamento na mesma autorização nunca vencem os dois. Se um cancelamento (seu, ou um informado pelo provedor) liquidar a transação enquanto uma captura está em andamento, ou se uma captura com valor diferente chegar primeiro, a chamada perdedora responde 409 (conflict_error) — o provedor pode já ter agido, então leia a transação de volta com GET /transactions/:id em vez de tentar de novo. Uma captura que encontra a mesma captura já registrada devolve essa transação com 200.

Exemplo de requisição — captura total

curl -X POST https://api.tokeflow.com/api/v1/transactions/tx_777/capture \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Exemplo de requisição — captura parcial

curl -X POST https://api.tokeflow.com/api/v1/transactions/tx_777/capture \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000 }'

Exemplo de resposta — 200 OK

{
  "success": true,
  "data": {
    "id": "tx_777",
    "merchant_id": "mrc_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": "acquirer_a",
        "status": "success",
        "started_at": "2026-01-15T12:30:00.000Z",
        "finished_at": "2026-01-15T12:30:02.000Z",
        "error_category": null,
        "error_code": null,
        "decline_reason": null
      }
    ],
    "payment_instructions": null,
    "metadata": {},
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:35:00.000Z"
  },
  "request_id": "req_a4e9",
  "timestamp": "2026-01-15T12:35:00.000Z"
}

Um 400 (validation_error) é retornado se a transação não estiver no status capture_pending ou se o valor exceder o valor autorizado.

POST`/api/v1/transactions/:id/void`

OrgMerchant

Auth: Chave de Organization (qualquer transação na organização) ou chave de Merchant (suas próprias transações). Escopo: transactions:write.

Cancela uma autorização antes de ela ser capturada, liberando os fundos retidos. A transação deve estar no status capture_pending ou authorized; após o cancelamento, ela se torna voided.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/transactions/tx_777/void \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200 OK

{
  "success": true,
  "data": {
    "id": "tx_777",
    "status": "voided",
    "updated_at": "2026-01-15T12:36:00.000Z"
  },
  "request_id": "req_b8c0",
  "timestamp": "2026-01-15T12:36:00.000Z"
}

Um 400 (validation_error) é retornado se a transação não estiver em um status cancelável. Um cancelamento que perde para uma captura já registrada responde 409 (conflict_error); um cancelamento que encontra a retenção já liberada pelo provedor é bem-sucedido.

Para reverter fundos após a captura, emita um reembolso em vez de um cancelamento. Veja Reembolsos.

Erros

Todo erro usa o envelope padrão. Os casos mais comuns para este recurso:

HTTP	`type`	Causa típica
`400`	`validation_error`	Campo obrigatório ausente, uma combinação inválida dos campos de origem do cartão (`payment_instrument_id` sozinho, `credential_on_file` com um ciphertext, um ciphertext `one_time` com `save_payment_instrument`, um instrumento ainda sem credencial armazenada), um `payer_token_id` inutilizável (`INVALID_PAYER_TOKEN`), ou captura/cancelamento no estado errado.
`401`	`authentication_error`	Chave de API ausente ou inválida.
`403`	`authorization_error`	A chave não tem o escopo necessário.
`404`	`not_found_error`	Transação não encontrada ou não pertencente ao merchant.
`409`	`conflict_error`	Uma captura e um cancelamento concorreram na mesma autorização e esta chamada perdeu. Leia a transação de volta; não tente de novo às cegas.
`422`	`business_rule_error`	Nenhum conector elegível para a cobrança — por exemplo, a moeda, a bandeira ou o plano de parcelas não é suportado pelo conector selecionado pelo roteamento ou fixado.
`429`	`rate_limit_error`	Limite de taxa excedido — recue exponencialmente.

Veja Erros para o envelope completo e o catálogo de tipos.

Relacionados

Upsells e downsells em um clique — o guia completo de save_payment_instrument e credential_on_file.
Idempotência e limites de taxa — retentativas seguras e controle de fluxo.
Reembolsos — reverta fundos capturados.
Autenticação — provisione chaves e escopos.
Como a Tokeflow funciona — roteamento, cascata e fallback.

Transações

POST/api/v1/transactions

GET/api/v1/transactions

GET/api/v1/transactions/:id

GET/api/v1/transactions/:id/attempts

POST/api/v1/transactions/:id/capture

POST/api/v1/transactions/:id/void

Nesta página

POST`/api/v1/transactions`

GET`/api/v1/transactions`

GET`/api/v1/transactions/:id`

GET`/api/v1/transactions/:id/attempts`

POST`/api/v1/transactions/:id/capture`

POST`/api/v1/transactions/:id/void`