Cobranças

Criar Cobrança Pix

POST/v1/charges

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

Cria uma cobrança Pix para seu cliente.

Criar cobrança

Cria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo paymentMethod — escolha entre Pix, boleto ou cartão de crédito.

Autenticação: token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho X-Sub-Account.

Métodos de pagamento disponíveis:

Método (`paymentMethod`)	Como o cliente paga
`pix`	QR Code / Pix Copia e Cola, com pagamento na hora
`boleto`	Boleto bancário com data de vencimento
`creditcard`	Cartão de crédito, à vista ou parcelado

Campos principais:

Campo	Obrig.	Tipo	Descrição
`paymentMethod`	✅	string	Método de pagamento: `pix`, `boleto` ou `creditcard`
`amount`	✅	number	Valor da cobrança, em reais
`title`	✅	string	Título da cobrança (2 a 100 caracteres)
`description`	❌	string	Descrição exibida ao cliente (até 500 caracteres)
`expiration`	❌	string	Prazo máximo de pagamento após o vencimento. Formato: `YYYY-MM-DD` — ex: `"2026-12-31"`. Se omitido: sem expiração. Deve ser posterior a `dueDate` quando ambos forem informados.
`dueDate`	❌	string	Data de vencimento do Pix (sem juros até essa data). Formato: `YYYY-MM-DD` — ex: `"2026-12-01"`. Se omitido: hoje + 30 dias.
`boletoDueDays`	❌	number	Prazo do boleto em dias (1 a 60) — alternativa ao `dueDate`
`customer`	❌	object	Dados do cliente (nome, documento, e-mail, telefone)
`customer.address`	❌	object	Endereço do cliente — obrigatório para boleto
`boletoInstructions.fine`	❌	number	Multa por atraso, em % (0.1 a 100)
`boletoInstructions.interest`	❌	number	Juros mensais por atraso, em %
`boletoInstructions.discount`	❌	object	Desconto: `amount`, `modality` (`fixed`/`percent`) e `limitDate` (formato `YYYY-MM-DD`, deve ser anterior ao `dueDate`)
`card`	✅*	object	Dados do cartão (número, CVV, nome, validade no formato `MM/YYYY` — ex: `"12/2027"`) — obrigatório para cartão
`tokenId`	❌	string	Token de um cartão já salvo (alternativa a `card`)
`installments`	❌	number	Número de parcelas (1 a 12, padrão 1)
`passFeesToCustomer`	❌	boolean	Repassa as taxas ao cliente
`freeInstallments`	❌	number	Parcelas sem juros (1 a 12, padrão 1)
`split`	❌	array	Divisão do valor entre contas (`type`, `accountNumber`, `amount`)
`metadata`	❌	object	Dados adicionais de sua escolha
`externalTxid`	❌	string	Identificador externo único da cobrança
`nfConfigId`	❌	string	Configuração de nota fiscal a ser usada

Os campos marcados com * são obrigatórios conforme o método de pagamento escolhido.

⚠️ Relação entre dueDate e expiration:

dueDate = data até a qual o cliente paga sem juros/multa
expiration = prazo máximo para pagamento após o vencimento (com juros/multa se configurados)
Regra: expiration deve ser uma data posterior a dueDate
Se expiration for omitido, o padrão é dueDate + 30 dias

Exemplo com ambos os campos:

{
  "paymentMethod": "pix",
  "amount": 100.0,
  "title": "Mensalidade Junho",
  "dueDate": "2026-07-01",
  "expiration": "2026-07-31"
}

Scope OAuth necessário: pix.cob/write

Body

application/json

Content-Type:application/json

{
  "paymentMethod": "pix",

  "amount": 100.0,
  "title": "Cobrança PIX",
  "description": "Referente ao pedido #001",
  "expiration": "2026-12-31",

  "customer": {
    "documentNumber": "12345678901",
    "name": "João da Silva",
    "email": "joao@email.com",
    "phone": "+5511999998888",
    "cep": "01310100"
  },

  "passFeesToCustomer": false,
  "installments": 1,
  "freeInstallments": 1,

  "split": [
    {
      "type": "percentage",
      "accountNumber": "123456",
      "amount": 10
    }
  ],

  "metadata": {
    "orderId": "ORD-001"
  },
  "externalTxid": "txid-externo-unico",
  "nfConfigId": null
}

Schema

Field	Type	Required	Description
paymentMethod	string	-	-
amount	number	-	-
title	string	-	-
description	string	-	-
expiration	string	-	-
customer	object	-	-
passFeesToCustomer	boolean	-	-
installments	number	-	-
freeInstallments	number	-	-
split[1]	array	-	-
metadata	object	-	-
externalTxid	string	-	-
nfConfigId	object	-	-

Headers

Name	Type	Value	Required
Content-Type	-	application/json	Optional

← Anterior

Validar Cupom

Criar Cobrança Boleto

const url = 'https://sandbox.validapay.com.br/v1/charges';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "paymentMethod": "pix",

  "amount": 100.0,
  "title": "Cobrança PIX",
  "description": "Referente ao pedido #001",
  "expiration": "2026-12-31",

  "customer": {
    "documentNumber": "12345678901",
    "name": "João da Silva",
    "email": "joao@email.com",
    "phone": "+5511999998888",
    "cep": "01310100"
  },

  "passFeesToCustomer": false,
  "installments": 1,
  "freeInstallments": 1,

  "split": [
    {
      "type": "percentage",
      "accountNumber": "123456",
      "amount": 10
    }
  ],

  "metadata": {
    "orderId": "ORD-001"
  },
  "externalTxid": "txid-externo-unico",
  "nfConfigId": null
})
};

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

Response Examples

200200 PIX

{
  "chargeId": "cha_xxx",
  "emv": "00020126580014...",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "metadata": {}
}

400400 split

{
  "code": "SPLIT_EXCEEDS_NET_AMOUNT"
}

404404 chave

{
  "code": "PIX_KEY_NOT_FOUND"
}

← Anterior

Validar Cupom

Criar Cobrança Boleto