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órioValor da cobrança (até 2 decimais). Mínimo
1.00. methodstringobrigatórioBOLETO (puro) ou PIX_BOLETO (híbrido — aceita boleto OU PIX pelo mesmo documento). payer.namestringobrigatórioNome completo do pagador.
payer.documentstringobrigatórioCPF ou CNPJ do pagador. Validado matematicamente.
payer.emailstringobrigatórioE-mail do pagador. Formato padrão.
payer.phonestringobrigatórioTelefone do pagador (8 a 12 dígitos numéricos, sem formatação).
payer.address.addressstringobrigatórioLogradouro (rua, avenida).
payer.address.numberstringNúmero do endereço.
payer.address.complementstringComplemento (apto, bloco, sala).
payer.address.districtstringobrigatórioBairro.
payer.address.citystringobrigatórioCidade.
payer.address.zipCodestringobrigatórioCEP com 8 dígitos (sem traço).
payer.address.ufstringobrigatórioUF com 2 letras maiúsculas (ex:
SP, RJ). due_datestringData de vencimento no formato
yyyy-mm-dd. Padrão: hoje + 3 dias. descriptionstringDescrição livre do boleto (aparece no app/comprovante).
external_idstringIdentificador único no seu sistema (idempotência). Máx 150 caracteres.
transaction_idstringSeu identificador. Único por merchant. Default: gerado automaticamente.
postback_urlstringURL HTTPS que receberá o webhook
cashin.confirmed. Sobrescreve o webhook default da credencial. Resposta
Parâmetros
transaction_idstringNosso identificador da transação. Use pra consulta e correlação com webhook.
payment_methodstringEcoa o
method da request: BOLETO ou PIX_BOLETO. statusstringpending até o pagador pagar o boleto. gateway_idnumberID do adquirente processando o boleto.
boleto.barcodestringCódigo de barras numérico de 44 dígitos. Use pra renderizar o boleto no seu lado.
boleto.digitable_linestringLinha digitável formatada (47 dígitos com separadores).
boleto.urlstringURL do PDF do boleto. Pode vir
null em alguns casos — nesses, renderize pelo barcode com biblioteca client-side. boleto.due_datestringData de vencimento ecoada (ISO yyyy-mm-dd).
boleto.registrationstringStatus do registro bancário:
registered (confirmado pela Núclea) ou pending (ainda registrando — webhook atualiza). Erros possíveis
error.code | HTTP | Causa |
|---|---|---|
MISSING_REQUIRED_FIELD | 400 | Campo obrigatório ausente ou inválido (ver details.field). |
INVALID_DOCUMENT | 400 | CPF/CNPJ inválido matematicamente. |
CREDENTIAL_PERMISSION_DENIED | 403 | Credencial API sem can_cashin. |
ACCOUNT_UNDER_REVIEW | 403 | Conta em revisão manual. |
LIMIT_EXCEEDED | 403 | Valor acima do limite ou volume diário excedido. |
PROVIDER_ERROR | 502 | Erro temporário no adquirente (retryable). |
Resposta de sucesso (201)
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.
