面向平台及合作伙伴 · Pix → BRL 余额
通过 API 接收 Pix，记入 BRL 余额。
无需登记固定加密资产钱包，即可将 Pix 收款记入主账户或子账户托管余额。之后可通过 Pix 提现，或按交付目录选择币种和网络兑换为加密资产。
适用于网站、SaaS 或平台的 Pix 收款单。
系统可为每个订单创建收款单，向客户展示二维码，并通过 webhook 跟踪确认。收款记入 BRL 托管余额；申请提现前，须核对结算、费用及可用余额。
若仍在选择方案，可先查看 Pix API 概览。下方提供实现收款所需的字段及示例。
先收款，之后再选择出金方式。
若产品需要收款、隔离不同客户余额，并稍后决定提现目的地，可选择此流程。托管余额以 BRL计价，一笔 Pix 不会同时生成 BTC、USDT 及 USDC 余额；只有申请加密资产提现时才执行兑换。
无需钱包的收款单
通过以下参数创建 Pix： destino: "saldo"。填写金额及付款人证件，使用 customer_ref 将入账分配至子账户。
入账与可用性
跟踪结算，并在流水中核对扣费后净额。仅使用可用余额；资金冻结及等待期可能使部分总额暂不可用。
之后再选择提现
使用 POST /payouts 用于 Pix 付款，或 POST /saldo/sacar-cripto 在提现时选择币种、网络及地址。
API 中省略 destino 仍表示直接交付加密资产。托管收款须明确传入 destino: "saldo"。在 Telegram 中， /cobrar valor cpf 默认使用托管余额。
不填写钱包，如何生成 Pix 收款单
使用 lun_test_密钥并保存在后端，确认 key.sandbox=true → GET /keys/me。下方示例的证件及收款地址均为虚构数据，不要使用生产凭证提交。
POST /cashin/charge · 测试环境请求体示例
{
"amount_cents": 100000,
"payer_tax_number": "12345678901",
"destino": "saldo",
"customer_ref": "cliente-teste",
"external_id": "sandbox-custodia-001"
}示例创建虚拟 R$ 1,000.00 收款单。发送至 https://api.luniumpay.com/cashin/charge，请求头 X-API-Key 中使用测试密钥，请求体为 JSON。此流程不要包含 payout_address 。 payer_tax_number 是付款人的证件； customer_ref 是客户在您系统中的引用标识。
保存返回的 cashin_id 。测试环境通过以下接口确认： POST /sandbox/cashin/{cashin_id}/pay ，请求体为 {} ；然后查询 GET /cashin/{cashin_id}/status 最高 status=paid 及 settlement_status=sent。测试二维码包含 SANDBOX:NAO_PAGAVEL: ，不得使用银行应用支付。
之后查询 GET /saldo?customer_ref=cliente-teste。入账净额已扣除密钥适用费用；须以实际收到金额核对流水，不要假定二维码票面金额全部成为可用余额。
主账户、客户子账户与对账流水
| 查询 | 返回的余额或信息 |
|---|---|
GET /saldo | 主账户，即密钥自身余额，不包含客户子账户。 |
GET /saldo?customer_ref=cliente-teste | 仅指定子账户，含可用 / 冻结余额及适用条件。 |
GET /saldo/consolidado | 主账户与客户子账户的总托管金额，用于对账。 |
GET /saldo/clientes | 子账户列表，按返回的分页信息继续查询。 |
GET /saldo/extrato?customer_ref=cliente-teste | 子账户流水，继续分页使用 before=proxima_pagina。 |
充值、查询及提现须复用同一引用标识，最长 80 个字符。 POST /saldo/transferir 可在子账户与主账户之间转移可用余额，不生成 Pix。内部转账也须有已授权的业务意图及 external_id 稳定标识。
通过 customer_ref 隔离余额，不能替代产品用户的身份验证及权限控制。API 密钥可操作该账户全部子账户，只能保存在后端。
通过 Pix 或所选加密资产提现
POST /saldo/sacar-cripto · 测试环境请求体示例
{
"amount_cents": 10000,
"asset": "usdc",
"chain": "base",
"payout_address": "0x1111111111111111111111111111111111111111",
"tax_number": "12345678901",
"customer_ref": "cliente-teste",
"external_id": "sandbox-saque-usdc-001"
}加密资产提现中的 amount_cents 是待兑换的 BRL 金额，不是代币数量。扣款包含平台费用，兑换及路由成本会影响接收数量。请跟踪返回的 cashin_id ，直至 settlement_status=sent。
仅选择以下有效组合： entregavel=true 的 GET /cashin/catalog；托管提现不支持 Liquid/DePix。请查询当前最低金额及 memo 要求。 POST /cashin/preview 仅预估兑换，不是提现完整扣款预览。 max_debited_cents 可限制 BRL 扣款，但不锁定汇率或代币数量。
产品界面须展示费用与资金冻结条件
读取 deposito_fee_bps、 deposito_fee_fixed_cents、 carencia_horas ，以及后续资金释放信息： GET /saldo。同时查询付款人限额： GET /cashin/limits。入账已结算后，部分余额仍可能因冻结规则暂不可用。
保存 external_id 及返回标识后，再更新您的订单。重试保持相同引用及请求体。配置 HTTPS 接收端，对原始请求体验证 HMAC 签名，并按 event_id去重。超时后，先查询原交易再决定是否重试。 Webhook 与对账手册 提供完整实现说明。
接入常见问题
合作伙伴收到 BRL，还是各种加密资产？
合作伙伴收到扣费后的 BRL 余额。加密资产提现时，再选择当时可交付的币种 / 网络组合，并非不受限制地支持全部加密资产。
密钥必须配置固定钱包吗？
不需要。托管充值无需地址，每次加密资产提现时再填写所选网络的钱包；Pix 提现则填写 Pix 收款标识。
如何避免使用冻结余额？
使用正确子账户的可用余额字段，并跟踪资金释放及流水。 total_cents 可能包含冻结金额，不能视为可提现余额。
可以在同一测试环境中测试充值和提现吗？
可以。Custody 流程会创建模拟 Pix、确认入账并执行模拟加密资产提现。完整工具包还测试 Pix 对外付款及内部转账，不涉及真实资金。