Boleto Bancário（巴西银行凭单）

Quick Reference

WhatBoleto Bancário 支付

Why离线银行凭单——巴西任意银行、ATM 或银行 App 均可付款，覆盖无银行账户人群

Reading Time10 分钟

Difficulty初级

Prerequisites身份验证 → 环境配置

什么是 Boleto Bancário

Boleto（巴西银行支付凭单）是由巴西央行监管的支付凭证。商户生成一张带条形码和到期日的 Boleto；客户可在任意银行网点、ATM、彩票站或银行 App 完成支付。结算通过 CIP（Câmara Interbancária de Pagamentos，巴西银行间支付清算所）在 1–3 个工作日内完成。

特性	详情
市场	巴西
币种	BRL
结算	D+1 到 D+3
拒付	无——Push 支付
默认过期时间	3 天（可配置）

---

运作方式

1

商户创建收费

您的服务器调用 POST /api/v1/bank/wallet/charge/，设置 type_charge: "boleto"。

2

A55 生成 Boleto

API（应用程序编程接口）返回 PDF 链接（boleto_url）和可输入条形码行（barcode）。

3

客户付款

客户在银行网点、ATM、彩票站或银行 App 使用条形码完成付款。

4

通过 CIP 结算

支付经 CIP 确认，A55 发送 webhook（网络钩子），状态为 paid。

---

支付流程

---

Boleto 生命周期

状态	说明
issued	Boleto 已生成；等待付款
pending	已在银行登记；等待客户付款
paid	支付已通过 CIP 确认
cancelled	付款前已过期或作废
failed	生成或处理错误

---

创建 Boleto 收费

POST/api/v1/bank/wallet/charge/Bearer Token创建 Boleto 支付

请求体

字段	类型	必填	说明
type_charge	string	是	必须为 "boleto"
currency	string	是	"BRL"
installment_value	number	是	BRL 金额（如 150 表示 R$150）
installment_count	number	是	Boleto 始终为 1
payer_tax_id	string	是	CPF（巴西个人税号，11 位）或 CNPJ（巴西企业税号，14 位）
payer_name	string	是	付款人全名
due_date	string	是	ISO 8601 到期日
description	string	否	Boleto 上显示的订单描述

cURL

curl -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "张伟",
    "payer_email": "zhangwei@example.com",
    "payer_tax_id": "12345678901",
    "payer_cell_phone": "+5511988887777",
    "installment_value": 250,
    "installment_count": 1,
    "items": [{"name":"年度套餐","quantity":1,"total_amount":250,"unit_amount":250,"sku":"PLAN-001","code":"AP001"}],
    "payer_address": {"street":"Rua Augusta","address_number":"500","complement":"Sala 12","neighborhood":"Consolação","city":"São Paulo","state":"SP","postal_code":"01304-001","country":"BR"},
    "currency": "BRL",
    "due_date": "2026-04-05T23:59:59Z",
    "description": "年度订阅",
    "type_charge": "boleto",
    "webhook_url": "https://yoursite.com/webhook",
    "redirect_url": "https://yoursite.com/confirmation"
  }'

Python

import requests

try:
    response = requests.post(
        "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
        headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
        json={
            "wallet_uuid": "00000000-0000-0000-0000-000000000000",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
            "payer_name": "张伟",
            "payer_email": "zhangwei@example.com",
            "payer_tax_id": "12345678901",
            "payer_cell_phone": "+5511988887777",
            "installment_value": 250,
            "installment_count": 1,
            "items": [{"name": "年度套餐", "quantity": 1, "total_amount": 250, "unit_amount": 250, "sku": "PLAN-001", "code": "AP001"}],
            "payer_address": {"street": "Rua Augusta", "address_number": "500", "complement": "Sala 12", "neighborhood": "Consolação", "city": "São Paulo", "state": "SP", "postal_code": "01304-001", "country": "BR"},
            "currency": "BRL",
            "due_date": "2026-04-05T23:59:59Z",
            "description": "年度订阅",
            "type_charge": "boleto",
            "webhook_url": "https://yoursite.com/webhook",
            "redirect_url": "https://yoursite.com/confirmation",
        },
    )
    response.raise_for_status()
    data = response.json()
    print(f"Boleto URL：{data['boleto_url']}")
    print(f"条形码：{data['barcode']}")
