Lunium 接入

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

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

## 立即测试

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

如需测试自己的后端，请 [下载工具包](https://docs.luniumpay.com/zh/starter/lunium-starter.zip)：

```
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` 可选择特定流程。

## 测试流程与完成条件

| 流程 | 创建 | 确认与跟踪 | 成功条件 |
| --- | --- | --- | --- |
| Pix → BRL 托管余额 | `POST /cashin/charge`、 `destino: "saldo"` | `POST /sandbox/cashin/{cashin_id}/pay`，随后 `/cashin/{cashin_id}/status` 及 `/saldo` | `status=paid`、 `settlement_status=sent`；确认资金在正确的子账户中可用 |
| Pix → BTC、USDC 或测试目录中的其他通道 | `POST /cashin/charge`、 `destino: "cripto"`、 `asset`、 `chain`、 `payout_address` | 使用相同的 Pix 模拟确认及买入查询流程 | `paid` 及 `sent`；交易哈希以 `sandbox:`开头，不存在真实链上交易 |
| 托管余额 → 加密资产 | `POST /saldo/sacar-cripto`、 `amount_cents`、 `tax_number`、 `asset`、 `chain`、 `payout_address` | `/cashin/{cashin_id}/status` | `paid` 及 `sent`；扣款包括 `fee_cents` |
| 托管余额 → Pix | `POST /payouts`、 `amount_cents`、 `pix_key` | `GET /payouts/{payout_id}` | `status=sent`；模拟 E2E 使用虚构 ISPB `00000000` |
| 内部转账 | `POST /saldo/transferir`、 `from_customer_ref`、 `to_customer_ref`、 `amount_cents` | `/saldo/extrato`、 `/saldo/clientes`、 `/saldo/consolidado` | 原子扣款与入账；托管总额保持不变 |
| DePix／Liquid → Pix | `POST /cash-outs`、 `asset: "DEPIX"`、 `network: "liquid"`、Pix 收款信息，以及可选的 `refund_address` | `POST /cash-outs/{cashout_id}/accept`，随后 `GET /cash-outs/{cashout_id}` | `state=COMPLETED`；入金和 Pix 付款均为模拟 |
| 外部加密资产 → Pix | `POST /cash-outs`，随后 `POST /cash-outs/{cashout_id}/accept` | `GET /cash-outs/{cashout_id}` | `state=COMPLETED`；入金同样为模拟 |

资金托管不要求固定钱包；余额币种为 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`。

| 场景 | 处理结果 |
| --- | --- |
| `success` | 成功；省略时的默认场景 |
| `delayed` | 暂缓处理约 30 秒后继续 |
| `held` | 仅限托管入金：资金暂不可用 30 秒，之后释放为可用余额 |
| `expired` | 尝试模拟付款时，买入订单过期 |
| `payer_mismatch` | 因付款人不符退回买入款项，不入账、不交付资产 |
| `refunded` | 买入退回且不入账；付款退回并仅冲正一次 |
| `failed` | 付款失败；付款流程仅退回已扣金额一次 |
| `settlement_failed` | 付款可能已确认，但资产交付失败；提现退回扣款及费用 |
| `settlement_uncertain` | 交付保持 `incerto`；付款继续保持 `processing`。完成对账前不冲正 |
| `route_unavailable` | 拒绝创建，不扣款 |
| `provider_unavailable` | 模拟 HTTP 503，不创建操作；只要场景持续，后续请求仍会被拒绝 |

如需处理结果不确定的操作， **仅在测试环境中**调用 `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`。请按[手册](/zh/manual#webhooks)验证原始请求体的 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 并由合作交易所发送加密资产的试运行属于真实交易，必须使用已授权的金额与收款对象。沙盒通过可以验证软件接入，不能保证服务商的流动性或执行结果。

简体中文版：2026年10月17日 · 当前 API：1.44.7。历史修订日期按原记录保留。