Skip to main content
GET
Obter sessão (pagador)
Recarrega a sessão como a página de checkout a enxerga, autenticada com o clientSecret recebido em Iniciar sessão: itens com preço e produto, valores a pagar hoje, opções de parcelamento, teste, cupom e, depois da confirmação, a cobrança. É a visão do pagador, a mesma de Iniciar, Confirmar e dos cupons. Com a chave secreta, a mesma URL devolve a estrutura do servidor. Permissão: checkout_session.read. O clientSecret só alcança a sessão da própria rota; qualquer outro erro de credencial responde 401 sem detalhes.
Os exemplos usam o sandbox (https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_…; no navegador, o upag-js usa só a chave pública.

​
Endpoint

​
Parâmetros

​
string (uuid)
required
ID da sessão.
​
string
required
Bearer <clientSecret>.

​
Resposta

200 OK
Response

​
Atributos

​
string
UUID da sessão.
​
string
open, complete ou expired.
​
string | null
Endereço da página de checkout hospedada.
​
string | null
UUID do link de pagamento de origem.
​
string | null
ISO 8601 do vencimento.
​
string
ISO 8601.
​
string
ISO 8601.
​
string
Moeda dos itens (brl ou usd).
​
integer
O que os itens custam hoje, em centavos. Itens recorrentes sob um teste ainda não são cobrados e não entram. Bumps não entram.
​
integer
Soma dos descontos do cupom, em centavos.
​
integer
subtotal - discountAmount, nunca negativo, em centavos. É 0 quando um teste cobre todos os itens. Não inclui bumps nem juros de parcelamento.
​
array
Itens da sessão.
  • id: UUID do item.
  • quantity: quantidade.
  • price: id, name, billingType (one_time ou recurring), interval, intervalCount, currency, amount (centavos) e product (id, name, description, image).
​
array
Ofertas extras. Cada uma tem id, quantity, amount (centavos), title, description e price (mesmo formato dos itens). O pagador aceita as que quiser enviando os id em bumps na confirmação.
​
array
Descontos de cupom: id, item, coupon, type (coupon) e amount (centavos).
​
boolean
Se a página pode pedir um cupom (aplicar).
​
string | null
Cupom aplicado.
​
string
auto, required ou none.
​
object | null
Presente só quando a sessão tem teste e um item recorrente. Veja Teste grátis.
  • interval: day, week ou month; null quando o teste é uma data fixa.
  • intervalCount: duração; null quando é uma data fixa.
  • endsAt: ISO 8601. Antes da conclusão é uma prévia, como se a assinatura fosse criada agora. Depois, é o fim real do teste.
​
string
always ou if_required.
​
string | null
URL de retorno depois do pagamento.
​
string | null
URL de retorno se o pagador desistir.
​
object | null
Aparência da página: theme, favicon, desktop e mobile. null sem layout.
​
array
Métodos que a conta tem ativados, com o cartão primeiro.
  • type: card ou pix.
  • interestRate: juros do parcelamento para o pagador, em percentual, medidos na parcela de 2x. 0 no Pix e quando os juros não são do pagador.
  • installments: opções { count, amount, total }. total é o que será cobrado (em centavos); amount é a primeira parcela e as demais são floor(total / count). O Pix só tem count: 1.
Quando nada é cobrado hoje (teste), não há tabela de parcelas: a lista traz só o cartão para guardar (installments: []) se paymentMethodCollection é always, e vem vazia com if_required.
​
object | null
Pagador, depois que a sessão foi confirmada: id, name, email, document (type e number mascarado) e, quando existirem, phone (mascarado) e address.
​
object | null
Última tentativa de pagamento: id, type, status, amount (centavos, já com juros), interestAmount, installments, paidAt, card (brand e last4, só cartão), pix (copyPaste e expiresAt, só Pix), error (code e message quando falhou) e nextAction (sempre null). null antes da primeira tentativa.
​
object | null
Fatura criada pela primeira confirmação: id e status. null antes dela e quando nada foi cobrado hoje.
​
string | null
Só vem preenchido em Iniciar sessão. Aqui é sempre null.
​
object
Dados da conta para a página: displayName, legalName, publishableKey (para tokenizar cartões) e threeDSecureEnabled (se a autenticação 3D Secure está disponível).

​
Erros