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

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

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

Envie os dados do comprador e os itens da compra. A resposta traz o código `emv` (copia e cola) e o QR Code para pagamento.

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.pix.generated` (envia o QR Code ao comprador assim que a cobrança é criada), `oneoff.payment.success` (confirmação ao comprador quando o Pix 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).

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`.

### Emitindo nota fiscal na cobrança

Envie `nfConfigId` com o identificador de uma configuração fiscal criada em `POST /v1/invoices/notas/config`. Com ele presente:

- `customer.address` passa a ser **obrigatório** — a nota precisa do endereço do tomador. Sem ele: `400 INVALID_DATA`.
- O momento da emissão vem da configuração, não da cobrança: `invoiceTiming` aceita `IMMEDIATE` (padrão), `AFTER_CONFIRMATION` e `DAYS_AFTER_CONFIRMATION`; neste último, `daysAfterConfirmation` define em quantos dias (padrão 1).
- O `cityCode` (IBGE) do endereço é resolvido a partir do CEP e é necessário para a NFS-e.

O mesmo campo existe em produtos (`POST /v1/products`) e nas configurações de assinatura, para emitir nota a cada ciclo sem repetir o `nfConfigId` em cada cobrança.

### Request body

```json
{
  "paymentMethod": "pix",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "+5511999998888",
    "cep": "01310100"
  },
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "expiration": "2026-07-30",
  "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`, `items.priceId`, `discounts.type`, `discounts.value`

| Campo | Descrição |
|---|---|
| `paymentMethod` | Forma de pagamento (fixo: pix) |
| `customer` | Dados do comprador |
| `customer.name` | Nome completo |
| `customer.email` | E-mail |
| `customer.documentNumber` | CPF (11) ou CNPJ (14 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.cep` | CEP (necessário para PIX com dados do pagador) |
| `items` | Produtos da compra (ou use amount para cobrança avulsa) |
| `items.quantity` | Quantidade (default 1) |
| `expiration` | Expiração do QR Code PIX (YYYY-MM-DD) |
| `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",
  "pix": {
    "emv": "00020126330014br.gov.bcb.pix...5204000053039865802BR6304ABCD",
    "qrCode": "data:image/png;base64,iVBORw0KGgo..."
  }
}
```

### 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-pix
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json