Sessões de Checkout

Crie e gerencie sessões de checkout da Tokeflow — capture um snapshot de ofertas e preços, identifique o cliente, acompanhe o comportamento do comprador e faça o repasse para uma transação de cobrança.

Uma sessão de checkout é o estado no lado do servidor de uma única compra em andamento. Ela captura um snapshot das ofertas e dos preços que um comprador está prestes a pagar, registra quem ele é, anota o que ele faz e se torna a única fonte da verdade para o valor e a moeda que serão eventualmente cobrados.

As sessões desacoplam a montagem do carrinho da cobrança. Você monta os itens de linha e identifica o cliente ao longo da vida da sessão e, então, cria uma única transação que referencia a sessão pelo ID. O valor e a moeda são derivados da sessão, de modo que a cobrança sempre corresponde ao que o comprador viu.

Como uma sessão captura um snapshot dos preços da oferta no momento da criação, edições posteriores no catálogo nunca alteram o preço de um checkout já em andamento — o comprador paga exatamente o que foi cotado.

A Tokeflow orquestra pagamentos; ela não processa nem liquida fundos. Uma sessão de checkout modela a intenção de compra e os itens; autorização, captura e liquidação acontecem no provedor de pagamento conectado assim que você cria a transação que cobra a sessão.

Como uma sessão flui

O objeto de sessão de checkout

FieldTypeDescription
idstringIdentificador da sessão, prefixado com cks_.
merchant_idstringMerchant proprietário, prefixado com mrc_.
offer_idstringOferta primária que iniciou o checkout, prefixada com ofr_.
customer_idstring | nullDefinido assim que o cliente é identificado, prefixado com cust_.
customer_emailstring | nullE-mail do cliente, preenchido na identificação.
customer_namestring | nullNome do cliente, quando conhecido.
selected_currencystring | nullMoeda ISO 4217 da sessão. Assume por padrão a moeda padrão da oferta.
statusenumEstado do ciclo de vida da sessão. Veja Status.
external_session_idstring | nullSua própria referência de sessão ou conta. Única por Merchant quando definida.
expires_atstring | nullHorário ISO 8601 após o qual a sessão é tratada como expirada.
completed_atstring | nullDefinido quando a sessão transita para completed.
created_atstringTimestamp de criação ISO 8601.
updated_atstringTimestamp da última atualização ISO 8601.
itemsarrayItens de linha. Incluído por padrão em get-by-id; veja Itens de linha.
eventsarrayEventos de rastreamento. Incluído quando solicitado; veja Eventos.

Status

StatusMeaning
initiatedSessão criada; nenhum cliente identificado ainda.
customer_identifiedUm cliente foi vinculado à sessão.
payment_pendingUma cobrança foi iniciada contra a sessão.
completedA sessão foi paga; completed_at está definido.
expiredA sessão ultrapassou expires_at sem ser concluída.
abandonedA sessão foi explicitamente marcada como abandonada.

Endpoints

Todos os endpoints estão sob https://api.tokeflow.com/api/v1.

Os endpoints de checkout têm escopo por Merchant. Com uma chave de Organization, identifique o Merchant de destino com o parâmetro de query merchant_id (em list/get) ou com o campo do corpo (em create); com uma chave de Merchant, o Merchant é inferido. As leituras exigem o escopo checkout:read; as escritas exigem checkout:write.


POST/api/v1/checkout-sessions

Cria uma sessão de checkout.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Forneça um offer_id primário. Identifique o comprador com um customer_id existente ou com um objeto customer inline (forneça exatamente um) — o customer inline é resolvido de forma idempotente por e-mail, de modo que um cliente existente com o mesmo e-mail é reutilizado. Omita items para deixar a Tokeflow capturar o snapshot de um único item padrão a partir de offer_id, ou passe um array items explícito.

