Cobranças

Criar Cobrança Boleto

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 via boleto bancário 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
pixQR Code / Pix Copia e Cola, com pagamento na hora
boletoBoleto bancário com data de vencimento
creditcardCartão de crédito, à vista ou parcelado

Campos principais:

CampoObrig.TipoDescrição
paymentMethod✅stringMétodo de pagamento: pix, boleto ou creditcard
amount✅numberValor da cobrança, em reais
title✅stringTítulo da cobrança (2 a 100 caracteres)
description❌stringDescrição exibida ao cliente (até 500 caracteres)
dueDate❌stringData de vencimento do boleto. Formato: YYYY-MM-DD — ex: "2026-07-30". Se omitido: hoje + 30 dias.
boletoDueDays❌numberPrazo em dias até o vencimento (1 a 60) — alternativa ao dueDate
expirationAfterDueDate❌numberDias extras para pagamento após o vencimento (padrão: 30)
customer❌objectDados do cliente
customer.name❌stringNome completo
customer.documentNumber❌stringCPF (11 dígitos) ou CNPJ (14 dígitos)
customer.email❌stringE-mail
customer.phone❌stringTelefone com DDI (+55...)
customer.address✅objectObrigatório para boleto. Endereço completo do pagador
customer.address.street✅stringLogradouro
customer.address.number✅stringNúmero
customer.address.neighborhood✅stringBairro
customer.address.city✅stringCidade
customer.address.state✅stringUF (2 letras, ex: "SP")
customer.address.zipCode✅stringCEP (8 dígitos, ex: "01310100")
customer.address.complement❌stringComplemento
boletoInstructions.fine❌numberMulta por atraso em % (0.1 a 100)
boletoInstructions.interest❌numberJuros mensais por atraso em %
boletoInstructions.discount.amount❌numberValor do desconto
boletoInstructions.discount.modality❌string"fixed" (valor fixo) ou "percent" (percentual)
boletoInstructions.discount.limitDate❌stringData limite para o desconto. Formato: YYYY-MM-DD — ex: "2026-07-28". Deve ser anterior ao dueDate.
split❌arrayDivisão do valor entre contas (type, accountNumber, amount)
metadata❌objectDados adicionais de sua escolha
externalTxid❌stringIdentificador externo único da cobrança
nfConfigId❌stringConfiguração de nota fiscal a ser usada

⚠️ customer.address é obrigatório para boleto. Sem o endereço completo do pagador a emissão falhará.

Scope OAuth necessário: checkouts/write

Body

application/json

Content-Type:application/json
{
  "paymentMethod": "boleto",
  "amount": 250.0,
  "title": "Fatura de Serviços",
  "description": "Referente ao mês de janeiro",
  "dueDate": "2026-07-30",
  "boletoDueDays": 3,
  "expirationAfterDueDate": 30,
  "customer": {
    "name": "João da Silva",
    "documentNumber": "12345678901",
    "email": "joao@email.com",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "limitDate": "2026-07-28"
    }
  },
  "passFeesToCustomer": false,
  "split": [
    {
      "type": "percentage",
      "accountNumber": "123456",
      "amount": 10
    }
  ],
  "metadata": {
    "orderId": "ORD-001"
  },
  "externalTxid": "txid-externo-unico",
  "nfConfigId": null
}

Schema

FieldTypeRequiredDescription
paymentMethod
string-
-
amount
number-
-
title
string-
-
description
string-
-
dueDate
string-
-
boletoDueDays
number-
-
expirationAfterDueDate
number-
-
customer
object-
-
boletoInstructions
object-
-
passFeesToCustomer
boolean-
-
split[1]
array-
-
metadata
object-
-
externalTxid
string-
-
nfConfigId
object-
-

Headers

NameTypeValueRequired
Content-Type-application/jsonOptional
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": "boleto",
  "amount": 250.0,
  "title": "Fatura de Serviços",
  "description": "Referente ao mês de janeiro",
  "dueDate": "2026-07-30",
  "boletoDueDays": 3,
  "expirationAfterDueDate": 30,
  "customer": {
    "name": "João da Silva",
    "documentNumber": "12345678901",
    "email": "joao@email.com",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "limitDate": "2026-07-28"
    }
  },
  "passFeesToCustomer": false,
  "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 Boleto
{
  "chargeId": "cha_xxx",
  "digitableLine": "03399.09097 74000.759406 18000.011230 3 97560000025000",
  "barCode": "03393975600000250009090974000759401800001123",
  "dueDate": "2026-07-30",
  "pdfUrl": "/v1/charges/cha_xxx/boleto.pdf"
}

← Anterior

Criar Cobrança Pix

Próximo →

Criar Cobrança com Cartão