面向平台 · BRL 余额 → Pix
通过 API 支付 Pix，跟踪每笔付款。
使用主账户或子账户的 BRL 余额支付 Pix。适用于用户提现、付款及资金分发，每笔扣款有明确标识、费用明细及 API 状态跟踪。
将支付与资金分发接入您的系统。
平台需要使用可用 BRL 余额向收款人付款时，可选择 Pix 对外付款。每笔付款都有引用标识、成本及状态，便于与您的系统对账。
多收款人业务须由您的应用分别管理各笔付款意图及标识。不要假定存在统一批量付款或自动分账接口。另见 LuniumPay Pix 收款与付款。
发送 Pix 前须准备什么
Pix 对外付款使用可用 BRL 余额，适用于已通过 Pix 托管收款 并需要用户提现或资金分发的平台。如资金位于外部加密资产钱包，应使用 加密资产兑换 Pix 的 cash-out 流程。
核对功能是否启用
读取 payout.enabled → GET /keys/me 及 custodia_ativa → GET /saldo。实际适用您当前密钥的条件。
核对余额与费用
查询正确范围：主账户或 customer_ref。可用余额须覆盖 amount_cents 及提现费用。
创建并跟踪
发送 POST /payouts ，并保存引用标识，再持续跟踪返回的 payout_id ，直至最终结果。
GET /saldo 仅返回主账户余额。查询客户子账户时，请使用 GET /saldo?customer_ref=cliente-teste。 GET /saldo/consolidado 汇总主账户及客户子账户，但总额不是各子账户均可使用的共享余额。
子账户 Pix 提现示例
使用 lun_test_密钥并保存在后端，确认 key.sandbox=true → GET /keys/me。下方示例的证件及收款地址均为虚构数据，不要使用生产凭证提交。
先通过 POST /cashin/charge 并传入 destino: "saldo" 为测试子账户充值，并确认模拟付款。等待余额可用后，提现须使用完全相同的 customer_ref 。
POST /payouts · 测试环境请求体示例
{
"amount_cents": 5000,
"pix_key": "teste@example.com",
"pix_key_type": "email",
"tax_number": "00000000191",
"funding_source": "pix_brl",
"customer_ref": "cliente-teste",
"external_id": "sandbox-payout-001"
}发送至 https://api.luniumpay.com/payouts，并提供 X-API-Key 及 Content-Type: application/json。示例发送虚拟 R$ 50.00，余额须同时覆盖该金额与费用。若未提供 customer_ref，则使用主账户。
请将 Pix 收款标识及证件替换为实际收款人的资料。 tax_number 须包含有效的 CPF 或 CNPJ，适用于邮箱、手机号及随机类型的 Pix 收款标识。若收款标识本身为有效 CPF/CNPJ，API 将直接提取证件；如另行提供，必须一致。 beneficiary_name 仍为可选项，且不能证明账户归属。11 位数字的收款标识须指定 pix_key_type: "cpf" 或 "phone"；手机号须包含国际区号，例如 +55。
此流程仅使用通过 Pix 收到的 BRL 余额。 funding_source 为可选项，仅接受 pix_brl。每笔 Pix 最高为 600000 分（R$ 6,000.00），还须遵守账户较低的限额，另计适用费用。
遇到 409 external_id_divergente 或 external_id_nao_verificavel时，请查询 payout_id/recovery_endpoint所指向的订单。请保留原标识，不要新建标识绕过冲突。遇到 503 idempotencia_indisponivel时，应等待并查询同一 external_id，因为之前的订单可能已存在。
USDT 钱包与 BRL 余额相互独立，接收外部 USDT 充值，不使用 /payouts。对应钱包付款流程使用 funding_source=crypto_usdt，不要求收款人证件；限额以报价及 API 条件为准，不适用 BRL 余额的 R$ 6,000 上限。测试密钥使用独立模拟钱包，不涉及真实资金。
计算扣款并展示成本
扣款金额为 amount_cents + fee_cents。交易总费用包含 fee_service_cents 及 fee_provider_cents。请查询 saque_fee_bps、 saque_taxa_provedor_tipo、 saque_taxa_estimada_cents 及以下接口返回的计算公式： GET /saldo。
请读取 API 当前费用，按密钥条件预估，并用订单保存的实际费用对账。限额、等待期及资金冻结可能限制部分余额的使用。 402 saldo_insuficiente 表示可用余额不足以覆盖完整扣款。
测试环境以虚拟余额计算其 API 公布的费用；生产条件须查询真实密钥。
超时不代表可以再次付款
| 响应或状态 | 接入方处理方式 |
|---|---|
processing | 继续查询 GET /payouts/{payout_id}。不要显示付款已完成。 |
sent / payout.sent | 核对金额、费用及付款证明字段： e2e、 paid_at 及 verify_url（如有）。 |
failed 或 refunded | 核对订单及流水，明确拒绝与结果不确定须分别处理。 |
| 超时或结果不确定 | 恢复并查询原交易，不要为同一付款意图新建 external_id 。 |
保存 external_id 及返回标识后，再更新您的订单。重试保持相同引用及请求体。配置 HTTPS 接收端，对原始请求体验证 HMAC 签名，并按 event_id去重。超时后，先查询原交易再决定是否重试。 Webhook 与对账手册 提供完整实现说明。
调用服务商前会预留余额。明确拒绝时可能冲回扣款；结果不确定时，须先对账再判断退款。界面应显示“处理中”，允许更新状态，且不创建新订单。
接入常见问题
使用 Pix 对外付款需要登记加密资产钱包吗？
不需要。Pix 对外付款使用 BRL 余额及 Pix 收款标识。可通过以下收款方式取得余额： destino: "saldo"，无需固定钱包。
可以为每位用户隔离余额吗？
可以，使用 customer_ref 贯穿充值、查询及提现。该引用用于区分余额，但 API 密钥有权操作其所有子账户；后端仍须为每位用户校验权限。
付款前必须先查询收款人吗？
GET /pix/keys/lookup 属于辅助查询，可能返回 available=false 或 verified=false。此时显示“收款人身份未核验”，不要编造姓名；查询不可用不等于 Pix 对外付款不可用。
如何测试余额不足及结果不确定？
运行引导接入或工具包中的 payout 流程。通过 API 测试时，查询 GET /sandbox 查看场景矩阵，并在支持时使用 settlement_uncertain 。模拟结果核实仅对测试密钥开放。