Sessões de checkout

Introdução

Uma Checkout Session (checkout.session) é um carrinho hospedado: você cria a sessão pela API, recebe uma URL de checkout pronta e a entrega ao comprador (redirect, e-mail, SMS ou QR code). O comprador preenche os dados e paga na página hospedada da Selectwin; você acompanha o resultado por webhook (checkout.session.completed + a transação correspondente).

Diferente do Payment Link (reutilizável, sem comprador fixo), a session representa uma intenção de compra específica — com itens já precificados pelo backend, cliente/endereço opcionais e um externalTransactionId para reconciliação com o seu ERP.

Modelo de precificação (autoritativo no backend)

A sessão é um snapshot durável do carrinho/cliente/UTM. Os itens são fornecidos pelo comprador e guardados como JSONB; o worker de pagamento é a autoridade que os valida contra o catálogo no momento do submit (/pay) — não na criação da sessão. Cada lineItems[] é resolvido server-side nesse momento:

• Catálogo — informe id de uma variante (var_...). O backend lê o preço de productVariants. Envie só id + quantity; opcionalmente sobrescreva com unitPrice.
• Ad-hoc — sem variante de catálogo: informe name e unitPrice (centavos). Útil para serviços avulsos.

O carrinho é payment-type-agnostic: pode misturar itens oneTime e variantes recurring (a sessão vira assinatura no momento da cobrança, lendo billingType/cycles/trialInterval da variante — você não envia esses campos).

Valores em centavos. unitPrice/totals.* são inteiros (ex.: 49700 = R$ 497,00).

Estrutura do Objeto checkout.session

{
  "object": "checkout.session",
  "id": "sess_a1b2c3d4e5f6789012ab",
  "url": "https://checkout.selectwin.io/p/live/sess_a1b2c3d4e5f6789012ab",
  "status": "active",
  "ambient": "live",
  "source": "api",
  "currency": "BRL",

  "lineItems": [
    { "id": "var_main_product", "name": "Curso Premium", "quantity": 1, "unitPrice": 49700,
      "currency": "BRL", "isOrderbump": false, "isUpsell": false,
      "metadata": { "sku": "ABC-123" }, "externalReference": "erp-ref-9" }
  ],
  "totals": { "amount": 46523, "discount": 5167, "shipping": 0, "tax": 0 },
  "coupons": [{ "code": "DESCONTO10", "type": "percentage", "value": 10 }],

  "customer": {
    "email": "[email protected]", "fullName": "Maria Silva",
    "document": { "number": "12345678909", "type": "cpf" },
    "telephone": { "countryCode": "55", "areaCode": "11", "number": "999998888" }
  },
  "address": {
    "postcode": "01310-100", "street": "Av. Paulista", "number": "1000",
    "district": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BR"
  },

  "paymentMethods": ["pix", "credit", "billet"],
  "paymentSelection": null,
  "redirectUrls": {
    "paid": "https://seller.com/obrigado",
    "refused": "https://seller.com/recusado",
    "pending": "https://seller.com/processando"
  },

  "utm": { "source": "newsletter", "campaign": "junho" },
  "metadata": { "erpOrderId": "9921" },
  "customInputs": null,
  "integrationType": "shopify",
  "integrationId": "cmp_shop_123",
  "externalTransactionId": "pedido-7781",

  "firstInitialization": true,
  "online": false,
  "expiresAt": "2026-06-12T12:00:00.000Z",
  "createdAt": "2026-06-08T12:00:00.000Z",
  "updatedAt": "2026-06-08T12:00:00.000Z"
}

Atribuição (utm)

De onde veio a venda. Capturada uma vez, na criação, e imutável: um PUT posterior com outra utm é ignorado enquanto a sessão já tiver atribuição — o afiliado que trouxe o comprador não pode ser sobrescrito no meio do checkout. Quando a sessão é cobrada, os cinco campos UTM descem para colunas próprias da transação e passam a alimentar os relatórios de canal.

{ "utm": { "source": "newsletter", "medium": "email", "campaign": "junho", "content": "banner-topo", "term": "curso", "gclid": "Cj0KCQ...", "fbclid": "IwAR1x..." } }

Duas grafias entram, uma sai. source, utm_source e utmSource são todas aceitas — a URL do anúncio carimba utm_source, e repassá-la crua funciona. O que fica armazenado e é devolvido na leitura é sempre a forma curta (source, medium, campaign, content, term), acompanhada dos identificadores de clique que vierem (gclid, fbclid, ttclid, msclkid, twclid, wbraid, gbraid, irclickid, li_fat_id, epik).

Chave desconhecida é descartada. Valor vazio, null, ou o texto literal "null"/"undefined" conta como ausente — então um objeto só de nulos equivale a não enviar utm, e não consome a captura única: a campanha real ainda pode ser gravada depois.

No checkout hospedado nada disso precisa ser enviado: os utm_* da URL de acesso são lidos e normalizados automaticamente na primeira inicialização da sessão.

Ciclo de Vida (status)

O enum nativo de status é active, completed, cancelled, abandoned, expired — não existe status pending.

