# 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",  
    "metadata": { "origem": "site" },
    "phone": "+5511999998888",  
    "cep": "01310100",
    "address": {
      "type": "BILLING",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "amount": 10.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1,
      "isOrderBump": false
    }
  ],
  "billingDay": 15,
  "pixInstructions": {
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "limitDate": "2026-07-28",
      "daysBeforeDue": 3
    }
  },
  "expiration": "2026-07-30",
  "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",
      "amount": 10.0,
      "couponCode": "PROMO10",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "tokenId": "tok_abc123",
  "cartId": "cart_2026_0001",
  "productId": "prod_123456_example"
}
```

### Campos do body

**Obrigatórios:** `paymentMethod`, `customer`, `customer.name`, `customer.email`, `customer.documentNumber`, `items`, `items.priceId`, `pixInstructions.discount.amount`, `pixInstructions.discount.modality`, `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) |
| `pixInstructions.discount.amount` | Valor do desconto, sempre maior que zero |
| `pixInstructions.discount.modality` | fixed desconta em reais, percent desconta em porcentagem |
| `discounts.type` | Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais |
| `discounts.value` | Percentual de 0 a 100 quando type é 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.metadata` | Objeto livre guardado junto do cadastro do comprador |
| `customer.phone` | Telefone |
| `customer.cep` | CEP do pagador, só números. Com expiration preenchido, identifica o devedor no Pix com vencimento |
| `customer.address` | Endereço do comprador. Obrigatório quando nfConfigId emite nota fiscal |
| `customer.address.type` | BILLING para cobrança, SHIPPING para entrega (default BILLING) |
| `customer.address.street` | Rua ou logradouro |
| `customer.address.number` | Número |
| `customer.address.complement` | Complemento |
| `customer.address.neighborhood` | Bairro |
| `customer.address.city` | Cidade |
| `customer.address.state` | UF com 2 letras |
| `customer.address.zipCode` | CEP com 8 dígitos, só números |
| `customer.address.country` | Pais (default BR) |
| `customer.address.cityCode` | Código IBGE do município; a nota fiscal exige e o backend resolve pelo CEP quando ausente |
| `amount` | Valor total em reais (alternativa a items; use um ou outro) (mín.: 0.01) |
| `items.quantity` | Quantidade (default 1) |
| `items.isOrderBump` | Marca o item como oferta adicional aceita no checkout |
| `billingDay` | Dia do mês das cobranças seguintes (1 a 31) |
| `pixInstructions` | Desconto por antecipação no Pix com vencimento |
| `pixInstructions.discount` | Exige amount e modality, mais limitDate ou daysBeforeDue (apenas um dos dois) |
| `pixInstructions.discount.limitDate` | Último dia com desconto (YYYY-MM-DD), para cobrança avulsa |
| `pixInstructions.discount.daysBeforeDue` | Dias antes do vencimento em que o desconto vale, para assinatura. Use limitDate ou daysBeforeDue, nunca os dois |
| `expiration` | Vencimento do Pix (YYYY-MM-DD). Preenchido, gera um Pix com vencimento (COBV) |
| `couponCode` | Código de cupom de desconto |
| `metadata` | Objeto livre, aceita as chaves e valores que você quiser ("referência" é só exemplo); salvo na cobrança |
| `description` | Descrição livre da cobrança |
| `split` | Divisão do valor. Não suportado em creditcard nem pix_automatico |
| `installments` | Parcelas no cartão, de 1 a 12 |
| `freeInstallments` | Parcelas sem juros para o comprador, de 0 a 12 |
| `passFeesToCustomer` | Repassa a taxa de parcelamento ao comprador |
| `allowedPaymentMethods` | Métodos aceitos quando a cobrança vira link |
| `nfConfigId` | Emite nota fiscal com esta configuração. Exige customer.address |
| `notifications` | E-mails disparados nesta cobrança |
| `discounts` | Descontos aplicados a cobrança |
| `discounts.paymentMethod` | Aplica o desconto só neste método de pagamento. O campo method e aceito como sinonimo |
| `discounts.amount` | Alternativa a value; informe amount ou value, nunca nenhum dos dois |
| `discounts.couponCode` | Cupom que originou este desconto |
| `discounts.fromCycle` | Primeiro ciclo em que o desconto vale, em cobranças recorrentes |
| `discounts.toCycle` | Último ciclo; null mantem o desconto até o fim da assinatura |
| `discounts.durationMonths` | Alternativa a toCycle: por quantos meses o desconto vale |
| `tokenId` | Alternativa a card e a paymentMethodId no cartão |
| `cartId` | Agrupa numa única compra as assinaturas criadas juntas e deduplica o evento de conversão |
| `productId` | Cria a cobrança a partir de um produto |

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