开发者指南 · 接入测试
Pix、资金托管及加密资产 API 测试环境
使用生产密钥前，先验证产品的资金流程。Lunium 测试环境在同一 API 中模拟 Pix 收款单、BRL 余额、加密资产交付与提现、Pix 对外付款及 cash-out。
六种流程与完成标准
凭证 lun_test_ 用于选择模拟环境，基础 URL 仍为 https://api.luniumpay.com。可测试请求、响应、状态、余额及事件，不支付真实 Pix 或转移加密资产。
| 流程 | 创建方式 | 完成标准 |
|---|---|---|
| Pix → BRL 托管余额 | POST /cashin/charge、 destino: "saldo" | paid 及 sent，且入账至正确子账户。 |
| Pix → 加密资产 | POST /cashin/charge、 destino: "cripto" | paid 及 sent；模拟哈希为 sandbox:。 |
| 托管余额 → 加密资产 | POST /saldo/sacar-cripto | 交付 sent ，并核对扣款与费用。 |
| 托管余额 → Pix | POST /payouts | status=sent，包含模拟 E2E 及流水扣款。 |
| 内部转账 | POST /saldo/transferir | 正确账户引用分别记入扣款与入账，总托管金额保持不变。 |
| 外部加密资产 → Pix | POST /cash-outs 并接受报价 | state=COMPLETED；随后模拟充值及 Pix 付款。 |
二维码包含 SANDBOX:NAO_PAGAVEL:，不是银行可付款的 Pix。确认使用 POST /sandbox/cashin/{cashin_id}/pay，不会调用银行、交易所或区块链。
从浏览器或后端开始
通过 引导接入 选择流程，仅填写邮箱即可运行演示。要在项目中实现，可 下载 Node 与 Python 工具包，解压后运行：
node sandbox.mjs all
# 或使用 Python 3.9+，无需额外依赖：
python3 sandbox.py all工具包使用测试人员邮箱，在内存中创建测试密钥（须设置 LUNIUM_SANDBOX_EMAIL，缺少时会提示并停止），执行前验证 GET /keys/me 。也支持通过 LUNIUM_API_KEY 复用仅供测试的凭证，生产密钥会被拒绝。可使用 custody、 cashin、 payout 或 cashout 替换 all ，选择单个流程。
手动调用接口
curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
-H 'Content-Type: application/json' \
-d '{"email":"voce@empresa.com","name":"Minha integração"}' email 为必填项，手册、流程图及接入步骤会发送至该测试邮箱。缺少时响应为 400 email_obrigatorio。将返回的 api_key 保存在后端环境变量中，不放入前端、URL 或 AI 对话。重复使用同一密钥，创建接口有 IP 配额。查询 GET /sandbox 获取当前功能及场景矩阵。
也要测试阻止交易完成的情况
| 场景 | 系统应如何处理 |
|---|---|
delayed / held | 显示等待或冻结，不创建另一笔交易。可用场景因流程而异。 |
expired / payer_mismatch | 结束或核对原收款单，不错误增加余额。 |
settlement_failed | 区分付款已确认与交付失败，核对结果及流水。 |
settlement_uncertain | 保留原交易，不默认已退款。模拟结果核实仅用于测试环境。 |
route_unavailable / provider_unavailable | 显示可处理的错误，不声称发生了实际未创建的交易或扣款。 |
| 余额不足与重复请求 | 余额不足时拒绝支出；重复相同引用及请求体，不重复创建收款单或提现。 |
Cash-in、托管余额及对外付款须传入 sandbox_scenario ，并仅使用测试密钥，场景见 scenarios_by_flow → GET /sandbox。并非所有场景都适用于全部流程；结果不确定的模拟交易可通过 POST /sandbox/operations/{operation_id}/resolve 并传入 {"outcome":"sent"} 或 {"outcome":"failed"}。
核实。Cash-out 使用以下字段的前两位小数选择场景： amount 或 brl_amount： .00 成功、 .01 延迟、 .02 失败、 .03 过期，以及以下指南中的其他场景： 技术场景指南。不要将这些测试触发条件作为生产规则。
模拟事件，真实 HTTP webhook 投递
配置您自己的公开 HTTPS URL，并保存 webhook_secret。测试事件带有 sandbox:true，但 HTTP 投递及签名使用真实 webhook 队列，因此可测试 HMAC 校验、服务器响应、重复及重发。
| 接口 | 可验证内容 |
|---|---|
GET /sandbox/events | 模拟事件，即使未配置回调也可查看。 |
GET /webhooks/deliveries | 投递尝试、接收端响应及结果。 |
POST /webhooks/deliveries/{event_id}/retry | 重发后验证处理仍具幂等性。 |
验证原始请求体、时间戳及 event_id ，遵循 签名契约。须在交易前配置回调，仅配置 URL 不会补发历史事件。
测试能证明什么，哪些仍须生产验证
测试环境验证软件能创建、跟踪及核对模拟流程。报价与目录为模拟快照；生产最低金额、可用性、价格、限额及冻结规则须用真实密钥重新查询。
Cash-in、托管余额、对外付款及转账独立保存，不进入真实资金账本。Cash-out 也会保存，保留 2 小时。新流程每个密钥最多 1,000 笔交易，cash-out 另最多 1,000 笔。可使用 POST /sandbox/reset 并传入 {"confirm":true} 清除模拟状态，已入队的 webhook 历史仍会保留。
不模拟任意合约 DEX 代币、银行动态二维码读取、真实区块链确认或服务商私有规则。测试冻结时间经过压缩；测试完成不证明实际流动性或银行执行。真实 Pix 及加密资产交付属于真实交易，须事先授权金额及收款人。
接入常见问题
测试环境只模拟加密资产兑换 Pix 吗？
不。它覆盖表中六类流程，包括 Pix 充值托管余额或交付加密资产、提现及转账。Pix 入金须通过模拟 API 明确确认付款。
测试时如何收款且无需固定钱包？
发送 destino: "saldo" 用于收款单，余额保持 BRL，仅在之后提取加密资产时选择钱包。
可以使用 ChatGPT 或其他智能体接入吗？
使用 AI 接入指南 及引导页面的需求说明。公共 MCP 连接提供发现及测试演示；通过 ChatGPT 操作生产账户仍须完成对应账户的身份验证。