ZypfyDocs Acessar painel
Guia de integração

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

PIXBoleto
ConfirmaçãoSegundos1 a 3 dias úteis após o pagamento
Endereço do pagadorNão exigidoObrigatório e completo
Retorno da criaçãoQR Code + Copia e ColaLinha digitável + código de barras + PDF
Liquidação no seu saldoImediataRetida até a liquidação bancária (D+N)
CancelamentoQR expiraBoleto vence na data de expiração

Endpoint

código
POST https://api.zypfy.com/api/payments/deposit

Headers: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.

Body

json
{
  "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

CampoTipoDescrição
paymentMethodstringFixo em "boleto". Se omitido, a cobrança sai como PIX.
amountnumberValor em BRL (ex.: 250.00).
external_idstringSeu identificador único. Serve como chave de idempotência, igual ao PIX.
payer.namestringNome do pagador — vai impresso no boleto.
payer.emailstringEmail do pagador. A Zypfy envia o boleto para este endereço automaticamente.
payer.documentstringCPF (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.

CampoTipoDescrição
address.zipCodestringCEP com 8 dígitos. Pontuação é removida automaticamente.
address.streetstringLogradouro.
address.numberstringNúmero.
address.neighborhoodstringBairro.
address.citystringCidade.
address.statestringUF 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:

json
{
  "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:

json
{
  "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
  }
}
CampoDescrição
boleto.digitableLineLinha digitável — é o que o pagador digita no app do banco. Exiba com destaque e ofereça botão de copiar.
boleto.barcodeCódigo de barras, para gerar a representação gráfica se você renderiza o boleto no seu layout.
boleto.pdfUrlPDF do boleto, servido pelo domínio da Zypfy. Pode ser enviado ao pagador ou aberto direto.
boleto.expiresAtData de vencimento. Depois dela o boleto não é mais pagável.
statusSempre 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:

  1. Webhook — quando compensa, a Zypfy envia type: "Deposit", status: "COMPLETED" e payment_method: "boleto". Veja Webhooks.
  2. Consulta — GET /api/transactions/deposit?external_id=... devolve o status atual e o campo payment_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:

Consulte /api/accounts/balance para ver saldo total e disponível separadamente.

Erros específicos

codeHTTPCausaRemediação
BOLETO_DISABLED403Boleto não habilitado nesta conta.Solicitar liberação ao suporte.
BOLETO_ADDRESS_REQUIRED422Endereço ausente ou incompleto.Enviar CEP, rua, número, bairro, cidade e UF.
INVALID_METHOD400paymentMethod fora de pix, boleto, card.Corrigir o valor.
DEPOSIT_DISABLED403Depósitos bloqueados na conta.Contato com suporte.

Quando o emissor bancário recusa a emissão (tipicamente por dados do pagador inconsistentes), a resposta é:

json
{
  "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

javascript
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' } }
);