# Gerar cobrança Pix Automático
`POST /v1/charges`
**Área:** Checkout Transparente

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

Inicia uma assinatura com **Pix Automático** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.

A resposta traz `pix.emv` (copia e cola) e `pix.recurrencyId`.

Enquanto o banco do pagador não confirma a autorização, a assinatura fica com status `PENDING`.

Requisitos:

- conta ValidaPay cadastrada como **PJ** (CNPJ)
- `items` com preço **recorrente** (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY); não use `amount` avulso
- valor mínimo de **R$ 4,99** por cobrança

Notificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `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: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF), `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo), `409 DUPLICATE_CHARGE` (externalId já utilizado) e `404 PRICE_NOT_FOUND` (preço inexistente).

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": "pix_automatico",
  "externalId": "assinatura-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "+5511999998888"
  },
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "billingDay": 15,
  "couponCode": "PROMO10",
  "metadata": { "referencia": "assinatura-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", "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`, `items.priceId`, `discounts.type`, `discounts.value`

| Campo | Descrição |
|---|---|
| `paymentMethod` | Forma de pagamento (fixo: pix_automatico) |
| `customer` | Dados do comprador |
| `customer.name` | Nome completo |
| `customer.email` | E-mail |
| `customer.documentNumber` | CPF (11) ou CNPJ (14 dígitos) |
| `items` | Itens da assinatura; o preço precisa ser recorrente |
| `items.priceId` | ID do preço recorrente (valor mínimo de R$ 4,99) |
| `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 |
| `items.quantity` | Quantidade (default 1) |
| `billingDay` | Dia do mês das cobranças seguintes (1 a 31) |
| `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",
    "recurrencyId": "RN1234567890abcdef"
  }
}
```

### Resposta 400 — 400 PIX_AUTOMATICO_PJ_ONLY

```json
{
  "error": {
    "message": "Pix Automático está disponível apenas para contas PJ",
    "code": "PIX_AUTOMATICO_PJ_ONLY"
  }
}
```

### Resposta 400 — 400 PIX_AUTOMATICO_MIN_AMOUNT

```json
{
  "error": {
    "message": "Pix Automático exige valor mínimo de R$ 4,99",
    "code": "PIX_AUTOMATICO_MIN_AMOUNT"
  }
}
```

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