Criar sessão de checkout

curl --request POST \
  --url https://api.upag.io/v1/checkout/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {}
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({items: [{}]})
};

fetch('https://api.upag.io/v1/checkout/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://api.upag.io/v1/checkout/sessions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({items: [{}]})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

POST

https://api.upag.io

checkout

sessions

Criar sessão de checkout

curl --request POST \
  --url https://api.upag.io/v1/checkout/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {}
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({items: [{}]})
};

fetch('https://api.upag.io/v1/checkout/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://api.upag.io/v1/checkout/sessions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({items: [{}]})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Abre uma sessão de checkout para um ou mais preços. Ela fica open por 24 horas, a menos que você envie expiresAt. A sessão criada com a chave secreta não tem clientSecret: ela é para você pagar do seu servidor com Confirmar. Para uma página de pagamento no navegador do cliente, crie um link de pagamento e abra a sessão com Iniciar sessão. Permissão: checkout_session.write. Apenas chave secreta (sk_…).

Os exemplos usam o sandbox (https://api.upag.dev/v1). Em produção use https://api.upag.io/v1 com sk_live_….

Endpoint

curl -X POST https://api.upag.dev/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
    "items": [
      { "price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61", "quantity": 1 }
    ],
    "paymentMethods": ["pix", "card"],
    "successUrl": "https://exemplo.com.br/obrigado",
    "cancelUrl": "https://exemplo.com.br/carrinho",
    "couponEnabled": true
  }'

import { Upag } from 'upag';

const upag = new Upag('sk_test_your_api_key');

const session = await upag.checkoutSessions.create({
  customer: '8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83',
  items: [{ price: '3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61', quantity: 1 }],
  paymentMethods: ['pix', 'card'],
  successUrl: 'https://exemplo.com.br/obrigado',
  cancelUrl: 'https://exemplo.com.br/carrinho',
  couponEnabled: true,
});

Com teste grátis

Para itens recorrentes, subscriptionData define o teste da assinatura que a sessão vai criar. Veja o fluxo completo em Teste grátis.

curl -X POST https://api.upag.dev/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61", "quantity": 1 }
    ],
    "paymentMethods": ["card"],
    "paymentMethodCollection": "always",
    "subscriptionData": {
      "trial": { "interval": "day", "intervalCount": 14 },
      "trialSettings": {
        "endBehavior": { "missingPaymentMethod": "cancel" }
      }
    }
  }'

const session = await upag.checkoutSessions.create({
  items: [{ price: '3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61', quantity: 1 }],
  paymentMethods: ['card'],
  paymentMethodCollection: 'always',
  subscriptionData: {
    trial: { interval: 'day', intervalCount: 14 },
    trialSettings: { endBehavior: { missingPaymentMethod: 'cancel' } },
  },
});

Parâmetros

array

required

Pelo menos um item. Os preços não podem se repetir (nem entre items e bumps), precisam estar na mesma moeda e, se recorrentes, ter o mesmo intervalo.

price (obrigatório): UUID do preço.
quantity (obrigatório): inteiro ≥ 1.

string (uuid)

UUID de um cliente da conta. Se omitido, o cliente é definido na confirmação.

array

Ofertas extras que o pagador pode aceitar na confirmação (bumps de Confirmar).

price (obrigatório): UUID do preço.
quantity: inteiro ≥ 1. Padrão 1.
title: até 255 caracteres.
description: texto livre.

array

pix e/ou card. Padrão ["pix", "card"]. Mínimo 1.

string (url)

URL de retorno depois do pagamento.

string (url)

URL de retorno se o pagador desistir.

string

default:"auto"

auto, required ou none.

boolean

default:"false"

Se permite aplicar um cupom à sessão.

object

Teste da assinatura criada pelos itens recorrentes. Exige pelo menos um item recorrente.

