# Cobrança imediata
`POST /v1/charges/pix`
**Área:** Pix

**Scopes necessários:** `pix.cob/write`

Com esta funcionalidade você pode criar um QR Code de cobrança imediata.

**Case de uso:**

_Como SaaS, quero gerar cobranças preenchendo apenas o valor do produto e nada mais_

**Regras condicionais (COBV):** `name` e `cep` do `customer` só são aceitos junto com `expiration`. Havendo `expiration` e `customer`, o trio `documentNumber`, `name` e `cep` passa a ser obrigatório em bloco.

**Resposta:** os campos vêm na raiz — `emv` e `qrCode`, não aninhados sob `pix`. O `qrCode` já é uma data URL PNG pronta para exibir; não é preciso gerar a imagem no seu lado.

**Correlação com o pedido:** envie `metadata` na criação e ele volta na resposta e no payload do webhook `payment.success`. É a forma recomendada de amarrar o pagamento ao seu pedido.

> ⚠️ **Esta rota não tem idempotência.** `externalId` é aceito e descartado; duas chamadas iguais criam **duas cobranças**. Controle duplicidade no seu lado (índice `pedido → cobrança`) ou use `POST /v1/charges`, que responde `409 DUPLICATE_CHARGE`. O campo `externalTxid` documentado aqui identifica loja, caixa ou vendedor — não serve como chave de idempotência.

### Request body

```json
{
  "amount": 10.00,
  "paymentMethod": "pix",
  "expiration": "2026-12-31",
  "externalTxid": "loja-01-caixa-03",
  "metadata": { "orderId": "pedido-1001" },
  "customer": {
    "documentNumber": "12345678901",
    "name": "Joao da Silva",
    "cep": "01310100",
    "phone": "+5511999998888",
    "email": "joao@email.com"
  },
  "split": [
    {
      "type": "fixed",
      "accountNumber": "896532569",
      "amount": 0.10
    }
  ]
}
```

### Campos do body

**Obrigatórios:** `amount`, `split.type`, `split.amount`

| Campo | Descrição |
|---|---|
| `amount` | Valor em reais, nunca em centavos (mín.: 0.01) |
| `split.type` | Tipo da divisao (valores: percentage, fixed) |
| `split.amount` | Valor em reais quando fixed; percentual de 0 a 100 quando percentage (mín.: 0.01) |

**Opcionais**

| Campo | Descrição |
|---|---|
| `paymentMethod` | Fixo "pix"; o padrao ja e pix (valores: pix) |
| `expiration` | Vencimento (COBV). Nao aceita data passada |
| `externalTxid` | Identifica loja, caixa ou vendedor |
| `customer` | Dados do pagador. Com expiration, vira COBV |
| `customer.documentNumber` | CPF ou CNPJ do pagador |
| `customer.name` | Exige expiration (COBV) |
| `customer.cep` | Exige expiration (COBV) |
| `customer.phone` | Telefone no formato E.164 |
| `customer.email` | E-mail do pagador |
| `split` | Divisao do valor entre recebedores |
| `split.accountNumber` | Conta do recebedor; ou informe publicId |

### Resposta 200 — 200

```json
{
    "chargeId": "cha_1771511282731_9p1wo3tql",
    "emv": "00020101021226910014br.gov.bcb.pix…",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "metadata": {
        "orderId": "pedido-1001"
    }
}
```

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