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
| Field | Type | Description |
|---|---|---|
id | string | Identificador da sessão, prefixado com cks_. |
merchant_id | string | Merchant proprietário, prefixado com mrc_. |
offer_id | string | Oferta primária que iniciou o checkout, prefixada com ofr_. |
customer_id | string | null | Definido assim que o cliente é identificado, prefixado com cust_. |
customer_email | string | null | E-mail do cliente, preenchido na identificação. |
customer_name | string | null | Nome do cliente, quando conhecido. |
selected_currency | string | null | Moeda ISO 4217 da sessão. Assume por padrão a moeda padrão da oferta. |
status | enum | Estado do ciclo de vida da sessão. Veja Status. |
external_session_id | string | null | Sua própria referência de sessão ou conta. Única por Merchant quando definida. |
expires_at | string | null | Horário ISO 8601 após o qual a sessão é tratada como expirada. |
completed_at | string | null | Definido quando a sessão transita para completed. |
created_at | string | Timestamp de criação ISO 8601. |
updated_at | string | Timestamp da última atualização ISO 8601. |
items | array | Itens de linha. Incluído por padrão em get-by-id; veja Itens de linha. |
events | array | Eventos de rastreamento. Incluído quando solicitado; veja Eventos. |
Status
| Status | Meaning |
|---|---|
initiated | Sessão criada; nenhum cliente identificado ainda. |
customer_identified | Um cliente foi vinculado à sessão. |
payment_pending | Uma cobrança foi iniciada contra a sessão. |
completed | A sessão foi paga; completed_at está definido. |
expired | A sessão ultrapassou expires_at sem ser concluída. |
abandoned | A 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.
| Field | Type | Required | Description |
|---|---|---|---|
offer_id | string | Sim | Oferta primária que iniciou o checkout. |
customer_id | string | Condicional | Id de cliente existente. Forneça este ou customer. |
customer | object | Condicional | Customer inline a ser criado/reutilizado. Forneça este ou customer_id. |
selected_currency | string | Não | Código ISO 4217. Omita para usar a moeda padrão da oferta. |
external_session_id | string | Não | Sua referência de sessão/conta. Única por Merchant. |
expires_at | string | Não | Timestamp ISO 8601; deve estar no futuro. |
items | array | Não | Itens de linha (veja abaixo). Omita para um único item padrão. |
Cada entrada em items:
| Field | Type | Required | Description |
|---|---|---|---|
offer_id | string | Sim | Oferta a ser incluída como item de linha. |
quantity | integer | Não | Unidades desta oferta. Mín 1, padrão 1. |
installments | integer | Não | Parcelas 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 param | Type | Description |
|---|---|---|
page | integer | Número da página, começando em 1. Padrão 1. |
limit | integer | Itens por página. Padrão 20, máx 100. |
status | enum | Filtra por status da sessão. |
offer_id | string | Sessões vinculadas a uma oferta primária específica. |
customer_id | string | Sessões de um cliente específico. |
customer_email | string | Sessões que correspondem a um e-mail de cliente. |
external_session_id | string | Busca pela sua referência externa de sessão. |
merchant_id | string | Obrigató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 param | Type | Description |
|---|---|---|
include_items | boolean | Inclui o array items. Assume true por padrão; passe false para omitir. |
include_events | boolean | Inclui 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.
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | string | Não | Vincula um cliente existente. |
customer | object | Não | Customer inline a ser criado/reutilizado. |
selected_currency | string | Não | Altera a moeda da sessão (ISO 4217). |
external_session_id | string | Não | Atualiza sua referência externa. |
expires_at | string | Não | Prorroga 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.
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | string | Condicional | Id de cliente existente. Forneça este ou customer_email. |
customer_email | string | Condicional | E-mail do cliente; resolve ou cria o cliente. |
customer_name | string | Não | Nome 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.
| Field | Type | Description |
|---|---|---|
id | string | Identificador do item, prefixado com cki_. |
checkout_session_id | string | Sessão pai, prefixada com cks_. |
offer_id | string | Oferta que este item de linha referencia. |
currency | string | Moeda ISO 4217 do snapshot. |
amount | integer | Snapshot do preço recorrente/padrão, em unidades menores. |
first_charge_amount | integer | null | Quanto 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. |
quantity | integer | Unidades desta oferta. |
installments | integer | Parcelas selecionadas pelo comprador (1 = cobrança única). |
created_at | string | Timestamp 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.
| Field | Type | Required | Description |
|---|---|---|---|
offer_id | string | Sim | Oferta a ser adicionada. |
quantity | integer | Não | Mín 1, padrão 1. |
installments | integer | Não | Mí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.
| Field | Type | Required | Description |
|---|---|---|---|
quantity | integer | Não | Mín 1. |
installments | integer | Não | Mí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.
| Field | Type | Description |
|---|---|---|
id | string | Identificador do evento, prefixado com cke_. |
checkout_session_id | string | Sessão pai, prefixada com cks_. |
event_type | enum | Tipo do evento (veja abaixo). |
source_url | string | null | URL em que o comprador estava quando o evento disparou. |
utm_source | string | null | Origem de atribuição. |
utm_medium | string | null | Meio de atribuição. |
utm_campaign | string | null | Campanha de atribuição. |
ip_address | string | null | IP do comprador no momento do evento. |
user_agent | string | null | User agent do comprador no momento do evento. |
metadata | object | null | Payload livre para contexto específico do evento. |
created_at | string | Timestamp de criação ISO 8601. |
Tipos de evento
event_type | When to record it |
|---|---|
initiated | Página de checkout carregada pela primeira vez. |
customer_identified | O comprador forneceu dados de identificação. |
currency_changed | O comprador trocou a moeda de exibição/cobrança. |
payment_started | O comprador enviou os dados de pagamento. |
payment_failed | Uma tentativa de cobrança foi recusada ou apresentou erro. |
payment_succeeded | Uma tentativa de cobrança foi bem-sucedida. |
completed | O checkout foi concluído com sucesso. |
expired | A sessão ultrapassou sua expiração. |
abandoned | O 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.
| Field | Type | Required | Description |
|---|---|---|---|
event_type | enum | Sim | Um dos tipos de evento acima. |
source_url | string | Não | URL da página quando o evento disparou. |
utm_source | string | Não | Origem de atribuição. |
utm_medium | string | Não | Meio de atribuição. |
utm_campaign | string | Não | Campanha de atribuição. |
ip_address | string | Não | Endereço IP válido. |
user_agent | string | Não | User agent do comprador. |
metadata | object | Não | Contexto 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:
| HTTP | type | When |
|---|---|---|
400 | validation_error | Campos ausentes/inválidos, ou nenhum customer_id nem customer/customer_email fornecido. |
401 | authentication_error | Chave de API ausente ou inválida. |
403 | authorization_error | A chave não possui checkout:read / checkout:write. |
404 | not_found_error | Sessão, item, oferta ou cliente não encontrado para este Merchant. |
409 | conflict_error | external_session_id duplicado para o Merchant. |
Relacionados
- Transações — cobre uma sessão e execute o pagamento.
- Customers — os registros de cliente aos quais as sessões se vinculam.
- Ofertas — as ofertas precificadas de que os itens de linha capturam snapshots.
- Idempotência e limites de taxa — retries seguros na criação e na cobrança.
- Visão geral da referência da API — envelopes, IDs, valores monetários e paginação.