except requests.exceptions.HTTPError as e:
    print(f"请求失败（HTTP {e.response.status_code}）：{e.response.text}")

JavaScript

try {
  const response = await fetch(
    "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        wallet_uuid: "00000000-0000-0000-0000-000000000000",
        merchant_id: "11111111-1111-1111-1111-111111111111",
        payer_name: "张伟",
        payer_email: "zhangwei@example.com",
        payer_tax_id: "12345678901",
        payer_cell_phone: "+5511988887777",
        installment_value: 250,
        installment_count: 1,
        items: [{ name: "年度套餐", quantity: 1, total_amount: 250, unit_amount: 250, sku: "PLAN-001", code: "AP001" }],
        payer_address: { street: "Rua Augusta", address_number: "500", complement: "Sala 12", neighborhood: "Consolação", city: "São Paulo", state: "SP", postal_code: "01304-001", country: "BR" },
        currency: "BRL",
        due_date: "2026-04-05T23:59:59Z",
        description: "年度订阅",
        type_charge: "boleto",
        webhook_url: "https://yoursite.com/webhook",
        redirect_url: "https://yoursite.com/confirmation",
      }),
    }
  );
  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const { boleto_url, barcode } = await response.json();
  console.log("Boleto URL：", boleto_url);
} catch (err) {
  console.error("创建 Boleto 失败：", err.message);
}

---

响应示例

{
  "charge_uuid": "a3b1c2d4-5678-9abc-def0-1234567890ab",
  "currency": "BRL",
  "type": "boleto",
  "status": "issued",
  "boleto_url": "https://pay.a55.tech/boleto/a3b1c2d4-5678-9abc-def0-1234567890ab.pdf",
  "barcode": "23793.38128 60000.000003 00000.000400 1 84340000025000",
  "due_date": "2026-04-05",
  "charge_payment_url": "https://pay.a55.tech/charge/a3b1c2d4-5678-9abc-def0-1234567890ab"
}

字段	说明
boleto_url	Boleto PDF 直链，可下载或打印
barcode	可输入行——客户可在任意银行 App 中输入
due_date	到期日，过期后 Boleto 不可支付
charge_payment_url	含 Boleto 详情的托管支付页

---

过期

Boleto 默认过期时间为 3 个工作日。可通过 due_date 字段配置。过期后，Boleto 自动取消，并发送状态为 cancelled 的 webhook。

过期 Boleto 支付尝试

客户可能仍尝试在银行网点支付已过期的 Boleto，银行会拒绝支付，但客户体验不佳。请设置合理的过期窗口。

---

结算时间

场景	结算
标准 Boleto	D+1 到 D+3 个工作日
已登记 Boleto（boleto registrado）	D+1

CIP 结算机制

客户支付 Boleto 后，开户银行通知 CIP（巴西银行间支付清算所）。CIP 以批处理方式完成银行间结算，并通知 A55。A55 随即向您的 endpoint（端点）触发 paid webhook。整个周期需 1–3 个工作日，取决于银行和付款时间。

---

常见错误

错误	原因	解决方案
invalid_tax_id	CPF/CNPJ 校验失败	确认付款人的 CPF（11 位）或 CNPJ（14 位）
invalid_due_date	due_date 已过期	设置未来日期，至少提前 1 个工作日
amount_below_minimum	金额低于服务商最低限额	查看 Boleto 最低金额（通常 R$5.00）
boleto_generation_failed	银行拒绝登记	重试；持续失败请检查付款人数据并联系支持团队

PIX →巴西即时支付信用卡 →分期付款的卡支付结算 →资金如何到达您的账户