# Gerar cobrança Boleto
`POST /v1/charges`
**Área:** Checkout Transparente

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

Gera uma cobrança via **boleto** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.

Para boleto, o **endereço completo do comprador é obrigatório**. Você pode personalizar vencimento, multa, juros e desconto por meio de `boletoInstructions`.

Produto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.

Notificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.boleto.generated` (envia o boleto ao comprador assim que a cobrança é criada), `oneoff.payment.success` (confirmação ao comprador quando o boleto compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.

> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.

Erros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `404 PRICE_NOT_FOUND` (preço inexistente) e `400 INVALID_DATA` (campo inválido — inclui endereço ausente).

Use `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.

**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.

### Request body

```json
{
  "paymentMethod": "boleto",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "dueDate": "2026-07-30",
  "boletoDueDays": 7,
  "expirationAfterDueDate": 30,
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "limitDate": "2026-07-28"
    }
  },
  "couponCode": "PROMO10",
  "metadata": { "referencia": "pedido-001" },
  "description": "Assinatura Premium",
  "split": [
    { "type": "fixed", "accountNumber": "896532569", "amount": 0.10 }
  ],
  "installments": 1,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "allowedPaymentMethods": ["pix", "creditcard"],
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "notifications": ["oneoff.pix.generated", "oneoff.payment.success", "new.sale"],
  "discounts": [
    {
      "type": "percentage",
      "value": 10,
      "paymentMethod": "pix",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "tokenId": "tok_abc123",
  "productId": "prod_123456_example",
  "recurrencyStartDate": "2026-10-01",
  "prorataStartDate": "2026-09-15",
  "prorataDueDate": "2026-09-20",
  "mergeWithNextCycle": false
}
```

### Campos do body

**Obrigatórios:** `paymentMethod`, `customer`, `customer.name`, `customer.email`, `customer.documentNumber`, `customer.address`, `customer.address.street`, `customer.address.number`, `customer.address.neighborhood`, `customer.address.city`, `customer.address.state`, `customer.address.zipCode`, `items.priceId`, `discounts.type`, `discounts.value`

| Campo | Descrição |
|---|---|
| `paymentMethod` | Forma de pagamento (fixo: boleto) |
| `customer` | Dados do comprador |
| `customer.name` | Nome completo |
| `customer.email` | E-mail |
| `customer.documentNumber` | CPF (11) ou CNPJ (14 dígitos) |
| `customer.address` | Endereço do comprador (obrigatório para boleto) |
| `customer.address.street` | Rua ou logradouro |
| `customer.address.number` | Número |
| `customer.address.neighborhood` | Bairro |
| `customer.address.city` | Cidade |
| `customer.address.state` | UF com 2 letras |
| `customer.address.zipCode` | CEP com 8 dígitos |
| `items.priceId` | ID do preço do produto |
| `discounts.type` | Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais |
| `discounts.value` | Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed |

**Opcionais**

| Campo | Descrição |
|---|---|
| `externalId` | Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada) |
| `externalTxid` | Identifica a loja, o caixa ou o vendedor responsável pela cobrança |
| `customer.phone` | Telefone |
| `customer.address.complement` | Complemento |
| `customer.address.country` | País (default BR) |
| `customer.address.cityCode` | Código IBGE (necessário para nota fiscal) |
| `items` | Produtos da compra (ou use amount para cobrança avulsa) |
| `items.quantity` | Quantidade (default 1) |
| `dueDate` | Vencimento do boleto (YYYY-MM-DD, maior que hoje) |
| `boletoDueDays` | Dias até o vencimento (mín. 1; ignorado se dueDate informado) |
| `expirationAfterDueDate` | Dias para cancelar o boleto após o vencimento (0 a 60) |
| `boletoInstructions` | Regras de multa/juros/desconto do boleto |
| `boletoInstructions.fine` | Multa por atraso em % (0.1 a 100; fine + interest <= 60) |
| `boletoInstructions.interest` | Juros mensais por atraso em % (0.1 a 100) |
| `boletoInstructions.discount` | Desconto para pagamento antecipado |
| `boletoInstructions.discount.amount` | Valor do desconto |
| `boletoInstructions.discount.modality` | fixed (R$) ou percent (%) |
| `boletoInstructions.discount.limitDate` | Data limite do desconto (antes de dueDate) |
| `couponCode` | Código de cupom de desconto |
| `description` | Descricao livre da cobranca |
| `split` | Divisao do valor. Nao suportado em creditcard nem pix_automatico |
| `installments` | Parcelas no cartao, de 1 a 12 |
| `freeInstallments` | Parcelas sem juros para o comprador, de 0 a 12 |
| `passFeesToCustomer` | Repassa a taxa de parcelamento ao comprador |
| `nfConfigId` | Emite nota fiscal com esta configuracao. Exige customer.address |
| `discounts` | Descontos aplicados a cobranca |
| `discounts.paymentMethod` | Aplica o desconto so neste metodo de pagamento |
| `discounts.fromCycle` | Primeiro ciclo em que o desconto vale, em cobrancas recorrentes |
| `discounts.toCycle` | Ultimo ciclo; null mantem o desconto ate o fim da assinatura |
| `discounts.durationMonths` | Alternativa a toCycle: por quantos meses o desconto vale |
| `tokenId` | Alternativa a card e a paymentMethodId no cartao |
| `productId` | Cria a cobranca a partir de um produto |
| `recurrencyStartDate` | Primeira cobranca da recorrencia (YYYY-MM-DD) |
| `prorataStartDate` | Inicio do calculo pro rata |
| `prorataDueDate` | Vencimento da cobranca pro rata (YYYY-MM-DD) |
| `mergeWithNextCycle` | Junta a pro rata com o proximo ciclo em vez de cobrar agora |

### Resposta 200 — 200

```json
{
  "success": true,
  "customerId": "cus_xxx",
  "chargeId": "cha_abc123",
  "boleto": {
    "digitableLine": "23793.38128 60007.827136 95000.063305 9 84410000010000",
    "barCode": "23799844100000100003381260007827139500006330",
    "dueDate": "2026-07-30",
    "pdfUrl": "https://app.validapay.com.br/boletos/cha_abc123.pdf"
  }
}
```

### Resposta 404 — 404 PRICE_NOT_FOUND

```json
{
  "error": {
    "message": "Preço não encontrado",
    "code": "PRICE_NOT_FOUND"
  }
}
```

### Resposta 409 — 409 DUPLICATE_CHARGE

```json
{
  "error": {
    "message": "Cobrança duplicada: já existe uma cobrança para este pedido",
    "code": "DUPLICATE_CHARGE",
    "details": {
      "chargeId": "cha_1784065113577_5dw2oyfic"
    },
    "timestamp": "2026-07-14T21:39:36.322Z"
  }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/post-gerar-cobranca-boleto
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json