Conceitos fundamentais

O Tokeflow é a infraestrutura por trás da sua plataforma. Você modela seu negócio uma única vez — suas contas, catálogo, clientes e pagamentos — e o Tokeflow padroniza esses objetos em cada provedor de pagamento conectado. Esta página é o glossário canônico e o modelo de objetos: cada entidade, o que ela representa, seu prefixo de ID e como as peças se encaixam.

O modelo de objetos em resumo

Tudo no Tokeflow se apoia em um modelo de tenancy de dois níveis: uma Organization (sua plataforma) que contém um ou mais Merchants (as marcas ou unidades de negócio que efetivamente vendem). Quase todos os demais recursos têm escopo de um único merchant.

Tenancy

Organization

Sua plataforma — o tenant de nível mais alto e a fronteira de faturamento/governança. Uma organization é dona de um ou mais merchants e carrega a identidade de compliance de toda a org (razão social, registro, país). Chaves de API com escopo de organization (sk_live_org_… / pk_live_org_…) podem atuar em todos os merchants da org.

Prefixo de ID: org_

Merchant

Uma única marca ou unidade de negócio que vende sob a sua plataforma. Um merchant é o escopo de quase todos os recursos operacionais — clientes, catálogo, checkout, transações, pedidos e assinaturas pertencem todos a exatamente um merchant. Chaves com escopo de merchant (sk_live_mer_… / pk_live_mer_…) inferem o merchant automaticamente.

Prefixo de ID: mrc_

Clientes e dados de pagamento

Customer

Um comprador sob um merchant específico. Guarda identidade (nome, e-mail, telefone), um documento fiscal opcional e um endereço de cobrança. Os clientes são deduplicados por e-mail dentro de um merchant, e a mesma pessoa pode existir de forma independente sob diferentes merchants.

Prefixo de ID: cust_

Payment Instrument

Um método de pagamento reutilizável e tokenizado, de propriedade de um cliente — normalmente um cartão armazenado para cobranças futuras (checkout de retorno, assinaturas, one-click). O Tokeflow armazena apenas metadados seguros, como bandeira, últimos quatro dígitos e validade; dados brutos de cartão nunca são persistidos nos sistemas do Tokeflow.

Prefixo de ID: pi_

Card Token

Uma referência de uso único e curta duração para dados de cartão coletados no navegador pelos secure fields do Tokeflow. Os secure fields são executados dentro de iframes isolados e cross-origin; os dados do cartão são criptografados no navegador e nunca tocam seus servidores. Seu cliente recebe um card token e o entrega ao seu backend, que o troca (server-side, com uma chave secreta) por um Payment Instrument durável.

Prefixo de ID: tok_

Catálogo

Seu catálogo vendável é uma hierarquia de quatro níveis: uma Product Family agrupa Products relacionados; cada produto é vendido como um ou mais Offers; cada offer é precificada via Offer Prices (uma por moeda). As Offer Transitions definem como um assinante pode se mover entre offers (upgrade/downgrade) dentro de uma família.

Product Family

Um agrupamento de produtos relacionados entre os quais um assinante pode se mover (por exemplo, os níveis de um plano). A família define o comportamento padrão — change_charge_behavior — para transições entre seus offers. Um produto pertence a uma família quando participa de fluxos de upgrade/downgrade.

Prefixo de ID: pfa_

Product

Algo que você vende. Um produto é one_time ou recurring (type), e é active ou archived (status). Quando faz parte de uma família, ele carrega uma posição de tier para que os planos possam ser ordenados na lógica de upgrade/downgrade.

Prefixo de ID: prd_

Offer

Uma configuração comprável de um produto — a coisa que o cliente efetivamente compra. Um offer fixa o ciclo de cobrança, o comportamento de trial e de setup, e quantos ciclos cobrar. Um produto pode expor vários offers (por exemplo, um offer mensal e um anual).

Prefixo de ID: ofr_

Offer Price

O valor de um offer em uma única moeda. Um offer tem um preço por moeda, com um marcado como padrão. Os valores são unidades menores inteiras e sempre acompanhados de uma moeda ISO 4217.

Prefixo de ID: opr_

Offer Transition

