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

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

Gera uma cobrança via **cartão de crédito** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.

Envie os dados do cartão no objeto `card` (dados brutos) ou use `paymentMethodId`/`tokenId` de um cartão tokenizado. É possível parcelar (`installments`) e repassar as taxas ao comprador.

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.payment.success` (confirmação ao comprador quando o cartão é aprovado), `oneoff.payment.failed` (aviso ao comprador quando o cartão é recusado) 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), `402` (pagamento recusado pelo banco), `400 MISSING_CARD_DATA` (faltam dados do cartão) e `404 PRICE_NOT_FOUND` (preço inexistente).

**Cartões de teste (sandbox):** em conta de sandbox nenhuma cobrança chega ao adquirente — o número do cartão é que define o resultado:

- `4111111111111111` — pagamento aprovado
- `4000000000000002` — recusado pela operadora (`card_declined`)
- `4000000000000004` — saldo insuficiente (`insufficient_funds`)
- `4000000000000006` — cartão expirado (`expired_card`)
- `4000000000000008` — CVV inválido (`invalid_cvv`)
- `4000000000000010` — suspeita de fraude (`fraud_suspected`)

Qualquer outro número de 16 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. Em produção o número não muda nada: quem decide é o emissor do cartão.

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": "creditcard",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "+5511999998888"
  },
  "card": {
    "number": "4111111111111111",
    "cvv": "123",
    "name": "JOAO DA SILVA",
    "expiration": "12/2027"
  },
  "paymentMethodId": "pm_abc123",
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "installments": 1,
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "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`, `card`, `card.number`, `card.cvv`, `card.name`, `card.expiration`, `items.priceId`, `discounts.type`, `discounts.value`

| Campo | Descrição |
|---|---|
| `paymentMethod` | Forma de pagamento (fixo: creditcard) |
| `customer` | Dados do comprador |
| `customer.name` | Nome completo |
| `customer.email` | E-mail |
| `customer.documentNumber` | CPF (11) ou CNPJ (14 dígitos) |
| `card` | Dados do cartão (ou use paymentMethodId/tokenId de um cartão salvo) |
| `card.number` | Número do cartão (13 a 19 dígitos) |
| `card.cvv` | Código de segurança (3 ou 4 dígitos) |
| `card.name` | Nome como está no cartão |
| `card.expiration` | Validade no formato MM/YYYY |
| `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 |
| `paymentMethodId` | Cartão tokenizado (alternativa ao objeto card) |
| `items` | Produtos da compra (ou use amount para cobrança avulsa) |
| `items.quantity` | Quantidade (default 1) |
| `installments` | Parcelas no cartao, de 1 a 12 |
| `passFeesToCustomer` | Repassa a taxa de parcelamento ao comprador |
| `freeInstallments` | Parcelas sem juros para o comprador, de 0 a 12 |
| `couponCode` | Código de cupom de desconto |
| `description` | Descricao livre da cobranca |
| `split` | Divisao do valor. Nao suportado em creditcard nem pix_automatico |
| `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",
  "status": "paid"
}
```

### Resposta 402 — 402

```json
{
    "success": false,
    "chargeId": "cha_1784065113577_5dw2oyfic",
    "status": "failed",
    "error": "Cartão recusado"
}
```

### Resposta 400 — 400 MISSING_CARD_DATA

```json
{
  "error": {
    "message": "tokenId, card ou paymentMethodId é obrigatório",
    "code": "MISSING_CARD_DATA"
  }
}
```

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