Skip to main content
Uma sessão de checkout representa uma compra em andamento: os itens, os métodos de pagamento aceitos, o pagador e, depois da confirmação, a fatura e a assinatura que ela gerou. Ela nasce de duas formas:
  • Do seu servidor, com a chave secreta: Criar sessão. Você paga a sessão por Confirmar, também no servidor.
  • Do navegador do pagador, a partir de um link de pagamento: Iniciar sessão. A sessão é uma cópia do link no momento da abertura (itens, bumps, métodos, URLs, trial); editar o link depois não muda uma sessão já aberta. A resposta traz o clientSecret, a única credencial que o navegador usa para ler e pagar aquela sessão.
Uma sessão fica open por 24 horas (ou até expiresAt) e vira complete quando o pagamento é aprovado (ou, num teste sem nada a cobrar hoje, quando é confirmada).

​
Endpoints

Gerenciamento, com chave secreta (sk_…): Ler e pagar uma sessão: aceitam a chave secreta ou o clientSecret da própria sessão (Authorization: Bearer <clientSecret>): Públicos, sem autenticação:
Sandbox: https://api.upag.dev/v1 com sk_test_…. Produção: https://api.upag.io/v1 com sk_live_…. O clientSecret nunca vai para uma chave secreta nem para logs; trate-o como uma senha de uma sessão só.

​
Estrutura

É o que o servidor devolve em Criar, Listar, Obter e Atualizar:

​
Atributos

​
string
UUID da sessão.
​
string | null
UUID do cliente da sessão. null até você informar um (por Criar ou Atualizar) ou até o pagador confirmar.
​
string | null
UUID do layout de checkout copiado do link. null em sessões criadas por Criar.
​
string | null
UUID do link de pagamento de origem. null em sessões criadas por Criar e Shopify.
​
array
Métodos aceitos: pix e/ou card.
​
object
Como começa a assinatura que os itens recorrentes criam.
  • trial: duração relativa do teste (interval: day, week ou month; intervalCount), contada a partir do momento em que a assinatura é criada. null sem teste.
  • trialEnd: data fixa de fim do teste, em ISO 8601. null sem teste ou com trial.
  • trialSettings.endBehavior.missingPaymentMethod: create_invoice (cobra o primeiro período por Pix) ou cancel, quando o teste acaba sem método de pagamento. Veja Teste grátis.
​
string
always (padrão) ou if_required. Com if_required, uma sessão sem nada a pagar hoje (teste) pode terminar sem método de pagamento.
​
string
open, complete ou expired.
​
string | null
Endereço da página de checkout hospedada da sessão. null quando o checkout hospedado não está configurado.
​
string | null
ISO 8601 do vencimento. Depois dele a sessão não aceita mais pagamento. null quando a sessão nunca expira.
​
string
ISO 8601.
​
string
ISO 8601.
​
string
auto, required ou none: se a página pede o endereço de cobrança.
​
string | null
URL para onde o pagador volta depois de pagar.
​
string | null
URL para onde o pagador volta se desistir.
​
number | null
Reservado para a localização do pagador. A API não preenche no momento (null), assim como longitude, country, region e city.
​
string | null
UUID da fatura criada na primeira confirmação. null antes dela, e também numa sessão confirmada sem nada a cobrar hoje.
​
string | null
UUID da assinatura criada quando a sessão tem itens recorrentes. null antes da confirmação.
​
boolean
Se o pagador pode aplicar um cupom.
​
string | null
Código do cupom aplicado.
​
array
Itens da sessão.
  • id: UUID do item.
  • price: UUID do preço.
  • quantity: quantidade.
​
array
Ofertas extras (order bumps) que o pagador pode aceitar na confirmação.
  • id: UUID do bump.
  • price: UUID do preço.
  • quantity: quantidade.
  • amount: valor do preço × quantity, em centavos, calculado quando a sessão foi criada.
  • title, description: textos opcionais (null quando ausentes).
​
array
Descontos aplicados por cupom, um por item elegível.
  • id: UUID do desconto.
  • item: UUID do item da sessão.
  • coupon: UUID do cupom.
  • type: coupon.
  • amount: desconto em centavos.

​
Status

​
Visão do pagador

As rotas que o navegador chama com o clientSecret (Iniciar, Obter, Confirmar, cupom) devolvem uma visão achatada e pronta para a página de checkout, em vez da estrutura acima: itens com o preço e o produto expandidos, subtotal, discountAmount e amount (em centavos), opções de parcelamento por método, trial, customer, charge, invoice e dados da conta. A forma é a mesma em todas essas rotas; só clientSecret muda (vem preenchido apenas em Iniciar, null nas demais). Os campos estão em Obter sessão (pagador).

​
Webhooks

As mudanças chegam por webhooks de checkout.