Em status terminal a url redireciona para uma página de estado em vez de renderizar o checkout.

Recursos Disponíveis

Filtros da listagem: status (enum), source (texto, máx. 20), id (sess_/ckts_/ses_), daterange* e paginação (limit/offset/sort). Não há filtro por externalTransactionId.

Criar

POST /v1/checkouts/sessions
SelectKey: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "externalTransactionId": "pedido-7781",
  "lineItems": [
    { "id": "var_main_product", "quantity": 1 },
    { "id": "var_orderbump_book", "quantity": 1, "isOrderbump": true }
  ],
  "customer": { "email": "[email protected]", "fullName": "Maria Silva" },
  "coupons": [{ "code": "DESCONTO10" }],
  "redirectUrls": { "paid": "https://seller.com/obrigado" },
  "metadata": { "erpOrderId": "9921" }
}

Resposta 201 = o objeto checkout.session acima. Redirecione o comprador para url.

Campos aceitos (todos opcionais): items/lineItems (carrinho), customer, address, client (carrega UTM), coupons, paymentMethods, redirectUrls, shippingDelivery, source, language, timezone, totalAmount/totalDiscount/totalShipping/totalTax (centavos), utm, metadata, integrationType, integrationId, externalTransactionId, expiresAt e onBehalfOf. onBehalfOf (publicId de um sub-vendedor que você possui) faz o charge único da sessão ser liquidado no sub-vendedor (marketplace direct-charge) e você (plataforma) recebe a application fee; a posse + função de marketplace são validadas na criação (senão onBehalfOfInvalid, 422). O campo ambient é aceito por compatibilidade mas ignorado — o ambiente vem do principal (namespace da chave).

Preço ad-hoc (sem catálogo):

{ "lineItems": [{ "name": "Consultoria 1h", "quantity": 2, "unitPrice": 25000 }] }

Atualizar

A semântica do PUT é de merge parcial, com recompute seguro de totais:

• Campos simples (customer, address, metadata, redirectUrls, externalTransactionId, expiresAt) — atualizam sem recalcular o carrinho.
• lineItems enviado → re-precifica itens + totais e zera os cupons (reenvie coupons no mesmo PUT para reaplicar).
• coupons enviado sem lineItems → re-precifica os itens atuais para recalcular o desconto.
• O corpo aceita também status, restrito a active ou abandoned (um abandoned voltando para active reativa a mesma sessão e emite checkout.session.reactivated).
• Só funciona em status não-terminal; em completed/cancelled/expired → checkoutSessionNotUpdatable (409).
• Selada enquanto há cobrança em voo. Depois que um job de pagamento é criado para a sessão e enquanto ele estiver pending/processing/requiresAction, um PUT que toque os campos de dinheiro (items/lineItems, coupons, totalAmount, totalDiscount, totalShipping) responde 409 sessionHasActivePayment, com params[0].jobId apontando o job que segura a sessão. Os demais campos continuam atualizáveis. O motivo é que o worker cobra o total congelado mas remonta a transação a partir do carrinho corrente — mexer nele nessa janela desalinharia o que foi cobrado do que foi vendido. Espere o job chegar a um estado terminal (ou abra uma nova sessão).
• O preço cobrado é o congelado no job. Ao submeter o pagamento, os totais são gravados na row do job; é essa a quantia cobrada — a coluna totalAmount da sessão é apenas o espelho. Se as duas divergirem, vale a do job (e a divergência é registrada em log). Junto com o item acima: o selo trava a mercadoria, o congelamento trava o preço.

Cancelar

DELETE é soft-cancel: marca status=cancelled e preserva a linha (os dados de funil/abandono vivem nela); sessões já completed não são afetadas. Resposta 200:

{ "id": "sess_a1b2c3d4e5f6789012ab", "resource": "checkoutSession", "deleted": true }

Se a sessão não existir → checkoutSessionNotFound (404).

Pagar (assíncrono)

POST /v1/checkouts/sessions/{id}/pay registra a seleção de pagamento do comprador e enfileira um job assíncrono — não cobra inline. A cobrança é feita pelo worker, que lê o snapshot da sessão.

{ "payment": { "method": "credit", "cardId": "card_01hqzv...", "installments": 3, "capture": true } }

Resposta 202 Accepted (envelope de job, sem _links):

{ "jobId": "payjob_01hqzv...", "status": "pending", "sessionId": "sess_a1b2c3d4e5f6789012ab" }

status do job pode ser pending, processing, requiresAction, completed ou failed. Só sessões active são pagáveis; senão checkoutSessionNotPayable (409). Sessão inexistente → checkoutSessionNotFound (404).

Configuração (paymentMethods / redirectUrls)

Você pode enviá-los no corpo da sessão. Quando omitidos, o backend usa o checkout template global da empresa (isGlobal) para os métodos habilitados e as URLs de redirect; o redirectUrls do corpo sobrescreve por sessão. Sem template e sem corpo, o default é ["pix", "credit", "billet"].

Cupons

