先选择正确流程

1. 选择交易流程#

BRL 托管余额以巴西雷亚尔计价。 合作伙伴收到 Pix 净额，提现时再选择币种及网络，无需登记固定钱包。一次托管充值不会同时生成 BTC、ETH 和 USDT 余额。

请注意各渠道的默认行为： 调用 API 时，省略 destino 仍表示 cripto。若要收款至托管余额，请传入 destino: "saldo"。在 Telegram 中， /cobrar valor cpf 则默认使用托管余额。

2. 密钥与配置#

基础地址： https://api.luniumpay.com。需要身份验证的接口须传入 X-API-Key ；JSON 请求体还须设置 Content-Type: application/json。密钥可授权账户交易，请仅在您的服务器端使用。

测试环境

curl --fail-with-body https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"email":"voce@empresa.com","name":"Minha integração de teste"}'

请将 voce@empresa.com 替换为测试人员的邮箱： email 为必填项。约一分钟后，LuniumPay 支持团队会向该邮箱发送一次介绍邮件，包含 LuniumPay 简介、三步接入指南、手册及 PDF、流程图，以及 VendaCripto（无需接入 API，即可使用 Pix 买卖加密资产的现成应用）。每个邮箱仅发送一次，并附退订链接。若未提供有效的 email ，响应将为 400，错误为 erro: "email_obrigatorio"。整个流程仍只需一次调用，无需审批或 API 密钥； name 为可选项。

保存 api_key 作为 LUNIUM_API_KEY 保存在服务器环境中。新建测试密钥的前缀为 lun_test_，生产密钥前缀为 lun_live_。旧版 lun_ 密钥仍然有效。

测试环境可模拟 Pix 入金、BRL 托管入账、加密资产交付与提现、Pix 对外付款、内部转账及 cash-out。二维码不可用于真实付款，请通过 POST /sandbox/cashin/{cashin_id}/pay确认。不会调用任何银行、交易所或区块链。有关场景、数据持久化及与生产环境的差异，请参阅 测试环境指南 及 GET /sandbox 。使用托管余额无需固定钱包。

无需固定钱包的生产环境接入

一次调用即可创建，无需人工审批或等待： 生产密钥与测试密钥均可自助取得。API 中仅 name 为必填项，但仍建议填写 email ，以便收到密钥副本。加入 Lunium Partners 为推荐事项，不是技术前提。

curl --fail-with-body https://api.luniumpay.com/keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"Meu projeto","email":"operacao@example.com"}'

请换成您自己的姓名及邮箱。响应会返回 api_key、 key、 limits、 monitor_url 及 Telegram 使用说明。完整密钥仅在创建时显示一次。 monitor_url 是项目监控面板；该链接也属于项目私密信息，请妥善保管。

新建生产密钥默认启用托管余额及 Pix 对外付款。实际应以 您的 密钥状态为准，请查询 payout.enabled → GET /keys/me 及 custodia_ativa → GET /saldo。

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

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

通过以下接口配置 HTTPS webhook 接收端： PATCH /keys/me 并传入 webhook_url；请保存响应返回的 webhook_secret 。 settlement_address 用于可选的 Polygon 直接交付，不是托管余额的必要条件，也不决定之后的提现地址。

请重复使用同一测试密钥；创建密钥受 IP 限流约束。遇到 429时，须按指定时间等待。不要为每笔交易新建密钥。

3. Pix 收款至托管余额#

创建收款单

请先查询 GET /cashin/limits?payer_tax=CPF_OU_CNPJ，并使用项目密钥验证身份。证件必须属于 实际支付 Pix 的付款人； customer_ref 则用于标识您系统中的子账户，两者含义不同。

示例金额为 R$ 50.00。请替换证件及引用标识，并选择该付款人额度内的金额。在生产环境调用会创建真实收款单。

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":5000,
    "payer_tax_number":"00000000191",
    "destino":"saldo",
    "customer_ref":"cliente-42",
    "external_id":"deposito-cliente42-001"
  }'

此流程不要传入 payout_address 。若未提供 customer_ref，入账将归属于该密钥自身的余额，称为 主账户；提供引用标识后，则仅归属于对应子账户。

