Dashboard

Checkout Transparente

Gerar cobrança Boleto

Gera uma cobrança via boleto pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.

Para boleto, o endereço completo do comprador é obrigatório. Você pode personalizar vencimento, multa, juros e desconto por meio de boletoInstructions.

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.boleto.generated (envia o boleto ao comprador assim que a cobrança é criada), oneoff.payment.success (confirmação ao comprador quando o boleto compensa) 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), 404 PRICE_NOT_FOUND (preço inexistente) e 400 INVALID_DATA (campo inválido — inclui endereço ausente).

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.

POST/v1/charges
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

checkouts/write

Body

application/json

Content-Type:application/json
JSON
{
  "paymentMethod": "boleto",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",  
    "metadata": { "origem": "site" },
    "phone": "+5511999998888",  
    "cep": "01310100",
    "address": {
      "type": "BILLING",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "amount": 10.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1,
      "isOrderBump": false
    }
  ],
  "dueDate": "2026-07-30",
  "boletoDueDays": 7,
  "expirationAfterDueDate": 30,
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "limitDate": "2026-07-28",
      "daysBeforeDue": 3
    }
  },
  "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",
      "amount": 10.0,
      "couponCode": "PROMO10",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "tokenId": "tok_abc123",
  "cartId": "cart_2026_0001",
  "productId": "prod_123456_example",
  "billingDay": 10
}

Schema

paymentMethodstringobrigatório
Forma de pagamento (fixo: boleto)
Valores aceitos:pixcreditcardboletopix_automatico
customerobjectobrigatório
Dados do comprador
externalIdstringopcional
Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)
Regra:até 100 caracteres
externalTxidstringopcional
Identifica a loja, o caixa ou o vendedor responsável pela cobrança
Regra:até 100 caracteres
amountnumberopcional
Valor total em reais (alternativa a items; use um ou outro)
Regra:0.01
itemsarray[1]opcional
Produtos da compra (ou use amount para cobrança avulsa)
dueDatestringopcional
Vencimento do boleto (YYYY-MM-DD, maior que hoje)
Regra:^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
boletoDueDaysnumberopcional
Dias até o vencimento (mín. 1; ignorado se dueDate informado)
Regra:1
expirationAfterDueDatenumberopcional
Dias para cancelar o boleto após o vencimento (0 a 60)
Regra:0 a 60
boletoInstructionsobjectopcional
Regras de multa/juros/desconto do boleto
couponCodestringopcional
Código de cupom de desconto
metadataobjectopcional
Objeto livre, aceita as chaves e valores que você quiser ("referência" é só exemplo); aceito mas NÃO persistido nesta rota, para correlacionar o pedido use externalId
descriptionstringopcional
Descrição livre da cobrança
splitarray[1]opcional
Divisão do valor. Não suportado em creditcard nem pix_automatico
installmentsnumberopcional
Parcelas no cartão, de 1 a 12
Regra:1 a 12
freeInstallmentsnumberopcional
Parcelas sem juros para o comprador, de 0 a 12
Regra:0 a 12
passFeesToCustomerbooleanopcional
Repassa a taxa de parcelamento ao comprador
allowedPaymentMethodsarray[2]opcional
Métodos aceitos quando a cobrança vira link
Valores aceitos:pixcreditcardboletopix_automatico
nfConfigIdstringopcional
Emite nota fiscal com esta configuração. Exige customer.address
notificationsarray[3]opcional
E-mails disparados nesta cobrança
Valores aceitos:oneoff.pix.generatedoneoff.boleto.generatedoneoff.payment.successoneoff.payment.failednew.saleseller.charge.pending
discountsarray[1]opcional
Descontos aplicados a cobrança
tokenIdstringopcional
Alternativa a card e a paymentMethodId no cartão
cartIdstringopcional
Agrupa numa única compra as assinaturas criadas juntas e deduplica o evento de conversão
productIdstringopcional
Cria a cobrança a partir de um produto
Regra:^prod_
billingDaynumberopcional
Dia do mês em que a recorrência cobra, de 1 a 31
Regra:1 a 31

Headers

Content-Typeopcional
application/json
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",
  "externalId": "pedido-2026-0001",
  "externalTxid": "loja-01-caixa-03",
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",  
    "metadata": { "origem": "site" },
    "phone": "+5511999998888",  
    "cep": "01310100",
    "address": {
      "type": "BILLING",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100",
      "country": "BR",
      "cityCode": "3550308"
    }
  },
  "amount": 10.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1,
      "isOrderBump": false
    }
  ],
  "dueDate": "2026-07-30",
  "boletoDueDays": 7,
  "expirationAfterDueDate": 30,
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "limitDate": "2026-07-28",
      "daysBeforeDue": 3
    }
  },
  "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",
      "amount": 10.0,
      "couponCode": "PROMO10",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "tokenId": "tok_abc123",
  "cartId": "cart_2026_0001",
  "productId": "prod_123456_example",
  "billingDay": 10
})
};

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

Response Examples

200200▾
JSON
{
  "success": true,
  "customerId": "cus_xxx",
  "chargeId": "cha_abc123",
  "boleto": {
    "digitableLine": "23793.38128 60007.827136 95000.063305 9 84410000010000",
    "barCode": "23799844100000100003381260007827139500006330",
    "dueDate": "2026-07-30",
    "pdfUrl": "https://app.validapay.com.br/boletos/cha_abc123.pdf"
  }
}
404404 PRICE_NOT_FOUND▾
JSON
{
  "error": {
    "message": "Preço não encontrado",
    "code": "PRICE_NOT_FOUND"
  }
}
409409 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"
  }
}

← Anterior

Gerar cobrança Pix Automático

Próximo →

Gerar cobrança Cartão