电子商务 · Marketplace · 钱包
如何接收多付款人 Pix，并结算为稳定币
每个订单创建独立收款单，不使用通用二维码。 将您的
external_id 关联至订单，填写付款人 CPF/CNPJ，在展示 Pix 前查询可用额度，并通过 webhook 确认。按产品流程，结算可进入钱包或 BRL 主账户 / 子账户余额。每个订单一张收款单付款人 CPF/CNPJexternal_idwebhookUSDT · USDC
最小数据模型
checkout_order id // 内部标识符 lunium_external_id // 固定且唯一 lunium_cashin_id // API 返回值 payer_tax_hash // 内部策略；不要发送至分析平台 amount_cents status expected_release_at created_at
逐单流程
验证付款人
在服务器规范化 CPF/CNPJ，并查询 GET /cashin/limits?payer_tax=。分级限额按每个证件独立计算。
查询预览
通过以下接口验证金额、资产、网络及钱包： POST /cashin/preview。不要根据本地计算的汇率向客户作出承诺。
使用唯一标识创建
传入由订单派生的 external_id 。超时后保持相同 payload 及标识重试。
展示二维码与资金可用预期
API 如提示资金冻结，须在付款前说明释放会延后，不要将其称为失败。
确认并对账
通过 webhook 更新订单，使用状态查询及投递历史恢复遗漏信息。
两种可选架构
直接结算
每张收款单指定 payout_address，稳定币交付至该订单配置的钱包。
余额与子账户
使用 destino: saldo 及 customer_ref，按客户隔离入账，之后通过已允许的方式使用。
可能造成资金损失的错误
复用二维码： 破坏一个订单对应一张收款单的关系，增加识别金额、付款人及退款的难度。
重试时新建 external_id： 可能将网络不确定性变成第二张收款单。
将限额固定写入代码： 数值会过期，请读取
/keys/me 及 /cashin/limits。持久化状态： 展示二维码及在系统中确认订单前，先保存交易标识。
接入验收清单
对账
内部订单、 external_id 及 cashin_id 已关联，且可检索。
隐私政策
CPF/CNPJ 不进入数据分析、URL、会话录制工具或应用日志。
客户体验
买家付款前可查看金额、期限、到期时间及可能的资金冻结。
支持
request_id 及技术标识即可，绝不发送 API 密钥。
迁移客户前，先验证收银台
在 cash-in 测试环境验证身份、目录、限额、预览、模拟付款及 webhook，不使用真实资金。可付款二维码及真实收款状态须通过生产密钥和受控首笔试点核验。