# Cobrança no cartão com split

**Área:** Split de pagamentos

Cria uma cobrança no **cartão de crédito** e divide o valor com outras contas ValidaPay. O split é aplicado na própria transação do cartão: cada recebedor recebe a parte dele **direto na conta ValidaPay dele**, no prazo de recebimento de cartão, junto com os demais recebíveis.

`POST /v1/charges/single`

**Base URL Produção:** `https://api.validapay.com.br`  
**Base URL Sandbox:** `https://sandbox.validapay.com.br`

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

**Case de uso:**

_Como plataforma com parceiros, quero vender no cartão e repassar a comissão de cada parceiro na própria venda, sem transferir depois._

## Como o valor é dividido

- **`fixed`** — o recebedor ganha exatamente o valor informado.
- **`percentage`** — incide sobre o valor da cobrança **sem a taxa repassada ao comprador**. Com `passFeesToCustomer`, o comprador paga a taxa do cartão, mas o percentual do parceiro é calculado sobre o preço (ex.: cobrança de R$ 100,00 em 3x com repasse, comprador paga R$ 107,10 e o parceiro de 10% recebe R$ 10,00).
- **A taxa do cartão sai inteira da sua conta.** Você fica com o valor líquido menos a parte dos recebedores.
- O meio centavo de arredondamento fica com a sua conta.

## Quem pode receber

O recebedor é identificado pelo **Id Público** da conta (no painel, **Gerenciamento > Minha Conta > Id Público**). No cartão ele precisa:

- ter a **mesma configuração de recebimento de cartão** que a sua conta, incluindo o **mesmo prazo de recebimento** (por exemplo, as duas em D+30);
- estar **habilitado para receber cartão** na ValidaPay. Uma conta que nunca vendeu no cartão ainda não está habilitada.

Se algum recebedor não atender, a cobrança não é criada e a API responde `400` com o motivo.

## Limite do split

A soma dos recebedores não pode passar do **valor líquido** da cobrança, já descontada a taxa do cartão. A conta usa o pior caso de parcelas que o comprador pode escolher (`maxInstallments`). Com `passFeesToCustomer`, vale a maior quantidade de parcelas **sem** repasse (`freeInstallments`).

## Pagar agora ou depois

- **Com `cardToken`:** o cartão é cobrado na hora e o split já sai aplicado.
- **Sem `cardToken`:** a cobrança fica `PENDING` e o comprador paga pelo link. O split configurado na criação é aplicado no pagamento.

Se, entre a criação e o pagamento, algum recebedor deixar de poder receber cartão, **a cobrança não é feita**: a API responde `400 SPLIT_NOT_APPLIED` com uma mensagem genérica para o comprador, e a ValidaPay é alertada. Ajuste o split e gere uma nova cobrança.

## Estorno

O **estorno total** funciona normalmente. O **estorno parcial** de uma cobrança no cartão com split pode não estar disponível: nesse caso a rota de estorno responde `400 CARD_SPLIT_PARTIAL_REFUND_UNSUPPORTED` e é preciso fazer o estorno total.

## Pix e boleto

Esta mesma rota aceita `split` com `paymentMethod` `pix` ou `boleto`. Nesses métodos o valor do recebedor é transferido para a conta dele quando o pagamento é confirmado.

> ⚠️ A rota de checkout transparente (`POST /v1/charges`) **não aceita** split no cartão nem no Pix Automático. Para cartão com split, use esta rota.

## Resposta

- **`200`** — com `cardToken` e cartão aprovado: `success: true`, `chargeId`, `status: "paid"`. Sem `cardToken`: `status: "PENDING"`, mais as opções de parcelamento.
- **`402`** — cartão recusado pelo banco: `success: false`, `status: "failed"` e o motivo em `error`.

## Erros do split

