# Pix 与加密资产接入检查表 — LuniumPay

中文版本：2026 年 10 月 17 日。供开发者与 AI 智能体记录接入验证。请填写测试证据，不要写入密钥、令牌、CPF、银行资料或客户数据。使用环境变量和模拟标识符。

## 1. 编写代码前确定业务

- 项目名称：
- 技术负责人：
- 流程：[ ] Pix → BRL 托管余额 [ ] Pix → 加密资产 [ ] 加密资产 → Pix [ ] Pix 付款
- 余额或付款的收款对象：
- 平台账户余额，还是按客户隔离的子账户：
- 目标资产／网络（须对照目录确认）：
- 用户可见的完成条件：

Pix 托管入账为 BRL，不得显示为已经收到 USDT。直接交付加密资产时，须区分 Pix 已付款与资产交付。对外付款须查询最终状态后才能宣称付款完成。

## 2. 使用现行资料

- [完整手册](https://docs.luniumpay.com/zh/manual)
- [OpenAPI](https://docs.luniumpay.com/zh/openapi.json)
- [沙盒](https://docs.luniumpay.com/zh/sandbox)
- [AI 接入指南](https://docs.luniumpay.com/zh/integrar-com-ia)
- [接入演示](https://luniumpay.com/zh/integrar)
- [服务状态](https://docs.luniumpay.com/zh/status)

- [ ] 核对现行接口、认证、字段与状态。
- [ ] 通过 `GET /keys/me` 查询密钥当前权限、限额与费用。
- [ ] 选择正确目录：`GET /cashin/catalog` 用于交付加密资产；`GET /catalog` 用于加密资产入金后支付 Pix。
- [ ] 使用预览核对通道最低金额，不在代码中写死数值。
- [ ] 按要求处理 memo／tag，并向转入人显示资产与网络。

## 3. 沙盒验收

| 场景 | 预期证据 | 结果／测试引用 |
|---|---|---|
| 主流程 | 到达文档规定的最终状态 | |
| 最低金额 | 所显示金额可接受，低于最低金额时错误明确 | |
| 余额不足 | 拒绝提现／付款，不出现负余额 | |
| 幂等性 | 相同 external_id 与参数不重复执行 | |
| 幂等冲突 | 相同 external_id、不同参数被拒绝 | |
| 超时 | 重试前查询原操作 | |
| 过期 | 不将过期订单显示为已付款 | |
| 暂缓可用／延迟 | 区分总余额与可用余额 | |
| 失败／冲正 | 状态与资金变动可核对 | |
| Webhook | 按手册验证签名与时间戳 | |
| 重复投递 | 同一事件不导致重复入账或交付 | |
| 对账 | 事件缺失时可通过查询恢复状态 | |

各场景可用性取决于流程。使用沙盒文档规定的控制参数，不要假定所有接口采用相同模拟参数。沙盒使用模拟数据，不能证明生产环境真实结算成功。

## 4. 准备生产试运行

- [ ] 通过适用的自助流程确认资格、凭证、权限与条件；需要时联系支持。
- [ ] 密钥只保存在后端，不写入 HTML 或客户端应用。
- [ ] 验证 HTTPS Webhook 与重复事件处理。
- [ ] 重新查询费用、最低金额、通道、暂缓可用规则与可用余额。
- [ ] 确定经授权的小额试运行、正确收款对象及风险敞口上限。
- [ ] 跟踪完整流程并记录对账结果。
- [ ] 明确暂停条件与差异排查负责人。

## 5. 给编程 AI 的指令

实现前读取现行资料，先使用沙盒，仅实现本表选定流程。不得编造接口、字段、状态或付款确认。未经明确授权不得使用真实资金或生产凭证。对每项验收标准，记录测试、结果及待验证项目。区分模拟成功与真实结算，不在证据中公开个人信息或密钥。

## 6. 提供有效的接入背景

说明业务流程、语言／框架、目标资产／网络、预计交易量（如已知）及技术问题。故障时保留 request_id 与 external_id，但不要发送 API 密钥。

[开始接入](https://luniumpay.com/zh/integrar) · 联系邮箱：contato@luniumpay.com