FieldTypeRequiredDescription
offer_idstringSimOferta primária que iniciou o checkout.
customer_idstringCondicionalId de cliente existente. Forneça este ou customer.
customerobjectCondicionalCustomer inline a ser criado/reutilizado. Forneça este ou customer_id.
selected_currencystringNãoCódigo ISO 4217. Omita para usar a moeda padrão da oferta.
external_session_idstringNãoSua referência de sessão/conta. Única por Merchant.
expires_atstringNãoTimestamp ISO 8601; deve estar no futuro.
itemsarrayNãoItens de linha (veja abaixo). Omita para um único item padrão.

Cada entrada em items:

FieldTypeRequiredDescription
offer_idstringSimOferta a ser incluída como item de linha.
quantityintegerNãoUnidades desta oferta. Mín 1, padrão 1.
installmentsintegerNãoParcelas selecionadas pelo comprador. Mín 1, padrão 1 (cobrança única).

O objeto customer inline aceita email, name, phone (E.164), document_type (cpf, cnpj, passport, tax_id), document_number, billing_address e metadata opcional. Veja Customers para o formato completo.

Envie um cabeçalho Idempotency-Key na criação para que uma requisição repetida retorne a sessão original em vez de criar uma duplicata. Veja Idempotência e limites de taxa.

curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c9a-2b8e-4c3a-9f0d-7a1e2b3c4d5e" \
  -d '{
    "offer_id": "ofr_a1b2c3d4e5",
    "customer": {
      "email": "joao@example.com",
      "name": "Joao da Silva",
      "phone": "+5511999990000",
      "document_type": "cpf",
      "document_number": "123.456.789-00",
      "billing_address": {
        "line_1": "Av Paulista, 1000",
        "line_2": "Apto 42",
        "zip_code": "01310-100",
        "city": "Sao Paulo",
        "state": "SP",
        "country": "BR"
      }
    },
    "selected_currency": "BRL",
    "external_session_id": "sess_external_42",
    "expires_at": "2026-05-20T18:00:00Z",
    "items": [
      { "offer_id": "ofr_a1b2c3d4e5", "quantity": 1, "installments": 1 }
    ]
  }'

Resposta 201 Created (uma requisição idempotente reproduzida retorna 200 OK):

