Criar nova sessão de checkout

curl --request POST \
  --url https://besimplo.com/api/v1/checkout/sessions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "session": {
    "success_url": "https://example.com/success",
    "line_items": [
      {
        "price_id": "price_01h455vb4pex5vsknk084sn02q",
        "quantity": 1
      }
    ],
    "external_code": "CHECKOUT-SESSION-XYZ",
    "customer_id": "cus_01h455vb4pex5vsknk084sn02p",
    "customer": "<unknown>",
    "mode": "subscription",
    "return_url": "https://example.com/return",
    "metadata": [],
    "discounts": [
      {
        "type": "percentage",
        "percentage": 20,
        "cycles": 3,
        "description": "Promo Q2"
      }
    ]
  }
}
'

{
  "live_mode": true,
  "customer": {
    "id": "cus_01h455vb4pex5vsknk084sn02p"
  },
  "invoice": {
    "id": "in_01h455vb4pex5vsknk084sn02q"
  },
  "subscription": {
    "id": "sub_01h455vb4pex5vsknk084sn02s"
  },
  "amount": 9990,
  "currency": "brl",
  "url": "https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02q?session_id=cs_01h455vb4pex5vsknk084sn02q"
}

Checkout

Criar nova sessão de checkout

Criar nova sessão de checkout na sua conta. A sessão permite que um cliente complete um pagamento ou assinatura através de uma interface web.

O cliente é opcional. Você pode:

Enviar customer_id para vincular um cliente já existente.
Enviar customer com os dados para criar um cliente junto com a sessão.
Omitir ambos: a sessão é criada sem cliente vinculado e o próprio comprador preencherá os dados (nome, CPF/CNPJ, e-mail e telefone) ao acessar a url retornada. Nesse caso, customer, invoice, subscription e amount voltam null na resposta e são preenchidos somente após o comprador finalizar o cadastro.

Validação de line_items e discounts ocorre em todos os casos — uma sessão sem cliente também recebe 404 RESOURCE_MISSING para price_id inexistente e 422 para TOO_MANY_LINE_ITEMS / DISCOUNT_EXCEEDS_SUBTOTAL.

Limite de taxa: 10 requisições por minuto por chave de API.

POST

api

checkout

sessions

Criar nova sessão de checkout

curl --request POST \
  --url https://besimplo.com/api/v1/checkout/sessions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "session": {
    "success_url": "https://example.com/success",
    "line_items": [
      {
        "price_id": "price_01h455vb4pex5vsknk084sn02q",
        "quantity": 1
      }
    ],
    "external_code": "CHECKOUT-SESSION-XYZ",
    "customer_id": "cus_01h455vb4pex5vsknk084sn02p",
    "customer": "<unknown>",
    "mode": "subscription",
    "return_url": "https://example.com/return",
    "metadata": [],
    "discounts": [
      {
        "type": "percentage",
        "percentage": 20,
        "cycles": 3,
        "description": "Promo Q2"
      }
    ]
  }
}
'

{
  "live_mode": true,
  "customer": {
    "id": "cus_01h455vb4pex5vsknk084sn02p"
  },
  "invoice": {
    "id": "in_01h455vb4pex5vsknk084sn02q"
  },
  "subscription": {
    "id": "sub_01h455vb4pex5vsknk084sn02s"
  },
  "amount": 9990,
  "currency": "brl",
  "url": "https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02q?session_id=cs_01h455vb4pex5vsknk084sn02q"
}

Authorizations

Authorization

string

header

required

A chave de API usada para autenticar a requisição e identificar a sua conta.

Exemplo: Authorization: ApiKey my-secure-key

Body

application/json

Dados da sessão de checkout que será criada

session

object

required

Show child attributes

Response

Operação realizada com sucesso

live_mode

boolean

required

Indica se a requisição foi feita em modo produção.

Example:

true

customer

object | null

required

Cliente vinculado à sessão. null quando customer_id/customer não foram enviados na criação — o comprador irá preencher os dados na página de checkout, e o cliente será criado nesse momento.

invoice

object | null

required

Fatura gerada para a sessão. null quando o cliente ainda não foi informado — a fatura é criada após o comprador preencher os dados na página de checkout.

amount

integer | null

required

Valor total em centavos. null quando o cliente ainda não foi informado e a fatura não foi gerada.

Example:

9990

currency

enum<string>

required

Código da moeda (ISO 4217).

Available options:

brl

Example:

"brl"

url

string<uri>

required

URL da sessão de checkout para redirecionar o cliente

Example:

"https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02q?session_id=cs_01h455vb4pex5vsknk084sn02q"

subscription

object | null

Dados da assinatura. Presente apenas quando mode é subscription e a fatura já foi criada. null quando o cliente ainda não foi informado ou quando mode é payment.

discounts

object

Descontos aplicados à sessão (presente apenas quando há descontos).

Show child attributes

Criar reembolso Fatura criada