Envie coupons por código — aceita tanto a forma de string (["DESCONTO10"]) quanto de objeto ([{ "code": "DESCONTO10" }]); ambas são guardadas verbatim e ecoadas como { code, type, value }. A elegibilidade (datas, limite de uso, mínimo de carrinho, itens permitidos) e o desconto são validados na cobrança (no /pay), não na criação da sessão. Cupom inexistente → couponNotFound; inelegível → couponExpired / couponMinCartAmount / etc. (catálogo de Coupons).

Telemetria de interatividade

Enquanto o comprador está na página, o checkout hospedado envia telemetria de interatividade — forma e tempo da interação (etapa atual, tempo ativo, edições por campo, tentativas de pagamento, trocas de parcelamento), nunca o valor digitado em campo nenhum. Sobre esse traço o backend calcula, por sessão, um diagnóstico de intenção e abandono. Você lê o resultado por dois endpoints; o terceiro só interessa a quem renderiza o próprio front-end do checkout.

Token de telemetria — POST /v1/checkouts/sessions/{id}/telemetry-token

Emite a capability que o front-end usa para enviar os ticks de telemetria. Só serve para escrever telemetria nessa sessão e só é emitida para sessão active (409 checkoutSessionNotTrackable nas demais). O checkout hospedado pela Selectwin já faz isso sozinho — você só precisa deste endpoint se renderiza o checkout por conta própria em cima de uma sessão.

{
  "object": "checkout.session.telemetryToken",
  "id": "sess_abc123",
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expiresAt": "2026-07-15T12:00:00.000Z",
  "endpoint": "/core/checkout/v1/sessions/sess_abc123/telemetry",
  "intervalMs": 10000
}

Comportamento — GET /v1/checkouts/sessions/{id}/behavior

O roll-up da sessão (engagement) e o diagnóstico calculado sobre ele (insights):

{
  "object": "checkout.session.behavior",
  "id": "sess_abc123",
  "status": "active",
  "engagement": {
    "totalTimeSpentMs": 384000,
    "activeTimeMs": 250000,
    "maxStepReached": 4,
    "visitCount": 2,
    "eventCount": 137,
    "lastTelemetryAt": "2026-07-14T12:06:11.000Z"
  },
  "insights": {
    "intentScore": 88,
    "abandonmentRisk": 64,
    "automationScore": 5,
    "confidence": 92,
    "stage": "stuck",
    "frictionPoints": [
      { "area": "pagamento", "severity": "high", "evidence": "2 tentativa(s) de pagamento recusada(s)." }
    ],
    "recommendedAction": "offerHelp",
    "reasons": ["2 tentativa(s) de pagamento registrada(s) — a intenção de compra é concreta."],
    "summary": "Comprador travado há ~6min, na etapa 4 de 4. Intenção 88/100, risco de abandono 64/100.",
    "computedAt": "2026-07-14T12:06:11.000Z"
  },
  "behavior": { "...": "o roll-up cru" }
}

insights: null significa "não há telemetria desta sessão" — não "intenção zero". Não pinte null como 0 na tela.

Eventos — GET /v1/checkouts/sessions/{id}/events

O traço evento a evento, em ordem, para "replay" da sessão. Paginação por cursor: limit (1–500, default 200) e afterSeq (devolve só eventos com seq maior).

{
  "object": "list",
  "id": "sess_abc123",
  "total": 137,
  "hasMore": false,
  "data": [
    { "seq": 42, "type": "field.paste", "step": 4, "payload": { "field": "cardNumber" },
      "occurredAt": "2026-07-14T12:00:03.100Z", "receivedAt": "2026-07-14T12:00:05.000Z" }
  ]
}

O vocabulário de type é fechado (session.view, step.enter, field.edit, field.paste, payment.submit, payment.result, click.rage, exit.intent…) e o payload carrega forma e tempo, jamais conteúdo: quantas correções, se houve colagem, qual validação falhou — nunca o que foi digitado.

Webhooks

O payload desses eventos é o objeto checkout.session completo (mesma forma da leitura).

O caminho recomendado de confirmação é webhook + a transação correspondente — veja Proibição de Polling e Verificando Assinaturas de Webhook.

Melhores Práticas

1. Resolva preço pelo catálogo (var_*) sempre que possível; use ad-hoc só para itens fora do catálogo.
2. Use externalTransactionId para reconciliar (campo ecoado em cada sessão; a listagem filtra por status/source/id/datas, não por externalTransactionId).
3. Reaja a checkout.session.completed em vez de fazer polling no GET.
4. Reenvie coupons ao alterar lineItems num PUT, já que mudar o carrinho zera os descontos.
5. Defina expiresAt se a idade máxima padrão (24h) não fizer sentido para o seu fluxo.

Integração com Outros Recursos

• Products / Variants — lineItems[].id referencia variantes (var_*); o preço vem da variante.
• Coupons — aplicados por código; validados/precificados no create/update.
• Transactions — a sessão concluída gera uma transação (cobrança).
• Customers / Addresses — o snapshot da sessão é resolvido em cliente/endereço no momento do pagamento.
• Webhooks — checkout.session.completed para confirmação assíncrona.