沙盒：Pix、资金托管与加密资产

使用相同的基础地址 https://api.luniumpay.com ，搭配 lun_test_密钥。所有财务操作均为模拟操作。入金二维码包含 SANDBOX:NAO_PAGAVEL:，不是银行 Pix 支付码。请通过模拟 API 确认付款。提现不会发送到合作交易所或区块链。

立即测试

打开 引导式接入，选择流程、提供邮箱并运行演示。通过公开 AI 连接测试时，使用 lunium_start_sandbox_demo 并传入 flow 等于 custody、 cashin、 payout 或 cashout，并提供随机且固定的 request_id ，以及测试人员的 email （MCP 工具中为选填，但强烈建议提供：LuniumPay 会向本人发送一次接入指南，包括服务介绍、手册、流程图与后续步骤。未提供邮箱时仍应创建密钥，之后可通过 lunium_contact补充）。随后调用 lunium_get_sandbox_demo；该工具可在确认入账后，创建既定测试流程中的模拟提现。

如需测试自己的后端，请 下载工具包：

node sandbox.mjs all
# 或使用 Python 3.9+，无需额外依赖：
python3 sandbox.py all

工具包会使用测试人员邮箱，在内存中创建密钥。请设置 LUNIUM_SANDBOX_EMAIL=voce@empresa.com；未设置时，工具包会显示明确提示并停止。操作前，工具包会确认 GET /keys/me ，并拒绝生产凭证。也可通过 LUNIUM_API_KEY 传入仅限测试环境的密钥。工具包不会打印凭证。使用 custody、 cashin、 payout 或 cashout 替换 all 可选择特定流程。

测试流程与完成条件

资金托管不要求固定钱包；余额币种为 BRL。仅在提现时选择币种、网络、地址与 memo。工具包覆盖 BTC 原生网络、Polygon 上的 USDC，以及 Base 上的 USDC 提现；测试目录还提供其他明确列出的通道。买入及提现使用 chain；卖出使用 network。

测试 Pix → DePix／Liquid

使用 lun_test_ 密钥，并通过 GET /keys/me 确认 key.sandbox=true。在 GET /cashin/catalog?asset=depix&network=liquid 的 instant 中可找到 DEPIX/liquid 通道。此测试覆盖 Pix → DePix；从托管余额提现至 Liquid 仍不可用。

提交 asset: "depix"、chain: "liquid"、delivery_mode: "split"，并在 payout_address 中填写 Liquid 地址。请将下方 SEU_ENDERECO_LIQUID 替换为自己的钱包地址。示例 CPF 为虚构数据，仅供沙盒使用。该地址不会收到资产：此流程不使用 Liquid 主网或测试网。

创建收款单前，先用相同参数调用 POST /cashin/preview。除密钥另有约定外，DePix 买入基础费率为 2% + R$1.00，每笔 Pix 最低收费 R$2.00。先扣固定费用，再计算比例费用：按标准策略，R$500.00 可兑换 489.02 DePix。请核对返回的 net_cents 和 fee_total_cents；USDC／USDT 买入费率及合作伙伴佣金不会叠加到 DePix 交易上。

curl --fail-with-body https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"amount_cents":50000,"payer_tax_number":"12345678901","destino":"cripto","asset":"depix","chain":"liquid","delivery_mode":"split","payout_address":"SEU_ENDERECO_LIQUID","external_id":"sandbox-depix-001"}'

# 使用创建时返回的 cashin_id：
curl --fail-with-body -X POST "https://api.luniumpay.com/sandbox/cashin/$CASHIN_ID/pay" \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' -d '{}'

curl --fail-with-body "https://api.luniumpay.com/cashin/$CASHIN_ID/status" \
  -H "X-API-Key: $LUNIUM_API_KEY"

通过 /sandbox/cashin/{cashin_id}/pay 模拟确认付款，并查询直至 paid 与 sent。API 和 cashin.paid／cashin.settled Webhook 保留 delivery_mode、net_cents 和 fee_total_cents。交易哈希以 sandbox: 开头，settlement_tx_url 为 null。不要使用银行支付二维码：不会发生真实 Pix 付款或链上发送。

测试 DePix／Liquid → Pix

使用 asset: "DEPIX"、network: "liquid" 及 lun_test_ 测试密钥。查询 GET /catalog?asset=DEPIX&network=liquid，在 fast 中找到通道。提交 amount 指定 DePix 数量，或提交 brl_amount 按目标 Pix 金额反向报价，不得同时提交两者。费用扣除前，1 DePix = R$1.00；请始终核对实际返回金额。

卖出使用该密钥独立的现行费率，可通过 fee_bps、 fee_fixed_cents、 fee_total_cents 及 net_cents查询。按标准卖出费率 1.5% + R$1.00，转入 100.00 DePix 可获得 R$97.51 的 Pix 付款。DePix 买入费率另行计算。

