Boleto

Requer autenticação
POST/v2/boleto

Emite um boleto bancário registrado (ou boleto híbrido com PIX, PIX_BOLETO) e retorna o código de barras, linha digitável e URL do PDF do boleto. O cliente paga em qualquer banco, lotérica, caixa eletrônico ou app bancário. Quando pago, você recebe o webhook cashin.confirmed com payment_method: BOLETO.

Boleto só suporta BRL. Para outras moedas use Cash-in.

Parâmetros
amountnumberobrigatório
Valor da cobrança (até 2 decimais). Mínimo 1.00.
methodstringobrigatório
BOLETO (puro) ou PIX_BOLETO (híbrido — aceita boleto OU PIX pelo mesmo documento).
payer.namestringobrigatório
Nome completo do pagador.
payer.documentstringobrigatório
CPF ou CNPJ do pagador. Validado matematicamente.
payer.emailstringobrigatório
E-mail do pagador. Formato padrão.
payer.phonestringobrigatório
Telefone do pagador (8 a 12 dígitos numéricos, sem formatação).
payer.address.addressstringobrigatório
Logradouro (rua, avenida).
payer.address.numberstring
Número do endereço.
payer.address.complementstring
Complemento (apto, bloco, sala).
payer.address.districtstringobrigatório
Bairro.
payer.address.citystringobrigatório
Cidade.
payer.address.zipCodestringobrigatório
CEP com 8 dígitos (sem traço).
payer.address.ufstringobrigatório
UF com 2 letras maiúsculas (ex: SP, RJ).
due_datestring
Data de vencimento no formato yyyy-mm-dd. Padrão: hoje + 3 dias.
descriptionstring
Descrição livre do boleto (aparece no app/comprovante).
external_idstring
Identificador único no seu sistema (idempotência). Máx 150 caracteres.
transaction_idstring
Seu identificador. Único por merchant. Default: gerado automaticamente.
postback_urlstring
URL HTTPS que receberá o webhook cashin.confirmed. Sobrescreve o webhook default da credencial.

Resposta

Parâmetros
transaction_idstring
Nosso identificador da transação. Use pra consulta e correlação com webhook.
payment_methodstring
Ecoa o method da request: BOLETO ou PIX_BOLETO.
statusstring
pending até o pagador pagar o boleto.
gateway_idnumber
ID do adquirente processando o boleto.
boleto.barcodestring
Código de barras numérico de 44 dígitos. Use pra renderizar o boleto no seu lado.
boleto.digitable_linestring
Linha digitável formatada (47 dígitos com separadores).
boleto.urlstring
URL do PDF do boleto. Pode vir null em alguns casos — nesses, renderize pelo barcode com biblioteca client-side.
boleto.due_datestring
Data de vencimento ecoada (ISO yyyy-mm-dd).
boleto.registrationstring
Status do registro bancário: registered (confirmado pela Núclea) ou pending (ainda registrando — webhook atualiza).

Erros possíveis

error.codeHTTPCausa
MISSING_REQUIRED_FIELD400Campo obrigatório ausente ou inválido (ver details.field).
INVALID_DOCUMENT400CPF/CNPJ inválido matematicamente.
CREDENTIAL_PERMISSION_DENIED403Credencial API sem can_cashin.
ACCOUNT_UNDER_REVIEW403Conta em revisão manual.
LIMIT_EXCEEDED403Valor acima do limite ou volume diário excedido.
PROVIDER_ERROR502Erro temporário no adquirente (retryable).
cURL
PHP
Node
Python
curl -X POST https://api.bspay.co/v2/boleto \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "method": "BOLETO",
    "payer": {
      "name": "João da Silva",
      "document": "11144477735",
      "email": "[email protected]",
      "phone": "11999999999",
      "address": {
        "address": "Rua das Flores",
        "number": "100",
        "district": "Centro",
        "city": "São Paulo",
        "zipCode": "01000000",
        "uf": "SP"
      }
    },
    "due_date": "2026-10-20",
    "description": "Pedido #1234",
    "transaction_id": "pedido_1234_boleto",
    "postback_url": "https://seu-sistema.com/webhooks/cashin"
  }'

Resposta de sucesso (201)

{
  "transaction_id": "17e2a3cebe24457578396466a61b919b",
  "external_id": null,
  "amount": 150,
  "payment_method": "BOLETO",
  "status": "pending",
  "gateway_id": 189,
  "boleto": {
    "barcode": "79299060500000150004492128193072609500070000",
    "digitable_line": "79294492182819307260195000700005906050000015000",
    "url": null,
    "due_date": "2026-10-20",
    "registration": "registered"
  }
}

Depois do pagamento

Quando o pagador paga, você recebe o webhook cashin.confirmed (ver Webhooks) e o boleto aparece em Listar Transações com status: confirmed e o bloco boleto populado.

Esta página foi útil?