通过 REST API 与 webhook 构建 Pix 收银台，结算为 USDT 或 USDC
五步接入流程
创建密钥
使用 POST /keys/sandbox ，使用您的邮箱，在不涉及真实资金的情况下验证接口契约；或使用 POST /keys 创建生产密钥。完整明文密钥只显示一次。
读取目录与限额
查询 GET /cashin/catalog、 GET /keys/me 及 GET /cashin/limits。不要将网络、最低 / 最高金额或冻结分级固定写入代码。
查询预览
POST /cashin/preview 验证资产、网络、地址及金额，不创建收款单。
创建并展示 Pix
POST /cashin/charge 接受金额、付款人 CPF/CNPJ、目的地及 external_id。展示二维码前，应先告知 API 返回的冻结条件。
确认并对账
处理已签名 webhook，并使用 GET /cashin/{cashin_id}/status 作为补充查询；重试须保持相同的 external_id 。
最小生产请求示例
curl -X POST https://api.luniumpay.com/cashin/charge \
-H 'Content-Type: application/json' \
-H 'X-API-Key: SUA_CHAVE' \
-d '{
"amount_cents": 25000,
"payer_tax_number": "CPF_OU_CNPJ",
"asset": "usdt",
"chain": "polygon",
"payout_address": "CARTEIRA_DO_CLIENTE",
"external_id": "pedido-84721"
}'
Payload 仅供说明。实现前，请查询 当前 OpenAPI 中的字段、限额及响应。
收银台须解释的状态
pending
二维码已创建但尚未付款，不要自动另建收款单。
delayed
Pix 已付款，资金等待释放。不是失败，应展示 API 返回的期限。
paid
Pix 已收到，仍须核对 settlement_status；不要仅凭此状态交付产品。
settled
结算已完成；仅在 paid 且 settlement_status 为 sent 或 confirmed时，也可按该流程契约接受相应完成状态。
expired / refunded
结束旧尝试，必要时使用新的业务标识创建另一笔收款单。
首笔真实 Pix 前须准备什么
external_id ，为每个订单设置，并在调用前持久化保存。常见问题
生产密钥需要人工审批吗？
无需自行重建服务端流程，但应保存业务订单及关键标识。 POST /keys 支持自助创建生产密钥。名称为必填项；邮箱、钱包及 webhook 可按当前接口契约设置或更新。
必须使用轮询吗？
无需将轮询作为主要通知方式。Webhook 可减少延迟与查询负担，但仍须保留状态查询，用于对账及事件恢复。
如何避免重复收款单？
发送 external_id。完全相同的重试会恢复原交易；同一标识配合不同参数则返回冲突。
真实收银台上线前，先测试接口契约
先使用模拟资金验证失败场景，状态处理正确后，再按生产接入流程切换密钥。