保存 cashin_id 及 external_id。请向客户展示返回的 qr_copypaste、 qr_image_url （如有）、金额及 expires_at 。生成二维码仅表示已创建收款单，不代表资金已经到账。

确认入账

使用 GET /cashin/{cashin_id}/status 或 webhook 事件，并分别跟踪 两种状态：

仅在以下状态下视为入账 / 交付完成： cashin.settled ，或通过查询 status: "paid" 且 settlement_status: "sent"确认。使用托管余额时，还须通过 GET /saldo?customer_ref=cliente-42 及流水核对金额与可用性。已登记的入账仍可能被冻结，不能将 total_cents 当作 disponivel_cents。

depix_received_cents 表示从结算服务商收到、尚未扣除密钥充值费用的金额。该字段沿用旧名称，不代表客户最终净入账金额。对账请使用余额流水。

充值费用与资金可用性

GET /saldo 会列明 deposito_fee_bps、 deposito_fee_fixed_cents、 carencia_horas、 carencia_ate、 retencao_acima_cents 及 proximas_liberacoes。 100 bps = 1%。新充值适用 deposito_fee_bps=0 及 deposito_fee_fixed_cents=100，不收取合作伙伴佣金。

以下三个概念相互独立：

held_hours 及 hold_hours 并非同义字段。 即使收款单显示 held: false ，仍可能处于本地冻结期。不能仅凭该布尔值承诺资金立即可用。

并非所有合作伙伴均适用统一的 24 小时等待期。即时余额密钥有独立规则，但仍受付款人、收款单及其他冻结影响。须结合创建响应、状态及余额判断；等待期内提现被拒绝时返回 423 及资金释放时间。

付款人限额

GET /cashin/limits 提供即时到账额度、是否允许冻结收款、已用额度及该证件下次释放时间。密钥条件可能调整分级规则。查询仅供参考，创建时仍重新校验，包括即时释放的托管收款。

allow_hold: false 会拒绝需要按付款人限额规则冻结的收款单。它不会关闭其他合同规则或之后发生的资金冻结。省略此字段即允许适用的冻结。付款前须向客户展示相关条件。

实际最低金额还取决于费用及服务商。不要将 R$ 1.00 用作所有接口通用的测试金额，也不要把全局最低金额误认为某个接口实际接受的最低金额。

8. 外部加密资产兑换 Pix#

该流程接收外部钱包的加密资产。若要使用托管余额支付 Pix，请使用 /payouts。

1. 查询 GET /catalog，即 加密资产入金目录；它与 /cashin/catalog。
2. 可选用 POST /cash-outs/preview 进行不创建订单的预估。
3. 通过以下接口创建报价： POST /cash-outs。
4. 向客户展示数量、网络、BRL 净额、收款人及有效期。通过以下接口接受报价： POST /cash-outs/{cashout_id}/accept。
5. 之后才向客户展示 deposit_address，该 deposit_tag （如有）及返回的精确金额。
6. 持续查询 GET /cash-outs/{cashout_id} 或跟踪 webhook，直至最终状态。

以下示例使用 测试环境，以及 LUNIUM_API_KEY 测试数据：

curl --fail-with-body https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "asset":"USDT",
    "network":"polygon",
    "amount":"10.00",
    "pix_key":"teste@example.com",
    "pix_key_type":"email",
    "external_id":"sandbox-cashout-001"
  }'

发送 amount （加密资产数量） 或 brl_amount （期望的 BRL 金额），须为以点作小数分隔符的字符串。两者不能同时传入。创建时可能返回 200 （生产环境）或 201 （测试环境）；请按接口契约接受相应的 2xx 响应。 cashout_id 是接口返回的标识，不是由接入方自行生成的 ID。

生产环境如提供 refund_address ，须为客户控制、符合实际退款网络的有效钱包。交易所提币来源可能为共用钱包，不能默认用于退款。未提供时，仅在卖出失败需要退款后补充。

状态与凭证

并非所有接口都会经历全部阶段。 timeline、 confirmations 及 confirmations_required等字段（如有）可辅助跟踪。充值确认不代表 Pix 已付款完成。