trial: { interval, intervalCount } com interval day, week ou month. Duração máxima de 730 dias (day até 730, week até 104, month até 24). Contada a partir da criação da assinatura.
trialEnd: data fixa de fim, com pelo menos 48 horas a partir de agora. Aceita ISO 8601 ou Unix em segundos. Não pode ser enviada junto com trial.
trialSettings.endBehavior.missingPaymentMethod: create_invoice (padrão: cobra o primeiro período por Pix) ou cancel. É o que acontece quando o teste acaba sem método de pagamento.

string

default:"always"

always ou if_required. Com if_required, uma sessão sem nada a pagar hoje pode ser confirmada sem cartão. Com always e um teste, card precisa estar em paymentMethods.

string

ISO 8601, no futuro. Padrão: 24 horas a partir de agora. null faz a sessão nunca expirar.

Resposta

201 Created com a sessão.

Response

{
  "id": "4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26",
  "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
  "checkoutLayout": null,
  "paymentLink": null,
  "paymentMethods": ["pix", "card"],
  "subscriptionData": {
    "trial": null,
    "trialEnd": null,
    "trialSettings": {
      "endBehavior": { "missingPaymentMethod": "create_invoice" }
    }
  },
  "paymentMethodCollection": "always",
  "status": "open",
  "url": "https://checkout.upag.io/cs/4f9d2b71-6c03-4e58-9a1d-8b3e7c0f5a26",
  "expiresAt": "2026-10-08T19:00:00.000Z",
  "createdAt": "2026-10-07T19:00:00.000Z",
  "updatedAt": "2026-10-07T19:00:00.000Z",
  "billingAddressCollection": "auto",
  "successUrl": "https://exemplo.com.br/obrigado",
  "cancelUrl": "https://exemplo.com.br/carrinho",
  "latitude": null,
  "longitude": null,
  "country": null,
  "region": null,
  "city": null,
  "invoice": null,
  "subscription": null,
  "couponEnabled": true,
  "couponCode": null,
  "items": [
    {
      "id": "b7e1c4a9-3d52-4f08-86a1-2c9d5e7f0b34",
      "price": "3a7e9c14-6b2d-4f85-9e10-5c8d2a7b4f61",
      "quantity": 1
    }
  ],
  "bumps": [],
  "discounts": []
}

Erros

Status	Código	Quando
`404`	`CUSTOMER_NOT_FOUND`	O cliente não existe na conta
`404`	`PRICE_NOT_FOUND` / `PRODUCT_NOT_FOUND`	Um preço, ou o produto dele, não existe na conta
`400`	`CHECKOUT_SESSION_DUPLICATE_PRICE`	O mesmo preço aparece duas vezes
`400`	`CHECKOUT_SESSION_CURRENCY_MISMATCH`	Os preços têm moedas diferentes
`400`	`CHECKOUT_SESSION_RECURRING_INTERVAL_MISMATCH`	Os preços recorrentes têm intervalos diferentes
`400`	`CHECKOUT_SESSION_TRIAL_REQUIRES_RECURRING_ITEM`	Há teste, mas nenhum item é recorrente
`400`	`CHECKOUT_SESSION_TRIAL_REQUIRES_CARD`	Há teste com `paymentMethodCollection: "always"` e `card` fora de `paymentMethods`
`422`	`VALIDATION_FAILED`	Corpo inválido: `trial` e `trialEnd` juntos, `trialEnd` com menos de 48 horas, `expiresAt` no passado, `trial` acima do máximo

Cobranças

Cartões

3D Secure

Clientes

Produtos

Preços

Cupons

Faturas

Assinaturas

Links de pagamento

Sessões de checkout

Layouts de checkout

Transferências Pix

Subcontas

Apps

Chave de API

Criar sessão de checkout

Endpoint

Com teste grátis

Parâmetros

Resposta

Erros

​Endpoint

​Com teste grátis

​Parâmetros

​Resposta

​Erros

Endpoint

Com teste grátis

Parâmetros

Resposta

Erros