创建订单时提供 Pix 收款键。 refund_address为客户确认的 Liquid 退款钱包，自 API 1.44.0 起可选。如未提供，而卖出订单需要退款，则订单会停留在 AWAITING_REFUND_ADDRESS ，直到通过 POST /cash-outs/{cashout_id}/refund-address补充钱包。对于邮箱、电话或随机类型的 Pix 收款键， payee_tax_number 为必填项；对于 CPF／CNPJ 类型，证件信息来自收款键本身。示例使用虚构收款人和 CPF。请将 SUA_CARTEIRA_LIQUID_DE_DEVOLUCAO 替换为有效的 Liquid 地址，或删除该字段；沙盒不会向该地址发送任何资产。

# 预览：不创建订单，无需收款人或退款钱包。
curl --fail-with-body https://api.luniumpay.com/cash-outs/preview \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"asset":"DEPIX","network":"liquid","amount":"100.00"}'

# 创建模拟报价：
curl --fail-with-body https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"asset":"DEPIX","network":"liquid","amount":"100.00","pix_key":"depix@example.invalid","pix_key_type":"email","payee_tax_number":"12345678901","refund_address":"SUA_CARTEIRA_LIQUID_DE_DEVOLUCAO","external_id":"sandbox-depix-pix-001","sandbox_scenario":"success"}'

# 使用创建时返回的 cashout_id：
curl --fail-with-body -X POST "https://api.luniumpay.com/cash-outs/$CASHOUT_ID/accept" \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' -d '{}'

curl --fail-with-body "https://api.luniumpay.com/cash-outs/$CASHOUT_ID" \
  -H "X-API-Key: $LUNIUM_API_KEY"

接受报价后，模拟入金会自动开始。 deposit_address 以 SANDBOX:LIQUID:NAO_ENVIAR: 开头，并非可转账地址。不要发送资产，也无需查找测试网：模拟在 API 内完成。持续查询订单直至 COMPLETED，通常在接受报价后约 14 秒。期间状态依次为 AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED。最终的 pix_e2e 使用虚构 ISPB 00000000；验证结果也会标明沙盒。不会发生银行付款，不会生成真实银行凭证，也不存在 Liquid 链上交易。

事件包括 cashout.awaiting_deposit、 cashout.deposit_detected、 cashout.processing 及 cashout.completed。发生退款时，还会产生 cashout.refunding 及 cashout.refunded；退款哈希以 sandbox:开头。请在创建操作前配置回调地址，或查看 GET /sandbox/events。

测试 DePix → Pix 时，可选择 sandbox_scenario： success、 delayed （约 54 秒）、 failed、 expired （创建报价后超过五秒不接受）、 refunded、 settlement_uncertain、 provider_unavailable （返回 503，不创建订单）、 route_unavailable 或 no_deposit （到期前无入金）。显式指定的场景优先于下方按金额小数部分触发的场景；未显式指定时，这些触发规则仍有效。

测试未提供钱包的退款时，创建报价时省略 refund_address，选择 refunded 场景。接受后，订单经过 REFUNDING，停留在 AWAITING_REFUND_ADDRESS，并产生 cashout.awaiting_refund_address 事件；响应包含 refund_amount、refund_asset 和 refund_network。通过 POST /cash-outs/{cashout_id}/refund-address 提交 Liquid 钱包后，订单进入 REFUNDING，约四秒后进入 REFUNDED，退款哈希以 sandbox: 开头。重复相同钱包返回 200；更换钱包返回 409 refund_address_imutavel。

遇到 settlement_uncertain，订单将停留在 PROCESSING。通过 POST /sandbox/operations/{cashout_id}/resolve 及 {"outcome":"sent"} 模拟成功完成，或通过 {"outcome":"failed"} 模拟退款（约四秒后进入REFUNDING → REFUNDED ；如未提供 refund_address，订单将停留在 AWAITING_REFUND_ADDRESS，与上述情况相同）。重复相同的处理结果或接受请求不会重复执行操作。若复用 external_id 时更改收款人、证件、钱包、金额或场景，返回 409。可通过以下接口找回原操作意图： GET /cash-outs?external_id=...。

此 DePix 流程使用 Pix 收款键； br_code 属于 USDT／USDC 通道的能力。 sandbox_scenario 及 /sandbox/operations/.../resolve 不接受生产密钥。另请参阅 GET /sandbox，在 scenarios_by_flow.cashout_depix。

无需钱包，将收款记入托管余额

通过 POST /keys/sandbox 创建密钥，提交测试人员本人的 email（必填；手册、流程图与接入步骤将发送至该邮箱）。将返回的 api_key 保存在后端环境变量 LUNIUM_API_KEY 中。执行下列请求前，通过 GET /keys/me 确认 key.sandbox=true。本例证件为虚构数据，仅供沙盒使用。

