# Criar sessão de pagamento
`POST /v1/checkout-sessions`
**Área:** Links de pagamento

**Scopes necessários:** `checkouts/write`

Cria um acesso temporário e seguro a uma página de pagamento, com cliente e configurações pré-preenchidos. É de uso único: expira após o pagamento.

Informe o `priceId` de um preço já cadastrado. Opcionalmente, envie os dados do cliente, restrinja as formas de pagamento e personalize a aparência.

A resposta inclui o `id` da sessão e a `url` de pagamento hospedada pela ValidaPay.

Formas de pagamento aceitas em `allowedPaymentMethods`: pix, creditcard, boleto e pix_automatico. O **Pix Automático** está disponível apenas para **contas PJ** (conta ValidaPay cadastrada com CNPJ) e exige um preço recorrente (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY): o cliente autoriza a recorrência uma única vez no aplicativo do banco e os ciclos seguintes são debitados automaticamente. Enquanto a autorização não é confirmada pelo banco do pagador, a assinatura fica com status `PENDING`. O valor mínimo por cobrança é de **R$ 4,99**.

Erros: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF) e `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo).

Ao informar `termsOfServiceUrl` e/ou `privacyPolicyUrl`, o checkout exibe um aceite obrigatório com os links: o cliente só consegue finalizar a compra depois de marcar que leu e concorda. O texto do aceite se adapta a um ou aos dois links. Sem esses campos, nenhum aceite é exibido.

Case de uso:

_Como SaaS, quero gerar um link de pagamento nominal para cada cliente no momento da contratação, com uso único para evitar cobranças duplicadas._

### Request body

```json
{
  "priceId": "price_abc123",
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto",
    "pix_automatico"
  ],
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "51999999999",
    "address": {
      "type": "BILLING",
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 4",
      "neighborhood": "Centro",
      "city": "Porto Alegre",
      "state": "RS",
      "zipCode": "90010000",
      "country": "BR",
      "cityCode": "4314902"
    }
  },
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "billingDay": 15,
  "prorataStartDate": "2026-06-11",
  "installments": 1,
  "dueDate": "2026-07-30",
  "boletoDueDays": 7,
  "expirationAfterDueDate": 30,
  "discounts": [
    {
      "type": "PERCENTAGE",
      "value": 10,
      "paymentMethod": "pix",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "maxInstallments": 12,
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.00,
      "modality": "fixed",
      "limitDate": "2026-07-28"
    }
  },
  "orderBumps": [
    {
      "priceId": "price_bump123",
      "callToAction": "Adicionar ao pedido",
      "title": "Produto adicional",
      "description": "Descrição do order bump",
      "showImage": true
    }
  ],
  "primaryColor": "#6366f1",
  "secondaryColor": "#818cf8",
  "fontColor": "#ffffff",
  "companyName": "Minha Empresa",
  "successUrl": "https://meusite.com/sucesso",
  "failureUrl": "https://meusite.com/falha",
  "termsOfServiceUrl": "https://meusite.com/termos-de-servico",
  "privacyPolicyUrl": "https://meusite.com/politica-de-privacidade",
  "metadata": { "referencia": "pedido-001" }
}
```

### Campos do body

**Obrigatórios:** `priceId`, `items.priceId`, `discounts.type`, `discounts.value`, `orderBumps.priceId`

| Campo | Descrição |
|---|---|
| `priceId` | Preço da sessão (deve começar com price_) |
| `items.priceId` | priceId do item |
| `discounts.type` | PERCENTAGE ou FIXED |
| `discounts.value` | Valor do desconto |
| `orderBumps.priceId` | priceId do produto adicional |

**Opcionais**

| Campo | Descrição |
|---|---|
| `allowedPaymentMethods` | Métodos exibidos: pix, creditcard, boleto, pix_automatico (só conta PJ; omitir usa o padrão do price) |
| `customer` | Pré-preenche os dados do cliente no checkout |
| `customer.name` | Nome exibido |
| `customer.email` | Usado para localizar cliente existente |
| `customer.documentNumber` | CPF (11) ou CNPJ (14 dígitos) |
| `customer.phone` | Telefone |
| `customer.address` | Endereço (obrigatório para boleto no pagamento) |
| `customer.address.type` | Tipo do endereço |
| `customer.address.street` |  |
| `customer.address.number` |  |
| `customer.address.complement` |  |
| `customer.address.neighborhood` |  |
| `customer.address.city` |  |
| `customer.address.state` |  |
| `customer.address.zipCode` |  |
| `customer.address.country` |  |
| `customer.address.cityCode` | Código IBGE (necessário para nota fiscal) |
| `items` | Lista de { priceId, quantity } (sobrescreve o item principal) |
| `items.quantity` | Quantidade (default 1) |
| `billingDay` | Dia do mês das cobranças recorrentes (1 a 31) |
| `prorataStartDate` | Início do cálculo de pró-rata (YYYY-MM-DD) |
| `installments` | Parcelas fixas da sessão (1 a 12) |
| `dueDate` | Vencimento do boleto (YYYY-MM-DD, maior que hoje) |
| `boletoDueDays` | Dias até o vencimento (mín. 1; ignorado se dueDate informado) |
| `expirationAfterDueDate` | Dias após o vencimento que o boleto aceita pagamento (0 a 60) |
| `discounts` | Descontos aplicados à sessão |
| `discounts.paymentMethod` | Restringe a um método |
| `discounts.fromCycle` | Ciclo inicial |
| `discounts.toCycle` | Ciclo final |
| `discounts.durationMonths` | Duração em meses |
| `passFeesToCustomer` | Repassa as taxas ao cliente (default false) |
| `freeInstallments` | Parcelas sem juros (1 a 12, default 1) |
| `maxInstallments` | Limite máximo de parcelas exibido (1 a 12) |
| `boletoInstructions` | Regras de multa/juros/desconto do boleto |
| `boletoInstructions.fine` | Multa em % (0.1 a 100; fine + interest <= 60) |
| `boletoInstructions.interest` | Juros mensais em % (0.1 a 100) |
| `boletoInstructions.discount` | Desconto antecipado |
| `boletoInstructions.discount.amount` | Valor do desconto |
| `boletoInstructions.discount.modality` | fixed (R$) ou percent (%) |
| `boletoInstructions.discount.limitDate` | Data limite (antes de dueDate) |
| `orderBumps` | Produtos adicionais exibidos no checkout |
| `orderBumps.callToAction` | Texto do botão |
| `orderBumps.title` | Título exibido |
| `orderBumps.description` | Descrição exibida |
| `orderBumps.showImage` | Exibir imagem |
| `primaryColor` | Cor primária em hex |
| `secondaryColor` | Cor secundária em hex |
| `fontColor` | Cor do texto em hex |
| `companyName` | Nome da empresa exibido no checkout |
| `successUrl` | Redireciona após pagamento aprovado |
| `failureUrl` | Redireciona após pagamento recusado |
| `termsOfServiceUrl` | Termos de serviço exibidos no checkout para aceite do cliente |
| `privacyPolicyUrl` | Política de privacidade exibida no checkout para aceite do cliente |

### Resposta 200 — 200

```json
{
  "id": "cs_abc123",
  "url": "https://app.validapay.com.br/pagamento/cs_abc123",
  "priceId": "price_abc123"
}
```

### Resposta 400 — 400

```json
{
  "error": {
    "code": "INVALID_DATA",
    "message": "Campo inválido",
    "details": []
  }
}
```

### Resposta 401 — 401

```json
{
    "error": {
        "message": "Você não tem permissão para usar este produto",
        "code": "FORBIDDEN",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

### Resposta 404 — 404

```json
{
    "error": {
        "message": "Preço não encontrado",
        "code": "PRICE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/post-criar-sessao-de-pagamento
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json