{
  "success": true,
  "data": {
    "id": "cks_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "offer_id": "ofr_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "customer_email": "joao@example.com",
    "customer_name": "Joao da Silva",
    "selected_currency": "BRL",
    "status": "customer_identified",
    "external_session_id": "sess_external_42",
    "expires_at": "2026-05-20T18:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z",
    "items": [
      {
        "id": "cki_a1b2c3d4e5",
        "checkout_session_id": "cks_a1b2c3d4e5",
        "offer_id": "ofr_a1b2c3d4e5",
        "currency": "BRL",
        "amount": 15000,
        "first_charge_amount": null,
        "quantity": 1,
        "installments": 1,
        "created_at": "2026-05-19T12:00:00.000Z"
      }
    ]
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

GET/api/v1/checkout-sessions

Lista as sessões de checkout, da mais recente para a mais antiga.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Query paramTypeDescription
pageintegerNúmero da página, começando em 1. Padrão 1.
limitintegerItens por página. Padrão 20, máx 100.
statusenumFiltra por status da sessão.
offer_idstringSessões vinculadas a uma oferta primária específica.
customer_idstringSessões de um cliente específico.
customer_emailstringSessões que correspondem a um e-mail de cliente.
external_session_idstringBusca pela sua referência externa de sessão.
merchant_idstringObrigatório com uma chave de Organization para direcionar a um Merchant.
curl -G https://api.tokeflow.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "status=initiated" \
  --data-urlencode "offer_id=ofr_a1b2c3d4e5" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Resposta 200 OK:

{
  "success": true,
  "data": [
    {
      "id": "cks_a1b2c3d4e5",
      "merchant_id": "mrc_a1b2c3d4e5",
      "offer_id": "ofr_a1b2c3d4e5",
      "customer_id": null,
      "customer_email": null,
      "customer_name": null,
      "selected_currency": "BRL",
      "status": "initiated",
      "external_session_id": "sess_external_42",
      "expires_at": "2026-05-20T18:00:00.000Z",
      "completed_at": null,
      "created_at": "2026-05-19T12:00:00.000Z",
      "updated_at": "2026-05-19T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_3a9d7c2e",
  "timestamp": "2026-05-19T12:05:00.000Z"
}

GET/api/v1/checkout-sessions/:id

Recupera uma única sessão de checkout.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

Query paramTypeDescription
include_itemsbooleanInclui o array items. Assume true por padrão; passe false para omitir.
include_eventsbooleanInclui o array events. Assume false por padrão; passe true para incluir.
curl -G https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "include_items=true" \
  --data-urlencode "include_events=true"

Resposta 200 OK:

{
  "success": true,
  "data": {
    "id": "cks_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "offer_id": "ofr_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "customer_email": "jane@acme.com",
    "customer_name": "Jane Doe",
    "selected_currency": "BRL",
    "status": "customer_identified",
    "external_session_id": "sess_external_42",
    "expires_at": "2026-05-20T18:00:00.000Z",
    "completed_at": null,
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:03:00.000Z",
    "items": [
      {
        "id": "cki_a1b2c3d4e5",
        "checkout_session_id": "cks_a1b2c3d4e5",
        "offer_id": "ofr_a1b2c3d4e5",
        "currency": "BRL",
        "amount": 15000,
        "first_charge_amount": null,
        "quantity": 1,
        "installments": 1,
        "created_at": "2026-05-19T12:00:00.000Z"
      }
    ],
    "events": [
      {
        "id": "cke_a1b2c3d4e5",
        "checkout_session_id": "cks_a1b2c3d4e5",
        "event_type": "customer_identified",
        "source_url": "https://acme.com/checkout",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "spring_sale",
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
        "metadata": null,
        "created_at": "2026-05-19T12:03:00.000Z"
      }
    ]
  },
  "request_id": "req_5c1e8b4f",
  "timestamp": "2026-05-19T12:10:00.000Z"
}

PATCH/api/v1/checkout-sessions/:id

Atualiza campos mutáveis da sessão. O offer_id primário e os items são imutáveis aqui — gerencie os itens de linha com os endpoints de item.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

FieldTypeRequiredDescription
customer_idstringNãoVincula um cliente existente.
customerobjectNãoCustomer inline a ser criado/reutilizado.
selected_currencystringNãoAltera a moeda da sessão (ISO 4217).
external_session_idstringNãoAtualiza sua referência externa.
expires_atstringNãoProrroga a expiração (deve estar no futuro).
curl -X PATCH https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "selected_currency": "USD", "expires_at": "2026-05-21T18:00:00Z" }'

Resposta 200 OK — retorna o objeto de sessão atualizado (mesmo formato de get-by-id).


POST/api/v1/checkout-sessions/:id/identify

Vincula um cliente à sessão. Forneça customer_id ou customer_email (obrigatório quando nenhum id é fornecido). Quando apenas um e-mail é informado, a Tokeflow procura ou cria o cliente correspondente para o Merchant. Em caso de sucesso, a sessão passa para customer_identified.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

FieldTypeRequiredDescription
customer_idstringCondicionalId de cliente existente. Forneça este ou customer_email.
customer_emailstringCondicionalE-mail do cliente; resolve ou cria o cliente.
customer_namestringNãoNome de exibição opcional.
curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5/identify \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "customer_email": "jane@acme.com", "customer_name": "Jane Doe" }'

Resposta 200 OK — retorna a sessão com customer_id, customer_email e status: customer_identified.


POST/api/v1/checkout-sessions/:id/abandon

Marca uma sessão como abandonada, por exemplo quando o comprador sai da página. A sessão passa para abandoned. Não recebe corpo.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5/abandon \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 200 OK — retorna a sessão com status: abandoned.


Itens de linha

Cada item de linha captura um snapshot do preço de uma oferta no momento em que é adicionado, em unidades menores inteiras. Editar seu catálogo depois disso nunca altera os totais de uma sessão existente.

FieldTypeDescription
idstringIdentificador do item, prefixado com cki_.
checkout_session_idstringSessão pai, prefixada com cks_.
offer_idstringOferta que este item de linha referencia.
currencystringMoeda ISO 4217 do snapshot.
amountintegerSnapshot do preço recorrente/padrão, em unidades menores.
first_charge_amountinteger | nullQuanto a primeira cobrança leva, em unidades menores, quando isso difere de amount. null significa que a primeira cobrança usa o preço do ciclo. Definido por uma cobrança de setup e por um período de teste gratuito — que resolve para 0, porque um período de teste não cobra nada no início.
quantityintegerUnidades desta oferta.
installmentsintegerParcelas selecionadas pelo comprador (1 = cobrança única).
created_atstringTimestamp de criação ISO 8601.

POST/api/v1/checkout-sessions/:id/items

Adiciona um item de linha.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

FieldTypeRequiredDescription
offer_idstringSimOferta a ser adicionada.
quantityintegerNãoMín 1, padrão 1.
installmentsintegerNãoMín 1, padrão 1.
curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5/items \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "offer_id": "ofr_f6g7h8i9j0", "quantity": 2, "installments": 1 }'

Resposta 201 Created:

{
  "success": true,
  "data": {
    "id": "cki_f6g7h8i9j0",
    "checkout_session_id": "cks_a1b2c3d4e5",
    "offer_id": "ofr_f6g7h8i9j0",
    "currency": "BRL",
    "amount": 4990,
    "first_charge_amount": null,
    "quantity": 2,
    "installments": 1,
    "created_at": "2026-05-19T12:08:00.000Z"
  },
  "request_id": "req_9b2f4d6a",
  "timestamp": "2026-05-19T12:08:00.000Z"
}

PATCH/api/v1/checkout-sessions/:id/items/:itemId

Atualiza o quantity ou o installments de um item de linha. O offer_id é imutável; remova e adicione novamente para trocar de ofertas.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

FieldTypeRequiredDescription
quantityintegerNãoMín 1.
installmentsintegerNãoMín 1.
curl -X PATCH https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5/items/cki_f6g7h8i9j0 \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 3 }'

