Depósitos Boleto
Emissão de boleto bancário via API: endereço obrigatório, linha digitável, PDF e confirmação assíncrona.
Depósitos Boleto
Além do PIX, a Zypfy emite boleto bancário pela mesma rota de depósito — muda apenas o campo paymentMethod e a exigência do endereço do pagador.
Diferenças em relação ao PIX
| PIX | Boleto | |
|---|---|---|
| Confirmação | Segundos | 1 a 3 dias úteis após o pagamento |
| Endereço do pagador | Não exigido | Obrigatório e completo |
| Retorno da criação | QR Code + Copia e Cola | Linha digitável + código de barras + PDF |
| Liquidação no seu saldo | Imediata | Retida até a liquidação bancária (D+N) |
| Cancelamento | QR expira | Boleto vence na data de expiração |
Endpoint
POST https://api.zypfy.com/api/payments/depositHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
Body
{
"paymentMethod": "boleto",
"amount": 250.00,
"external_id": "order-2026-0042",
"clientCallbackUrl": "https://minhaloja.com/webhooks/deposit",
"payer": {
"name": "Maria Souza",
"email": "[email protected]",
"document": "98765432100",
"phone": "11987654321"
},
"address": {
"zipCode": "01310930",
"street": "Avenida Paulista",
"number": "1578",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP"
}
}Campos
Obrigatórios
| Campo | Tipo | Descrição |
|---|---|---|
paymentMethod | string | Fixo em "boleto". Se omitido, a cobrança sai como PIX. |
amount | number | Valor em BRL (ex.: 250.00). |
external_id | string | Seu identificador único. Serve como chave de idempotência, igual ao PIX. |
payer.name | string | Nome do pagador — vai impresso no boleto. |
payer.email | string | Email do pagador. A Zypfy envia o boleto para este endereço automaticamente. |
payer.document | string | CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador. |
Endereço (obrigatório)
O emissor bancário recusa boletos sem endereço completo. Envie o objeto em address (raiz do body) ou em payer.address — os dois são aceitos.
| Campo | Tipo | Descrição |
|---|---|---|
address.zipCode | string | CEP com 8 dígitos. Pontuação é removida automaticamente. |
address.street | string | Logradouro. |
address.number | string | Número. |
address.neighborhood | string | Bairro. |
address.city | string | Cidade. |
address.state | string | UF com 2 letras (ex.: "SP"). |
Os nomes em português também funcionam: cep, logradouro, numero, bairro, cidade, uf.
Se qualquer um faltar, a resposta é 422:
{
"message": "Para gerar o boleto, informe o endereço completo (CEP, rua, número, bairro, cidade e UF).",
"code": "BOLETO_ADDRESS_REQUIRED"
}Opcionais
Os mesmos do PIX — clientCallbackUrl, payer.phone, split, utm_*, platform, src, sck, products. O comportamento é idêntico ao descrito em Depósitos PIX.
Resposta
201 Created:
{
"message": "Deposit created successfully.",
"qrCodeResponse": {
"transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "PENDING",
"qrcode": null,
"amount": 250.00,
"paymentMethod": "boleto",
"boleto": {
"digitableLine": "34191790010104351004791020150008291070026000",
"barcode": "34197910200000250001040435100479102015000829",
"pdfUrl": "https://api.zypfy.com/api/links/boleto/48211/9f3c1a7e2b4d6058",
"expiresAt": "2026-07-29T23:59:59.000Z"
},
"fee": 3.50
}
}| Campo | Descrição |
|---|---|
boleto.digitableLine | Linha digitável — é o que o pagador digita no app do banco. Exiba com destaque e ofereça botão de copiar. |
boleto.barcode | Código de barras, para gerar a representação gráfica se você renderiza o boleto no seu layout. |
boleto.pdfUrl | PDF do boleto, servido pelo domínio da Zypfy. Pode ser enviado ao pagador ou aberto direto. |
boleto.expiresAt | Data de vencimento. Depois dela o boleto não é mais pagável. |
status | Sempre PENDING na criação — boleto nunca nasce pago. |
Envio automático por email
Ao criar o boleto, a Zypfy envia a linha digitável e o PDF para o payer.email informado. Você não precisa implementar esse email — mas continua livre para exibir os dados no seu próprio checkout, que é o caminho com melhor conversão.
Confirmação do pagamento
Boleto é assíncrono: o pagador tem até o vencimento para pagar, e a compensação bancária leva de 1 a 3 dias úteis. Sua integração descobre o pagamento de duas formas:
- Webhook — quando compensa, a Zypfy envia
type: "Deposit",status: "COMPLETED"epayment_method: "boleto". Veja Webhooks. - Consulta —
GET /api/transactions/deposit?external_id=...devolve o status atual e o campopayment_method.
Boletos vencidos sem pagamento terminam em FAILED.
Liquidação: retenção D+N
O dinheiro do boleto entra no seu saldo quando o pagamento compensa, mas fica retido até a data de liberação acordada para a sua conta (D+N, configurável pelo suporte). Durante a retenção:
- O valor aparece no seu saldo total e no extrato.
- O valor não entra no saldo disponível para saque.
- Na data de liberação, a retenção cai automaticamente e o valor vira sacável.
Consulte /api/accounts/balance para ver saldo total e disponível separadamente.
Erros específicos
code | HTTP | Causa | Remediação |
|---|---|---|---|
BOLETO_DISABLED | 403 | Boleto não habilitado nesta conta. | Solicitar liberação ao suporte. |
BOLETO_ADDRESS_REQUIRED | 422 | Endereço ausente ou incompleto. | Enviar CEP, rua, número, bairro, cidade e UF. |
INVALID_METHOD | 400 | paymentMethod fora de pix, boleto, card. | Corrigir o valor. |
DEPOSIT_DISABLED | 403 | Depósitos bloqueados na conta. | Contato com suporte. |
Quando o emissor bancário recusa a emissão (tipicamente por dados do pagador inconsistentes), a resposta é:
{
"message": "Não foi possível gerar o boleto. Confira o nome, CPF/CNPJ e o endereço completo (CEP, rua, número, bairro, cidade e UF) — precisam ser dados reais e válidos — e tente novamente."
}Exemplo completo
const { data } = await axios.post(
'https://api.zypfy.com/api/payments/deposit',
{
paymentMethod: 'boleto',
amount: 250.0,
external_id: 'order-2026-0042',
clientCallbackUrl: 'https://minhaloja.com/webhooks/deposit',
payer: {
name: 'Maria Souza',
email: '[email protected]',
document: '98765432100',
},
address: {
zipCode: '01310930',
street: 'Avenida Paulista',
number: '1578',
neighborhood: 'Bela Vista',
city: 'São Paulo',
state: 'SP',
},
},
{ headers: { Authorization: `Bearer ${token}` } }
);
const { digitableLine, pdfUrl, expiresAt } = data.qrCodeResponse.boleto;
// Guarde transactionId vinculado ao seu pedido e aguarde o webhook COMPLETED.
await db.pedidos.update(
{ gateway_id: data.qrCodeResponse.transactionId, status: 'AGUARDANDO_BOLETO' },
{ where: { external_id: 'order-2026-0042' } }
);