Uma regra direcional que conecta dois offers na mesma família — o caminho que um assinante percorre ao fazer upgrade ou downgrade. Uma transição pode sobrescrever o change_charge_behavior padrão da família (next_renew, prorated ou override) para aquele par específico, e pode ser ativada ou desativada.

Prefixo de ID: oft_

Checkout

Um fluxo de compra hospedado e com estado. Uma Checkout Session acompanha um comprador desde a chegada até a conclusão, mantém os offers escolhidos como Checkout Items e registra uma linha do tempo de Checkout Events (incluindo atribuição UTM) para análise de funil. Uma sessão concluída produz um Order.

Checkout Session

O contêiner de uma tentativa de checkout. Acompanha o offer principal, o cliente (eventualmente identificado), a moeda selecionada e um status de ciclo de vida: initiated, customer_identified, payment_pending, completed, expired, abandoned.

Prefixo de ID: cks_

Checkout Item

Uma linha dentro de uma sessão: um offer, sua moeda e valor congelado (snapshot), quantidade e parcelas selecionadas. Os valores são congelados a partir do offer price no momento da sessão, para que edições posteriores no catálogo não alterem um checkout em andamento.

Prefixo de ID: cki_

Checkout Event

Um evento append-only na linha do tempo de uma sessão. Tipos de evento: initiated, customer_identified, currency_changed, payment_started, payment_failed, payment_succeeded, completed, expired, abandoned. Carrega atribuição opcional (utm_source, utm_medium, utm_campaign) e contexto da requisição.

Prefixo de ID: cke_

Pagamentos

Transaction

Uma única tentativa de pagamento contra um provedor — o registro normalizado de uma autorização/captura, independentemente de qual provedor conectado a processou. Carrega o método de pagamento, os valores (autorizado e capturado, em unidades menores), a moeda, o país e um status detalhado. As transações são idempotentes na criação e podem estar vinculadas a um Order.

Prefixo de ID: tx_

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

Order

O registro normalizado e voltado ao merchant de uma única venda. Um pedido vincula-se a no máximo uma Transaction que o liquida, referencia o cliente e pode estar atrelado a uma Subscription quando é uma renovação ou configuração de trial. Use o pedido como sua referência de negócio estável; a transação é a mecânica de pagamento por trás dele.

Prefixo de ID: ord_

status: pending, pre_authorized, authorized, failed, canceled, refunded, partially_refunded, charged_back, refund_pending.

Refund

Um estorno total ou parcial de uma transação capturada. Uma transação pode ter múltiplos refunds (ex.: reembolsos parciais sucessivos). Cada refund registra um valor em unidades menores, uma moeda, um status e um motivo.

Prefixo de ID: ref_

Subscription

Um acordo de cobrança recorrente: um cliente cobrado sobre um Offer usando um Payment Instrument armazenado. O Tokeflow acompanha o offer e o valor atuais, o período de cobrança, as janelas de trial, o estado de dunning para renovações falhas e um status de ciclo de vida. Cada cobrança de renovação produz um Order (e sua transação).

Prefixo de ID: sub_

Convenções de valores e formatação

A consistência entre provedores e moedas é garantida por algumas regras. Aplique-as em todos os lugares.

Envelope de resposta padrão

Toda resposta da API encapsula o recurso em um envelope consistente. Um recurso único omite meta; uma lista inclui meta.pagination.

{
  "success": true,
  "data": {
    "id": "tx_8f3c2a1b",
    "status": "authorized",
    "payment_method": "credit_card",
    "amount_authorized": 15000,
    "amount_captured": 15000,
    "currency": "BRL",
    "country": "BR"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Uma resposta de lista define data como um array e inclui paginação:

{
  "success": true,
  "data": [
    { "id": "ord_a1b2c3", "status": "authorized", "total_amount": 9900, "currency": "USD" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Referência de formato de ID

Todo objeto do Tokeflow carrega um identificador opaco e prefixado. Os prefixos são estáveis — faça a correspondência por eles em vez de analisar o sufixo aleatório.

Próximos passos

• Autenticação — tipos de chave, escopos e a regra do merchant_id para chaves de org.
• Idempotência — retentativas seguras em chamadas de create e de cobrança.
• SDK — colete cartões com secure fields e troque card tokens por payment instruments.
• Webhooks — entrega normalizada de eventos e verificação de assinatura.