> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upag.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Obter sessão (pagador)

> Recarrega a sessão no navegador com o clientSecret e descreve a visão do pagador

Recarrega a sessão como a página de checkout a enxerga, autenticada com o `clientSecret` recebido em [Iniciar sessão](./start): 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](./start), [Confirmar](./confirm) e dos [cupons](./apply-coupon). Com a chave secreta, a mesma URL devolve a [estrutura do servidor](./get).

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.

<Note>
  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.
</Note>

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.upag.dev/v1/checkout/sessions/4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26 \
    -H "Authorization: Bearer Zk3v0pQ8xJ2mR7cYt1LwN5dHs9uAeB4gXo6iFqVjT0E"
  ```

  ```javascript upag-js theme={null}
  import { UpagJs } from 'upag-js';

  const upag = new UpagJs('pk_test_your_public_key');

  const session = await upag.checkout.retrieve(id, clientSecret);
  ```
</CodeGroup>

## Parâmetros

<ParamField path="sessionId" type="string (uuid)" required>
  ID da sessão.
</ParamField>

<ParamField header="Authorization" type="string" required>
  `Bearer <clientSecret>`.
</ParamField>

## Resposta

`200 OK`

```json Response theme={null}
{
  "id": "4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26",
  "status": "open",
  "url": "https://checkout.upag.io/cs/4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26",
  "paymentLink": "c3f81a5e-2b94-4d70-a6e3-9d0b7c1f4a58",
  "expiresAt": "2026-10-08T19:00:00.000Z",
  "createdAt": "2026-10-07T19:00:00.000Z",
  "updatedAt": "2026-10-07T19:02:30.000Z",
  "currency": "brl",
  "subtotal": 19900,
  "discountAmount": 1990,
  "amount": 17910,
  "items": [
    {
      "id": "b7e1c4a9-3d52-4f08-86a1-2c9d5e7f0b34",
      "quantity": 1,
      "price": {
        "id": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61",
        "name": "Curso de Culinária",
        "billingType": "one_time",
        "interval": null,
        "intervalCount": null,
        "currency": "brl",
        "amount": 19900,
        "product": {
          "id": "7d2b5e90-1c34-4a68-b9f7-0e3a6c8d1f25",
          "name": "Curso de Culinária",
          "description": "12 aulas em vídeo",
          "image": null
        }
      }
    }
  ],
  "bumps": [],
  "discounts": [
    {
      "id": "0d6f3a82-5e19-4b47-a3c8-7f1b9e2d4c60",
      "item": "b7e1c4a9-3d52-4f08-86a1-2c9d5e7f0b34",
      "coupon": "a58c2e14-9d70-4f36-b1e5-3c8a6d0f7b92",
      "type": "coupon",
      "amount": 1990
    }
  ],
  "couponEnabled": true,
  "couponCode": "BEMVINDO10",
  "billingAddressCollection": "auto",
  "trial": null,
  "paymentMethodCollection": "always",
  "successUrl": "https://exemplo.com.br/obrigado",
  "cancelUrl": "https://exemplo.com.br/carrinho",
  "layout": null,
  "paymentMethods": [
    {
      "type": "card",
      "interestRate": 2.99,
      "installments": [
        { "count": 1, "amount": 17910, "total": 17910 },
        { "count": 2, "amount": 9055, "total": 18110 }
      ]
    },
    {
      "type": "pix",
      "interestRate": 0,
      "installments": [{ "count": 1, "amount": 17910, "total": 17910 }]
    }
  ],
  "customer": null,
  "charge": null,
  "invoice": null,
  "clientSecret": null,
  "account": {
    "displayName": "Loja Exemplo",
    "legalName": "Loja Exemplo Ltda",
    "publishableKey": "pk_test_your_public_key",
    "threeDSecureEnabled": false
  }
}
```

## Atributos

<ParamField body="id" type="string">
  UUID da sessão.
</ParamField>

<ParamField body="status" type="string">
  `open`, `complete` ou `expired`.
</ParamField>

<ParamField body="url" type="string | null">
  Endereço da página de checkout hospedada.
</ParamField>

<ParamField body="paymentLink" type="string | null">
  UUID do link de pagamento de origem.
</ParamField>

<ParamField body="expiresAt" type="string | null">
  ISO 8601 do vencimento.
</ParamField>

<ParamField body="createdAt" type="string">
  ISO 8601.
</ParamField>

<ParamField body="updatedAt" type="string">
  ISO 8601.
</ParamField>

<ParamField body="currency" type="string">
  Moeda dos itens (`brl` ou `usd`).
</ParamField>

<ParamField body="subtotal" type="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.
</ParamField>

<ParamField body="discountAmount" type="integer">
  Soma dos descontos do cupom, em centavos.
</ParamField>

<ParamField body="amount" type="integer">
  `subtotal - discountAmount`, nunca negativo, em centavos. É `0` quando um teste cobre todos os itens. Não inclui bumps nem juros de parcelamento.
</ParamField>

<ParamField body="items" type="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`).
</ParamField>

<ParamField body="bumps" type="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](./confirm).
</ParamField>

<ParamField body="discounts" type="array">
  Descontos de cupom: `id`, `item`, `coupon`, `type` (`coupon`) e `amount` (centavos).
</ParamField>

<ParamField body="couponEnabled" type="boolean">
  Se a página pode pedir um cupom ([aplicar](./apply-coupon)).
</ParamField>

<ParamField body="couponCode" type="string | null">
  Cupom aplicado.
</ParamField>

<ParamField body="billingAddressCollection" type="string">
  `auto`, `required` ou `none`.
</ParamField>

<ParamField body="trial" type="object | null">
  Presente só quando a sessão tem teste **e** um item recorrente. Veja [Teste grátis](../guides/free-trial).

  * `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.
</ParamField>

<ParamField body="paymentMethodCollection" type="string">
  `always` ou `if_required`.
</ParamField>

<ParamField body="successUrl" type="string | null">
  URL de retorno depois do pagamento.
</ParamField>

<ParamField body="cancelUrl" type="string | null">
  URL de retorno se o pagador desistir.
</ParamField>

<ParamField body="layout" type="object | null">
  Aparência da página: `theme`, `favicon`, `desktop` e `mobile`. `null` sem layout.
</ParamField>

<ParamField body="paymentMethods" type="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`.
</ParamField>

<ParamField body="customer" type="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`.
</ParamField>

<ParamField body="charge" type="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.
</ParamField>

<ParamField body="invoice" type="object | null">
  Fatura criada pela primeira confirmação: `id` e `status`. `null` antes dela e quando nada foi cobrado hoje.
</ParamField>

<ParamField body="clientSecret" type="string | null">
  Só vem preenchido em [Iniciar sessão](./start). Aqui é sempre `null`.
</ParamField>

<ParamField body="account" type="object">
  Dados da conta para a página: `displayName`, `legalName`, `publishableKey` (para tokenizar cartões) e `threeDSecureEnabled` (se a [autenticação 3D Secure](./three-d-secure) está disponível).
</ParamField>

## Erros

| Status | Código | Quando |
| - | - | - |
| `401` | n/a | `clientSecret` ausente, errado ou de outra sessão (a resposta é a mesma nos três casos) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.