遇到 COMPLETED，请核对 pix_e2e、 pix_paid_at、 receipt_url、 receipt_pdf_url 及 verify_url（如有），并使用接口返回的链接。公开查询接口 GET /v1/verificar/{e2e} 用于核验已知的 Pix 付款，不是对所有加密资产交易的通用证明。

发生退款时，请跟踪 REFUNDED 及 refund_tx_hash。退款金额及时间取决于交易已到达的阶段，以及服务商的资金返还情况。不要承诺任何失败均可全额、自动或在固定时间内退款。逾期或金额不符的充值须继续跟踪同一订单，不得将其地址用于其他交易。

收款人查询与二维码付款

GET /pix/keys/lookup?key=...&type=... 仅为辅助查询，可能返回 200 并传入 available: false、 verified: false、 verification_status: "not_performed" ，且姓名为 null。此时应显示“收款人身份未核验”，不得编造姓名；查询不可用也不等于付款不可用。测试环境的收款人资料为虚构数据，并带有 source: "sandbox"。

br_code 的可用性独立判断。在生产环境创建时，可能因 503 br_code_indisponivel被拒绝，即使预览或测试环境接受该二维码，也不能承诺 Copia e Cola 付款始终可用。启用后，该字段替代 pix_key、 amount 及 brl_amount，且须有确定金额及兼容资产。

新建的加密资产兑换 Pix 订单适用运营预留款： 每笔 R$ 1.00，适用于所有合作伙伴，已计入报价，并列于 reserve_brl。其 USDT 等值金额按当时报价计算，创建后固定在订单中： pix_key_reserve_usd 用于 Pix 收款标识付款，或 copia_e_cola_buffer_usd 用于 Copia e Cola。这些字段表示换算后的金额，不是另收 US$ 1；不要将预留款再次加到总额中。比例费用及服务商成本仍包含在报价中，二维码仅按其精确金额支付。付款完成后，运营预留款不予退还；临时余额预留则是另一项机制。已有订单保留原约定金额，DePix/Liquid 按独立的 BRL 费率执行。

仅使用该交易目录列出的网络。即使某些需要 memo 的网络出现在交付目录中，也可能不支持 cash-out。不要将某一产品的网络列表直接用于另一产品。

12. 测试环境与接入测试#

运行 node sandbox.mjs all 或 python3 sandbox.py all 否 工具包。示例会核验测试密钥、模拟 Pix 付款，并覆盖托管余额、USDC/Base 提现、Pix 对外付款、BTC、USDC/Polygon 及 cash-out 流程。Cash-in / Pix 对外付款使用 sandbox_scenario；资金冻结、退款、交付失败及结果不确定的场景，详见 指南。 GET /sandbox/events 可用于检查事件；已配置的回调使用产品自带的签名队列。价格与时间均为模拟值，不代表合作交易所的实际条件。

测试环境 cash-out 场景由 amount 的前两位小数决定：

测试订单仅为临时数据，不代表真实充值。测试环境不能证明生产环境的实际时效、价格、服务商可用性或托管入账结果。Cash-in 与余额功能须覆盖文档列出的模拟接口和场景。之后开展真实试点时，应使用该接口及付款人允许的最低金额，并事先确认金额及收款人已获授权。

15. 上线检查清单#

• 密钥保存在服务器端，测试环境与生产环境分离。
• /keys/me 及 /saldo 已按密钥及各客户范围核对。
• 托管收款使用 destino: "saldo"；只有在提取加密资产时才选择钱包。
• 界面读取当前目录及限额，展示资金冻结条件，并在需要时要求填写 memo。
• 已持久化保存 ID；重试保持相同请求体及 external_id；已测试超时后的恢复流程。
• Webhook 验证 HMAC 与时间戳，按事件去重，并在超时前响应。
• 对账明确区分 Pix 已支付、入账已登记、资金可提现及加密资产已交付。
• 处理余额、等待期、接口、费用、服务商及密钥错误时，不重复执行交易。
• Telegram 由身份明确的管理员绑定，提现须在正确的会话及项目中确认。
• 接入验收覆盖成功、资金冻结、过期、失败、重发及响应丢失后的查询。

技术支持： @luniumB2B · contato@luniumpay.com。请关注 服务状态 及 合作伙伴渠道。请求支持时，请提供交易 ID 及 request_id （如有），不要分享完整 API 密钥。