Dashboard

Split de pagamentos

Cobrança no cartão com split

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

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

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

charges/write

Body

application/json

Content-Type:application/json
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
    }
  ]
}

Schema

paymentMethodstringobrigatório
Forma de pagamento (fixo: creditcard)
Valores aceitos:pixcreditcardboletopix_automatico
amountnumberobrigatório
Valor em reais com duas casas decimais separadas por ponto
titlestringobrigatório
Título da cobrança (2 a 100 caracteres)
customerobjectobrigatório
Dados do comprador
splitarray[2]obrigatório
Recebedores do split (até 20)
cardTokenstringopcional
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
deviceIdstringopcional
Identificador do dispositivo gerado pelo SDK; alimenta o antifraude
installmentsnumberopcional
Parcelas desta cobrança, de 1 a 12. Default 1
Regra:1 a 12
maxInstallmentsnumberopcional
Máximo de parcelas oferecido ao comprador no link de pagamento
Regra:1 a 12
passFeesToCustomerbooleanopcional
Repassa a taxa do cartão ao comprador nas parcelas acima de freeInstallments
freeInstallmentsnumberopcional
Parcelas em que a taxa não é repassada. Default 1
Regra:0 a 12
const url = 'https://sandbox.validapay.com.br/v1/charges/single';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "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
    }
  ]
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200cartão aprovado▾
JSON
{
  "success": true,
  "customerId": "cus_1791478518377_ddakgbap7",
  "chargeId": "cha_1791483206720_or87nbs4f",
  "status": "paid"
}
400recebedor 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"
  }
}

← Anterior

Split para Conta Master

Próximo →

Criar subconta PF