- `400 SPLIT_RECIPIENT_NOT_FOUND` — nenhum recebedor com esse Id Público
- `400 SPLIT_RECIPIENT_PROVIDER_MISMATCH` — o recebedor tem outra configuração de recebimento de cartão
- `400 SPLIT_RECIPIENT_SCHEDULE_MISMATCH` — o recebedor tem outro prazo de recebimento de cartão
- `400 SPLIT_RECIPIENT_SELLER_NOT_FOUND` — o recebedor ainda não está habilitado para receber cartão
- `400 SPLIT_RECIPIENT_SELLER_INACTIVE` — a habilitação de cartão do recebedor está inativa
- `400 SPLIT_RECIPIENT_ACCOUNT_BLOCKED` — a conta do recebedor está bloqueada
- `400 SPLIT_DUPLICATE_RECIPIENT` — o mesmo recebedor aparece mais de uma vez
- `400 SPLIT_EXCEEDS_NET_AMOUNT` — a soma dos recebedores passa do valor líquido no pior caso de parcelas
- `400 SPLIT_NOT_APPLIED` — um recebedor deixou de ser elegível antes do pagamento; a cobrança não foi feita

### Request body

```json
{
  "paymentMethod": "creditcard",
  "amount": 100.00,
  "title": "Plano anual",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "zipCode": "01310100"
    }
  },
  "cardToken": "ctk_9f8s7d6f5g4h3j2k1l0",
  "deviceId": "dev_7a6b5c4d3e2f1a0b",
  "installments": 1,
  "maxInstallments": 12,
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "split": [
    {
      "type": "percentage",
      "publicId": "3f2a1c9e-1111-4222-8333-444455556666",
      "amount": 10
    },
    {
      "type": "fixed",
      "publicId": "7b8c9d0e-2222-4333-8444-555566667777",
      "amount": 5.00
    }
  ]
}
```

### Campos do body

**Obrigatórios:** `paymentMethod`, `amount`, `title`, `customer`, `customer.name`, `customer.email`, `customer.documentNumber`, `customer.phone`, `split`, `split.type`, `split.publicId`, `split.amount`

| Campo | Descrição |
|---|---|
| `paymentMethod` | Forma de pagamento (fixo: creditcard) |
| `amount` | Valor em reais com duas casas decimais separadas por ponto |
| `title` | Título da cobrança (2 a 100 caracteres) |
| `customer` | Dados do comprador |
| `customer.name` | Nome completo |
| `customer.email` | E-mail |
| `customer.documentNumber` | CPF (11) ou CNPJ (14 dígitos) |
| `customer.phone` | Telefone do comprador |
| `split` | Recebedores do split (até 20) |
| `split.type` | percentage ou fixed |
| `split.publicId` | Id Público da conta ValidaPay que recebe |
| `split.amount` | Valor fixo em reais |

**Opcionais**

| Campo | Descrição |
|---|---|
| `customer.address` | Endereço do comprador. Recomendado: é usado na análise antifraude do cartão |
| `customer.address.street` | Rua ou logradouro |
| `customer.address.number` | Número |
| `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 |
| `cardToken` | Token do cartão gerado pelo SDK @validapay/tokenize (vale 5 min). Sem ele a cobrança fica pendente e o comprador paga pelo link |
| `deviceId` | Identificador do dispositivo gerado pelo SDK; alimenta o antifraude |
| `installments` | Parcelas desta cobrança, de 1 a 12. Default 1 |
| `maxInstallments` | Máximo de parcelas oferecido ao comprador no link de pagamento |
| `passFeesToCustomer` | Repassa a taxa do cartão ao comprador nas parcelas acima de freeInstallments |
| `freeInstallments` | Parcelas em que a taxa não é repassada. Default 1 |

### Resposta 200: 200 - cartão aprovado

```json
{
  "success": true,
  "customerId": "cus_1791478518377_ddakgbap7",
  "chargeId": "cha_1791483206720_or87nbs4f",
  "status": "paid"
}
```


### Resposta 400: 400 - recebedor com outro prazo de recebimento

```json
{
  "error": {
    "message": "O recebedor PARCEIRO LTDA não pode receber split no cartão: tem prazo de recebimento de cartão diferente",
    "code": "SPLIT_RECIPIENT_SCHEDULE_MISMATCH"
  }
}
```


---

Página: https://docs.validapay.com.br/referencia/post-cobranca-no-cartao-com-split  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json