curl --fail-with-body https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"amount_cents":100000,"payer_tax_number":"12345678901","destino":"saldo","customer_ref":"cliente-teste","external_id":"sandbox-deposito-001"}'

保存 cashin_id。模拟付款时调用：

curl --fail-with-body -X POST "https://api.luniumpay.com/sandbox/cashin/$CASHIN_ID/pay" \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' -d '{}'

查询 /cashin/{cashin_id}/status，等待 paid 且 sent，通常约六秒。随后查询 /saldo?customer_ref=cliente-teste。入账为扣除密钥费用后的净额，不应与收款单毛额直接比较。重复模拟付款不会重复入账。

买入、资金托管与付款的确定性测试场景

创建操作时提交 sandbox_scenario。各流程支持的场景矩阵见 GET /sandbox。

如需处理结果不确定的操作， 仅在测试环境中调用 POST /sandbox/operations/{operation_id}/resolve 并传入 {"outcome":"sent"} 或 {"outcome":"failed"}。重复提交相同处理结果具有幂等性。接口要求操作属于当前密钥，且结果处于不确定状态。生产环境不存在模拟确认。

还应测试无效请求体、各币种与网络最低金额、余额不足、并发支出、账户受限、其他密钥的 ID，以及 external_id 复用时更改参数的情况。重试应保持同一操作意图和 external_id ；参数不一致将被拒绝。收款单与加密资产提现共用引用标识命名空间。超时后，可通过 ID 或按以下字段筛选列表找回操作： external_id。

加密资产 → Pix 测试场景

卖出流程继续按 amount 的小数部分触发测试场景（反向报价则使用 brl_amount ）： .00 成功、 .01 延迟、 .02 失败、 .03 过期； .04 限额； .05 延迟； .06 服务商拒绝； .07 首次接受报价返回 503，第二次成功； .08 付款人限额。预览不会创建记录。切勿向模拟器返回的地址发送加密资产。

USDT/USDC 钱包

测试密钥使用钱包模拟器，与生产环境采用相同的 /carteira-usdt 接口、请求结构和状态，但不操作真实资金。入金返回虚构地址 SANDBOX-NAO-ENVIE-FUNDOS，约 15 秒后自动模拟入账，切勿转入资金。测试 Pix 通常约 15 秒完成，返回测试 E2E 及 receipt_url: null。金额小数部分触发规则：入金 .02 不到账，约一分钟后过期；Pix .01 在 revisao 持续约 40 秒；.02 在发送前失败并释放预留资金；.05 约需两分钟。wallet.deposit_credited、wallet.payment_completed 及 wallet.payment_failed Webhook 均带有 sandbox: true。

真实 HTTP Webhook，模拟业务事件

通过 PATCH /keys/me 设置 webhook_url，提供由您控制的公开 HTTPS 地址，并妥善保存 webhook_secret。沙盒采用与产品相同的投递队列和签名机制，事件带有 sandbox:true。请按手册验证原始请求体的 HMAC 和时间戳，并按 event_id 去重。模拟事件通过真实 HTTP 投递，不代表真实资金结算。

使用 GET /sandbox/events 可检查已生成的事件，即使未配置回调地址也可查询。 GET /webhooks/deliveries 显示投递尝试； POST /webhooks/deliveries/{event_id}/retry 用于重发。配置回调前产生的事件不会自动补发；请创建新的测试操作，或调用 /webhooks/test。买入发布 cashin.paid、 cashin.settled 或相应失败事件。资金暂缓可用／释放及转账各有专属事件。付款发布最终结果；卖出发布进度与完成事件。

持久化、价格与测试边界

买入、资金托管、付款与内部转账的数据独立于真实账本持久化，重启后仍保留。卖出数据同样持久化，保留两小时。新流程每个密钥最多 1,000 笔操作，卖出最多 1,000 笔。 POST /sandbox/reset 并传入 {"confirm":true} 仅清除当前密钥的模拟状态；已进入投递队列的 Webhook 保留其历史记录。

报价与目录为响应中标明的模拟快照。生产环境的价格、最低金额、可用性和风控判断可能变化。沙盒不会调用合作交易所、银行或钱包。测试付款的服务商费用固定为 100 分，并通过 /saldo返回；不代表真实费率。按 CPF 分级的规则不查询真实个人历史； /cashin/limits 会说明该差异。暂缓可用测试使用压缩后的时间。

模拟器覆盖目录中明确列出的资产，不模拟任意合约地址的 DEX 代币、银行动态二维码读取、区块链网络或各服务商私有策略。在生产环境中，请使用生产密钥重新查询 /keys/me、 /saldo、限额与目录。真实支付 Pix 并由合作交易所发送加密资产的试运行属于真实交易，必须使用已授权的金额与收款对象。沙盒通过可以验证软件接入，不能保证服务商的流动性或执行结果。