Resposta 200 OK — retorna o objeto de item atualizado.

DELETE/api/v1/checkout-sessions/:id/items/:itemId

Remove um item de linha.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

curl -X DELETE https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5/items/cki_f6g7h8i9j0 \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 204 No Content — corpo vazio.


Eventos

Os eventos são um log comportamental somente de adição (append-only) de uma sessão — úteis para análise de conversão, rastreamento de funil e depuração de desistências. Registrar um evento nunca altera o status da sessão por si só; as transições de status são orientadas pelos endpoints de ciclo de vida e pela cobrança.

FieldTypeDescription
idstringIdentificador do evento, prefixado com cke_.
checkout_session_idstringSessão pai, prefixada com cks_.
event_typeenumTipo do evento (veja abaixo).
source_urlstring | nullURL em que o comprador estava quando o evento disparou.
utm_sourcestring | nullOrigem de atribuição.
utm_mediumstring | nullMeio de atribuição.
utm_campaignstring | nullCampanha de atribuição.
ip_addressstring | nullIP do comprador no momento do evento.
user_agentstring | nullUser agent do comprador no momento do evento.
metadataobject | nullPayload livre para contexto específico do evento.
created_atstringTimestamp de criação ISO 8601.

Tipos de evento

event_typeWhen to record it
initiatedPágina de checkout carregada pela primeira vez.
customer_identifiedO comprador forneceu dados de identificação.
currency_changedO comprador trocou a moeda de exibição/cobrança.
payment_startedO comprador enviou os dados de pagamento.
payment_failedUma tentativa de cobrança foi recusada ou apresentou erro.
payment_succeededUma tentativa de cobrança foi bem-sucedida.
completedO checkout foi concluído com sucesso.
expiredA sessão ultrapassou sua expiração.
abandonedO comprador saiu sem concluir.

POST/api/v1/checkout-sessions/:id/events

Registra um evento.

Auth: chave de Organization (com merchant_id) ou chave de Merchant.

FieldTypeRequiredDescription
event_typeenumSimUm dos tipos de evento acima.
source_urlstringNãoURL da página quando o evento disparou.
utm_sourcestringNãoOrigem de atribuição.
utm_mediumstringNãoMeio de atribuição.
utm_campaignstringNãoCampanha de atribuição.
ip_addressstringNãoEndereço IP válido.
user_agentstringNãoUser agent do comprador.
metadataobjectNãoContexto livre (por exemplo, um motivo de recusa).
curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions/cks_a1b2c3d4e5/events \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "payment_failed",
    "source_url": "https://acme.com/checkout",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring_sale",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
    "metadata": { "decline_code": "insufficient_funds" }
  }'

Resposta 201 Created:

{
  "success": true,
  "data": {
    "id": "cke_a1b2c3d4e5",
    "checkout_session_id": "cks_a1b2c3d4e5",
    "event_type": "payment_failed",
    "source_url": "https://acme.com/checkout",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring_sale",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
    "metadata": { "decline_code": "insufficient_funds" },
    "created_at": "2026-05-19T12:12:00.000Z"
  },
  "request_id": "req_2e7a9c5d",
  "timestamp": "2026-05-19T12:12:00.000Z"
}

Cobrando uma sessão de checkout

Uma sessão de checkout nunca cobra a si mesma. Quando o comprador paga, crie uma transação que referencia a sessão pelo seu checkout_session_id. A Tokeflow deriva o amount e o currency da sessão e monta o pedido a partir dos itens de linha da sessão — de modo que a cobrança sempre corresponde ao snapshot que o comprador viu.

Quando checkout_session_id é fornecido, qualquer amount e currency enviados na requisição da transação são ignorados.

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0a9b8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d" \
  -d '{
    "checkout_session_id": "cks_a1b2c3d4e5",
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR"
  }'

Em caso de sucesso, a sessão transita para completed e completed_at é definido. Quando a cobrança só se resolve depois — um pagamento PIX confirmado pelo provedor, uma cobrança de cartão que o provedor não respondeu na hora, um QR code que expirou — a sessão é liquidada nesse momento: ela é concluída quando o pagamento tem sucesso, e um pagamento que falha ou expira a libera para que o comprador possa tentar de novo.

Um cliente recorrente também pode pagar a sessão com um cartão que salvou antes: envie payment_instrument_id e credential_on_file: true junto com o checkout_session_id. Isso exige o opt-in saved_card_checkout_enabled do merchant; veja Checkout com cartão salvo.

Colete os dados do cartão com segurança no cliente primeiro: os campos seguros da Tokeflow rodam dentro de iframes isolados e cross-origin; os dados do cartão são criptografados no navegador e nunca chegam aos seus servidores. Veja Transações para o fluxo completo de cobrança.

Envie um Idempotency-Key na cobrança para que uma requisição repetida retorne a transação original em vez de cobrar em duplicidade.

Erros

Os endpoints de checkout usam o envelope de erro padrão. Casos comuns:

HTTPtypeWhen
400validation_errorCampos ausentes/inválidos, ou nenhum customer_id nem customer/customer_email fornecido.
401authentication_errorChave de API ausente ou inválida.
403authorization_errorA chave não possui checkout:read / checkout:write.
404not_found_errorSessão, item, oferta ou cliente não encontrado para este Merchant.
409conflict_errorexternal_session_id duplicado para o Merchant.

Relacionados

Nesta página