接入手册

当前费率

2026年10月15日费率政策：余额充值每笔 R$ 1.00，无比例费用及佣金；直接购买为 3.3% + R$ 1.00；BRL 余额兑换加密资产为 3.3%，不再收取固定费用；BRL 余额通过 Pix 提现为 1.5%。合作伙伴佣金另计于购买及转出费用。参考汇率采用 Binance 卖一价（ask），不另加溢价。适用的网络和处理成本将在预览中列明。

saque_cripto_conversao_fee_bps：兑换费率； saque_cripto_fee_bps=0； saque_cripto_conversao_fee_fixed_cents=0。

1. 选择交易流程#

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

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

2. 密钥与配置#

欢迎加入 Lunium Partners，即官方接入者社区。 强烈建议从接入初期就加入社区。我们在此分享运行通告、维护通知及 API 变更，合作伙伴也可互相交流。 了解如何结合社区、专属群组及监控工具开展工作。

基础地址： 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 。使用托管余额无需固定钱包。

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

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时，须按指定时间等待。不要为每笔交易新建密钥。

恢复监控访问并管理凭证

私密监控 以只读方式展示项目情况，而 API 密钥 可授权执行交易。监控链接、API 密钥及 webhook 签名密钥是不同的凭证；恢复其中一项，不会恢复其他项。

若丢失监控链接，可申请将其发送至生产密钥登记的邮箱：

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

该接口无需 API 密钥。出于账户隐私保护，响应 200 {"ok":true,...} 为统一格式，不会确认账户是否存在或邮件是否送达。请检查收件箱及垃圾邮件。遇到 429时须等待，不要自动连续提交。如登记邮箱有误或无法访问，请联系项目的人工支持人员核验并恢复访问。

若仍持有密钥， GET /keys/me 会返回 monitor_url。若链接泄露，请使用 PATCH /keys/me 并传入 {"rotate_monitor_token":true} 使旧链接失效，并仅向授权团队分发新链接。旧链接立即失效，但 API 密钥及 webhook 签名密钥不会改变。

完整 API 密钥仅在创建时显示一次，此流程不会重新显示或恢复密钥。若密钥丢失或泄露，请联系支持团队处理替换 / 撤销及账户连续性。不要假设新建密钥后，余额、收款单或绑定关系会自动转移。更换 webhook 签名密钥请参阅 专门流程。

现有监控与控制台演进

本次修订所列的跟踪方式包括私密监控、事件流及接口契约中的公开接口。额外控制台功能及 webhook 多接收端能力，须在正式发布并经生产验证后再接入。请按文档在以下接口配置接收端： PATCH /keys/me；不要根据开发预告推测存在公开的多接收端 API，或登录 / 2FA 接口。

Fable 及其他 AI 接入工具请核对 经核查的版本及接口清单 ，并结合 OpenAPI使用。如有差异，请记录涉及的资料来源及操作，暂停该能力的实现直至澄清，不要自行编造接口补齐流程。

合作伙伴新控制台

合作伙伴控制台位于 parceiros.luniumpay.com，使用同一邮箱及密码登录；也可使用邮件验证码或 Google 账户。尚未开通访问权限的用户可使用 创建账户。控制台供团队操作及跟踪项目，系统接入仍通过项目密钥调用 API。控制台页面使用登录用户的会话，不属于 API 公开接口契约。

• 首页： 按时间范围查看业务概览（Pix 收款、加密资产卖出、Pix 付款、加密资产提现及佣金）、收款单 / 卖出订单 / 付款状态，以及日历。
• 凭证： 查看卖出订单、Pix 付款及收款单的 PDF 凭证。
• 使用加密资产付款： 可搜索并选择稳定币（所有支持网络上的 USDT、USDC，以及 DePix）和 30 种主要加密资产，并显示图标。仅在卖出交易失败时才要求填写退款钱包（退款钱包).
• USDT/USDC 钱包： 充值时展示地址二维码及 1 小时倒计时，可使用余额支付 Pix。详情参阅 USDT/USDC 钱包。
• 佣金： 提现最低 US$ 10。
• 通知： 通过通知铃铛查看项目动态，并通过 Telegram 及邮件接收各笔交易通知。
• 团队： 角色包括所有者、财务、操作员、开发者及只读成员；双重验证位于 我的访问权限。
• 我的访问权限： 点击 退出其他会话 可退出其他设备上的控制台会话，并保留当前会话。无密码账户（通过验证码或 Google 登录）可用验证器代码或恢复代码关闭双重验证。更改密码时，当前密码每小时最多允许 10 次错误尝试；密码被更改、创建或重置时，系统均会发送邮件通知。
• Webhook： 立即重发 可在控制台中重新投递该事件。
• 可读性： 提高对比度、增大字号，统一各页面的 Pix 拼写，保持页面标题与菜单一致，并按所选界面语言提供清晰的错误提示。

新账户激活。 若邮箱尚未注册账户，通过机器人或邮件链接、或项目密钥激活控制台时，该邮箱会收到 6 位数验证码。验证码有效期为 30 分钟，最多允许 5 次尝试； 重新发送验证码 可在 1 分钟后生成新验证码，最多 5 次，仅最新验证码有效。已有账户的邮箱仍使用账户密码确认。

通过验证码或 Google 登录的受邀用户。 无密码账户可这样接受邀请：先用受邀邮箱登录控制台，再次打开邀请链接；保持登录后，即可一键接受。

控制台安全规则：

• 仅 所有者 可查看 Telegram 绑定链接及代码、断开会话或生成新代码。当成员失去访问权限、不再是所有者，或会话被断开时，绑定代码会自动更新。
• 某位成员不再是所有者时，其他所有者会收到邮件，提醒其前往 通知检查已连接的 Telegram 会话；这些会话会保持连接，直至所有者主动断开。
• 已连接的 Telegram 会话也可通过机器人查询余额及执行资金操作：私聊由绑定者操作，群组由管理员操作。仅连接可信的会话。
• 在控制台中，仅 所有者 可修改结算钱包（settlement_address）及子佣金（partner_fee_bps、 partner_cashout_fee_bps、 partner_saque_fee_bps）。 开发者 仍可调整 webhook、名称及监控。
• 会话有效期为 12 小时，使用控制台时会续期，但自登录起最长不超过 7 天。会话 cookie 受到保护，页面启用了内容安全策略。

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 用作所有接口通用的测试金额，也不要把全局最低金额误认为某个接口实际接受的最低金额。

4. 余额、子账户与流水#

充值、查询及提现须使用完全相同的 customer_ref ，最长 80 个字符。该引用用于隔离余额，但 API 密钥仍可操作其所有子账户；您的系统还须自行实现用户权限控制。

内部转账不生成 Pix，使用 POST /saldo/transferir：

{
  "amount_cents":1000,
  "from_customer_ref":"cliente-42",
  "to_customer_ref":"casa",
  "external_id":"transferencia-interna-001",
  "descricao":"Transferência autorizada pelo cliente"
}

casa 表示不属于任何子账户的主账户余额。仅可转移可用余额，来源子账户的等待期仍然有效。该接口余额不足时返回 409 saldo_insuficiente；提现接口通常返回 402。

5. 以加密资产形式提取余额#

1. 查询 GET /saldo ，并须使用正确的账户范围。
2. 查询 GET /cashin/catalog：这是 交付目录，也用于托管余额提现。
3. 请提供以下字段组成的有效组合： instant 及 convert 并传入 entregavel: true。余额提现须排除 Liquid/DePix，此流程不支持这两项。
4. 选择币种、网络、收款钱包，以及需要时的 memo/tag。每次提现可使用不同钱包。
5. 发送 POST /saldo/sacar-cripto ，并使用以下接口跟踪返回的 cashin_id ： GET /cashin/{cashin_id}/status。

以下请求体仅为示例，发送前请替换钱包及证件：

{
  "amount_cents":10000,
  "asset":"usdt",
  "chain":"polygon",
  "payout_address":"0x1111111111111111111111111111111111111111",
  "tax_number":"00000000191",
  "customer_ref":"cliente-42",
  "external_id":"saque-cripto-cliente42-001"
}

amount_cents 表示 待兑换的 BRL 金额，而非加密资产数量。证件字段 tax_number 属于提现客户。需要 memo 的网络须根据收款钱包要求传入 payout_tag ，并遵守目录中的 memoRequired 。也支持以下别名： memo、 tag 及 destination_tag 。

响应会返回 fonte: "saldo"、 destino: "cripto"、 fee_cents 及 debited_cents。扣款包含本金及平台提现费用；最终加密资产数量还考虑兑换与交付成本，不能仅用扣款金额除以市场汇率计算。

GET /saldo 会列明 saque_cripto_fee_bps。 POST /cashin/preview 可辅助查询兑换情况及该路由的最低金额，但 不是提现完整扣款的预览。Telegram 使用的提现预览为内部功能，不存在公开的 /saldo/sacar-cripto/preview。

可选字段 max_debited_cents 可限制 BRL 扣款总额。若总额超过上限，API 将返回 409 taxa_alterada。该字段不会锁定汇率，也不保证收到最低数量的代币。

不要笼统宣称“支持所有加密资产”。实际选项为当前目录中可交付的币种 / 网络组合，仍受最低金额、维护及地址校验约束。 stale: true 表示备用目录，确认前须重新校验。

6. 通过 Pix 提取余额#

POST /payouts 会在发送 Pix 前预留并扣除主账户或子账户的可用余额。须具备 payout.enabled、已启用托管功能，以及足够覆盖本金和费用的余额。

{
  "amount_cents":5000,
  "pix_key":"recebedor@example.com",
  "pix_key_type":"email",
  "tax_number":"00000000191",
  "customer_ref":"cliente-42",
  "external_id":"saque-pix-cliente42-001"
}

请将 Pix 收款标识及证件替换为实际收款人的资料。 tax_number 须包含有效的 CPF 或 CNPJ，适用于邮箱、手机号及随机类型的 Pix 收款标识。若收款标识本身为有效 CPF/CNPJ，API 将直接提取证件；如另行提供，必须一致。 beneficiary_name 仍为可选项，且不能证明账户归属。11 位数字的收款标识须指定 pix_key_type: "cpf" 或 "phone"；手机号须包含国际区号，例如 +55。

此流程仅使用通过 Pix 收到的 BRL 余额。 funding_source 为可选项，仅接受 pix_brl。每笔 Pix 最高为 600000 分（R$ 6,000.00），还须遵守账户较低的限额，另计适用费用。

遇到 409 external_id_divergente 或 external_id_nao_verificavel时，请查询 payout_id/recovery_endpoint所指向的订单。请保留原标识，不要新建标识绕过冲突。遇到 503 idempotencia_indisponivel时，应等待并查询同一 external_id，因为之前的订单可能已存在。

USDT 钱包与 BRL 余额相互独立，接收外部 USDT 充值，不使用 /payouts。对应钱包付款流程使用 funding_source=crypto_usdt，不要求收款人证件；限额以报价及 API 条件为准，不适用 BRL 余额的 R$ 6,000 上限。测试密钥使用独立模拟钱包，不涉及真实资金。

费用构成：amount_cents + fee_cents，其中 fee_cents = fee_service_total_cents + fee_provider_cents。通过 GET /saldo 读取 saque_fee_total_bps、saque_taxa_provedor_tipo、saque_taxa_provedor_piso_cents、saque_taxa_estimada_cents 和 saque_taxa_provedor_formula。请使用 API 当前费用，不要在代码中写死历史费率或固定费用。付款记录会保存实际费用。

查询 GET /payouts/{payout_id}。 processing 不代表付款完成； sent 表示发送已确认。 failed 及 refunded 须结合状态及流水对账。超时后继续查询原交易，不要假定已退款，也不要换用新标识再次付款。

确认后， e2e、 paid_at、 receiver_name、 receiver_tax_number 及 verify_url 等字段可能提供 Pix 付款证明。尚未取得的字段可能为 null。

7. Pix 直接兑换加密资产#

如需每笔 Pix 收款后直接交付加密资产，请使用 destino: "cripto"、交付目录中的有效组合，以及 payout_address。若请求体未指定地址，服务可能使用密钥配置的 Polygon 钱包；不要把它当作适用于其他网络的通用钱包。

{
  "amount_cents":10000,
  "payer_tax_number":"00000000191",
  "destino":"cripto",
  "asset":"usdt",
  "chain":"polygon",
  "payout_address":"0x1111111111111111111111111111111111111111",
  "external_id":"compra-cripto-001",
  "allow_hold":false
}

目录与报价

GET /cashin/catalog 列出 API 可交付的资产。使用目录中的 asset 及 network ；在 cash-in 及提现请求体中，网络字段名为 chain。 instant 可能为空。出现在 convert 中，并不免除 entregavel、最低金额或 memo 要求。当前各币种及网络的最低金额表见 最低金额与网络。

curl --fail-with-body https://api.luniumpay.com/cashin/preview \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"amount_cents":10000,"asset":"usdt","chain":"polygon"}'

预览不会创建收款单，也不会锁定付款时的汇率。请读取响应中的 min_brl_cents、费用及预估数量。客户钱包实际预计收到的数量列于 asset_amount，适用于所有路由及测试环境，已扣除网络提现费用（withdraw_fee，以资产单位表示）。该费用按每次发送固定收取，因此小额交易受影响更大，例如 Bitcoin 网络上的 BTC；若要以 BRL 展示，请使用 withdraw_fee × brl_per_asset。需要兑换的路由中， usdt_amount 是用于购买的 USDT，不是客户最终收到的数量； amount 是以下字段的旧名称： asset_amount。 eta/etaSeconds 是路由时效预估，不是合同约定的最长处理时间。

实际收到的金额及结算时适用汇率决定最终交付数量。若存在以下字段，请展示： settlement_tx_hash 及 settlement_tx_url ；不要将所有链接都固定指向 Polygon。内部交付标识不一定有公开区块浏览器链接。

所填 CPF/CNPJ 必须属于付款人。资料不符可能导致退款（PAYER_MISMATCH），若退款未完成则可能进入审核。不要仅凭客户发送的凭证或 under_review。

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 在创建时为可选项，DePix 卖出也一样：仅在卖出失败时才要求退款钱包（详见 退款钱包）。若已持有客户钱包，也可提前传入，但必须符合相应网络格式，并由退款收款人控制。交易所提币的来源可能是交易所共用钱包，不要假定它可用作退款钱包。

状态与凭证

并非所有接口都会经历全部阶段。 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。退款金额及时间取决于交易已到达的阶段，以及服务商的资金返还情况。不要承诺任何失败均可全额、自动或在固定时间内退款。逾期或金额不符的充值须继续跟踪同一订单，不得将其地址用于其他交易。

退款钱包：仅在卖出失败时要求

仅当卖出失败、资金需要退还客户时，才要求填写退款钱包。如订单尚无 refund_address，将停留于 AWAITING_REFUND_ADDRESS (refund_address_required: true），Lunium 并会发送 webhook： cashout.awaiting_refund_address。请客户提供符合以下网络的钱包： refund_network （DePix 卖出须使用 Liquid 地址 lq1…），然后提交：

curl --fail-with-body -X POST \
  "https://api.luniumpay.com/cash-outs/$CASHOUT_ID/refund-address" \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"refund_address":"CARTEIRA_DO_CLIENTE"}'

退款绝不会自动发送至充值来源地址，只会发送至客户提供的钱包。登记后，退款依次经过（REFUNDING_CRYPTO 用于加密资产卖出， REFUNDING 用于 DePix 卖出），直至 REFUNDED，并提供 refund_tx_hash （对应 webhook 为 cashout.refunding 及 cashout.refunded）；已向服务商发送 DePix 的情况见下文。若待退款项已由 Lunium 持有， refund_amount、 refund_asset 及 refund_network 会说明退款内容。退款完成前不要重新发起付款。

DePix 卖出时（asset: "DEPIX"、 network: "liquid"), POST /cash-outs/{cashout_id}/refund-address ，响应情况如下：

DePix 已发送至服务商的情况。 若 DePix 已发送至服务商后 Pix 付款失败，须先在链上确认服务商返还资金，才可向客户退款。在此之前，订单保持 MANUAL_REVIEW （webhook： cashout.under_review），且 refund_amount 为空，即使已登记退款钱包也是如此。确认返还后， refund_amount 才会显示退款金额，最高为实际返还金额加上尚未发送的部分，且不超过订单金额。之后订单进入 REFUNDING ；若无钱包，则进入 AWAITING_REFUND_ADDRESS。若 DePix 始终全部由 Lunium 持有，则按订单金额退款。

Pix 官方付款凭证

每笔达到 COMPLETED 状态的卖出订单均有 官方付款凭证 ，由 Lunium 出具。您可将其交给最终客户并留存用于会计记录。凭证包含金额、日期与时间（巴西利亚时间）、 E2E （巴西央行 Pix 系统中的唯一端到端标识）、收款机构与收款标识持有人、付款人（Lunium 的 Pix 结算服务商，即收款人流水中显示的付款主体），以及公开核验链接。

同一付款证明有以下四种形式，均包含在订单响应中：

凭证的获取渠道：

• API： 上述字段位于 GET /cash-outs/{cashout_id}，订单进入以下状态后即可获取： COMPLETED。
• Webhook： cashout.completed 会在链接已生成时填入相应字段。如返回 null、 cashout.receipt_ready ，后续事件会提供完整订单及可用链接。两个事件均须按 cashout_id。
• 合作伙伴控制台：在卖出订单中打开对应订单，选择“打开凭证”“下载 PDF”或“打开核验页面”。具备金额查看权限的用户可见这些链接。
• Telegram： 在密钥绑定的业务群组中，“✅ Pix 已付款”通知包含 E2E 及“查看凭证”链接，随后发送 PDF 附件（“🧾 官方付款凭证”）。若链接晚于通知生成，则稍后单独发送 PDF。

收款标识持有人。 收款人姓名及机构来自 Lunium 付款时进行的一次 Pix 收款标识目录查询。该查询有配额，专用于凭证，不是通用查询服务（GET /pix/keys/lookup 即使返回 verification_status: "not_performed" 也不影响凭证）。若该次查询未找到姓名，凭证仍然有效，金额、收款标识、日期及机构可从 E2E 等付款信息取得，姓名会稍后补充。

建议做法。将 pix_e2e 和 receipt_pdf_url 与订单一并保存。向客户提供 PDF，并将 verify_url 提供给需要核验的人。客户发来的凭证不能替代到账核验，应以原订单的 COMPLETED 状态及 pix_e2e 为准。通过 POST /payouts 提取余额时，GET /payouts/{payout_id} 同样返回 E2E、收款人姓名及 verify_url，也可在控制台“对外付款”中打开凭证。买入 Pix 入金的 E2E 与付款人姓名位于 GET /cashin/{cashin_id}/status 的 e2e 和 payer_name。

收款人查询与二维码付款

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，且须指定金额并使用兼容资产。若客户粘贴或扫描了带金额的静态或动态二维码，请提交完整的 br_code ，绝不要仅提交从中提取的 pix_key + brl_amount ：只有这样才能按精确金额、对应收款单及 txid 支付。若改为按收款标识付款，金额可能相差几分，导致收款方无法匹配原收款单。

新建的加密资产兑换 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。不要将某一产品的网络列表直接用于另一产品。

USDT/USDC 钱包：加密资产余额与 Pix 付款

钱包保存您项目的 USDT 余额。您可通过多条网络充值 USDT 或 USDC，再使用该余额通过收款标识或 Copia e Cola 支付 Pix。所有生产密钥均可使用； lun_test_ 密钥使用模拟器。

1. GET /carteira-usdt：余额（available、 reserved、 confirming）、当前支持的网络（networks[]，含币种及预估时间）、 min_deposit 及 min_payment_brl。
2. POST /carteira-usdt/deposits 并传入 {"amount": "100", "network": "tron"}：返回 amount_to_send （金额必须 精确一致，末尾小数用于识别该笔充值）、 address、 network_name 及 expires_at。请向用户展示这四项信息。若发送平台从转账金额中扣除手续费，须额外补足；识别依据是实际 到账的金额。充值请求有效期为 1 小时 (deposit_validity_hours = 1; expires_at ，即创建时间 + 1 小时），请在期限内发送。
3. 系统会自动入账，请跟踪 GET /carteira-usdt/deposits (waiting → confirming → available）或 webhook： wallet.deposit_credited。USDC 按 1:1 计入余额。
4. POST /carteira-usdt/quote 并传入 {"brl_amount": "50.00"} 或 {"br_code": "000201…"}：以 USDT 计价的预览（usdt_total、 usdt_reserved），不执行交易。
5. 调用 POST /carteira-usdt/payments，提交 {"brl_amount": "50.00", "pix_key": "cliente@exemplo.com", "pix_key_type": "email", "external_id": "pedido-123"}，或提交 br_code。创建成功返回 201，状态为 reservado。持续查询 GET /carteira-usdt/payments/{payment_id} 直至 final: true，或跟踪 wallet.payment_completed 与 wallet.payment_failed Webhook。
6. 完成后会提供 pix_e2e、 recipient_name、 recipient_document （部分遮盖的 CPF）及 receipt_url （官方付款凭证）。 GET /carteira-usdt/statement 用于查询流水：金额始终为正数， type 表示方向（deposit、 reserve、 debit、 release、 reversal).

规则：Pix 最低金额为 min_payment_brl （目前 R$ 25.00）。临时预留可覆盖最高 1% 的波动，未使用的部分会释放回余额。 falhou = 未执行，预留款已释放； falhou_apos_envio = 结果核查中，预留款不会自动释放； revisao 表示正在核查，不等于失败。同一 external_id 配合相同资料会返回同一笔付款（200）；资料不同时返回 409 external_id_divergente。 409 saldo_insuficiente 表示可用余额不足以覆盖预留金额。

共支持 9 条网络：USDT 和 USDC 支持 Polygon、BNB Smart Chain（BEP20）、Ethereum（ERC20）、Arbitrum One、Optimism、Avalanche C-Chain 及 Solana；Tron（TRC20）仅支持 USDT，Base 仅支持 USDC。当前密钥实际可用网络以 networks[]，详见GET /carteira-usdt为准。最低充值为 5 USDT 或 USDC（min_deposit）。未在期限内发送时，请求将进入 expired。Lunium MCP 提供 6 项钱包工具：查询余额、创建及列出充值请求、预览付款、执行付款及查询付款。

在 合作伙伴控制台中，充值请求只展示地址二维码，并显示精确到秒的倒计时，直至 expires_at。二维码不包含金额，须在发送应用中手动输入精确金额（amount_to_send）。EVM 网络的 0x 地址相同，务必在发送应用中选择正确网络。

测试环境中（lun_test_）：地址为虚构地址，切勿转入真实资金；充值约 15 秒后自动入账，Pix 约 15 秒后完成，并提供测试 E2E。金额末尾小数用于选择场景：充值 .02 会过期；Pix .01 会经过 revisao、 .02 会失败并释放预留款， .05 约需 2 分钟完成。

9. 通过 Telegram 操作#

Lunium Partners — 官方接入者社区

加入 Lunium Partners

Lunium Partners 是 API 接入方建议持续关注的渠道。建议从项目开始就让合作伙伴的技术及运营负责人加入，并在生产运行期间持续关注通知。参与社区 受到强烈推荐，但不是创建密钥或使用 API 的技术前提。

在社区中可关注 运行通告、维护通知及 API / 接口契约变更，也可与其他接入方交流。不要等到故障发生后才加入；系统上线后仍须持续跟踪变更。

开始步骤： 加入 Lunium Partners，与两位人工联系人安排项目专属群组，绑定机器人，并在正确环境核验监控与 webhook。社区不替代项目专属支持，也不替代 API 资金对账。

不要在社区公开 API 密钥、webhook 签名密钥、 monitor_url、付款人证件或客户交易资料。具体问题请在专属群组处理，仅提供必要的 ID 及最少资料。

使用 Fable 或其他 AI 接入： 交付给人工负责人的方案及检查清单中，应包含 Lunium Partners 链接。AI 应解释这一建议，并区分上述三个渠道。未经确认，不应声称某人已加入群组；不要将入群作为执行测试环境测试的前提，也不要将 Telegram 消息视为资金操作授权。

有人工跟进的接入群组

强烈建议为项目建立专属 Telegram 群组，并加入人工联系人 @luniumb2b 及 @luniumb2c。 。Lunium 可创建群组并邀请合作伙伴团队，合作伙伴也可自行创建并添加两位联系人。群组用于跟进接入、验收及生产运行，但不是使用 API 的技术前提。

1. 自行创建群组，或联系上述人员申请创建，并使用能识别项目的群名。
2. 加入两位人工联系人，以及合作伙伴的技术和运营负责人，明确各方职责及升级处理渠道。
3. 同时添加 @LuniumNotifyBot ，并按下方步骤绑定。 机器人发送通知及执行命令，人工联系人跟进疑问和故障，两者各有职责。
4. 在群内置顶手册、公开状态页及操作说明。私密监控链接仅可分享给有权查看项目资料的成员。
5. 验收时，请核对绑定项目、监控、已签名 webhook，以及所选流程的失败与恢复场景。

请求支持时，请提供环境（测试或生产）、交易 ID、 external_id、含时区的时间、预期与实际行为，以及 request_id （如有）。通知问题还须提供 event_id 及 X-Lunium-Delivery-Id。不要发送 API 密钥、webhook 签名密钥、完整付款人证件或其他客户资料。群组成员身份不代表 24 小时人工支持或结算时效承诺，请与团队约定服务安排。

以下资料列出的合作伙伴 / 社区通用渠道： /keys/me ，可补充维护与 API 变更通知，但不替代项目专属群组。

机器人绑定与命令

将 @LuniumNotifyBot 添加至项目群组。身份明确的管理员须使用 /vincular 及创建 / 查询密钥时提供的绑定流程。若机器人展示确认按钮，须点击按钮；发送文字“是”不能代替点击。不要在群组中公开 lun_... 密钥。

Telegram 中的金额单位为 巴西雷亚尔，例如 50 或 50,50；API 中的 amount_cents 以分为单位。对子账户操作前，须核对显示的账户范围。 /pagar 不提供加密资产提现中的 cliente=ref 参数。子账户 Pix 对外付款请通过 API 传入 customer_ref。

加密资产提现会在确认前展示目的地、预估数量及扣款金额。确认有效期为 60 秒，仅对发起请求的用户、群组及项目有效。群组提现要求身份明确的管理员操作，匿名发送的消息不能授权提现。确认时会重新校验条件，必要时要求重新预览，不会锁定汇率。

/sacar 是外部加密资产兑换 Pix 的流程。将余额以加密资产形式提取，请使用 /sacarcripto。 /qr、 /qrwhitelist 及 /qrdelay 等命令在未明确提供钱包时，也会使用托管余额；处理时间及冻结条件须以响应为准。

10. 可靠的 webhook#

配置 webhook_url，保存 webhook_secret ，并执行 POST /webhooks/test 测试接收端。此调用会向已配置的地址发送测试通知。

事件封装示例：

{
  "event":"cashin.settled",
  "event_id":"evt_exemplo",
  "created_at":"2026-09-17T20:00:00.000Z",
  "data":{
    "cashin_id":"ci_exemplo",
    "destino":"saldo",
    "status":"paid",
    "settlement_status":"sent"
  }
}

示例省略了部分 data。收款单、cash-out 及 Pix 对外付款事件使用各自资源的基础状态对象；GET 查询补充的信息，例如 timeline，不一定出现在事件中。 saldo.* 事件则有独立的流水数据。不要要求每个 webhook 的所有字段均与补充信息后的 GET 响应完全一致。

验证 原始请求体，不要重新序列化 JSON；还须检查时间戳有效期。比较长度相同的缓冲区时，应使用恒定时间比较。可使用 完整 Node.js 验签示例，它也会安全拒绝格式错误的签名，不会因缓冲区长度不同而抛错。

持久化保存或入队事件后，尽快返回 2xx。投递请求的 超时时间为 10 秒，耗时处理应放在之后执行。不要按投递尝试去重：同一事件的所有尝试仅应产生一次业务效果。

未成功时，最多尝试 12 次，并逐步延长重试间隔。整体约 7 小时，但受队列影响，不构成投递 SLA。请查询 GET /webhooks/deliveries ，并在修复接收端后通过 POST /webhooks/deliveries/{event_id}/retry 重发。重试耗尽的投递将标记为 failed，仍可依据记录恢复。

新接入应使用 v2 签名。 X-Webhook-Signature 为旧版字段，新密钥不再提供，已公告于2026年11月9日移除，请勿依赖。

事件

请兼容新增事件与字段，记录未知内容，并在必要时通过 GET 核对资源。不要假定事件按顺序到达；更新已完成的资源前，先查询当前状态，避免回退。

合作伙伴实时监控

合作伙伴可通过 Lunium 私密监控查看自己的项目。 查询 GET /keys/me ，在后端获取响应中的 monitor_url 并打开，或在已绑定群组中使用 /monitor 。创建密钥时也会返回该链接。链接提供项目只读访问，仅可分享给授权人员，不得放入公开文档或交给最终客户。

监控每隔 3 秒 查询事件流，每隔 15 秒查询托管余额。它展示收款单、cash-out、Pix 对外付款及 webhook 投递；启用托管后还展示可用 / 冻结余额、子账户及近期流水。这些间隔仅表示界面查询频率，不保证数据库、服务商或区块链在该期限内更新。

私密链接泄露时，请使用 PATCH /keys/me 并传入 {"rotate_monitor_token":true}，并保存新的 monitor_url，旧 token 随即失效。监控 token 虽为只读，但可查看整个项目，而非单个客户；不要将其用作公开交易详情页的身份验证。

构建您自己的控制台事件流

# 在后端执行；从密钥管理器读取 LUNIUM_API_KEY。
curl --fail-with-body 'https://api.luniumpay.com/cashin/events?limit=80' \
  -H "X-API-Key: $LUNIUM_API_KEY"

GET /cashin/events 接受在请求头中传入 X-API-Key 或 X-Dashboard-Token 。托管监控页面使用 ?token=。响应包含 projeto、 agora 及 eventos。每个条目提供 ts、 fluxo (cash-in、 cash-out、 payout 或 webhook), provedor、 ref、 valor、 estado、 detalhe 及 tx，部分字段可能为空。 limit 默认为 60，允许范围为 1 至 200。

这是近期摘要，不是完整的状态变化历史。 列表按 ts 降序排列。交易可能仅显示当前状态；事件流没有重放游标，也没有 webhook 封装中的 event_id 。不要根据 valor/estado等说明文本计算余额、费用或进行对账，也不要将 ts 当作全局变更序列。金额、网络、哈希及凭证须查询原始资源；尤其应使用 cash-in 状态返回的 settlement_tx_url 打开对应网络的区块浏览器，不要根据事件流摘要默认使用 Polygon。

Webhook + 状态查询 + 界面更新

Webhook 是 Lunium 向合作伙伴后端发送的 HTTPS POST 请求。若要在您的应用中提供实时体验，请实现以下流程：

1. 接收： 读取原始请求体并限制大小，在解析 JSON 前验证签名及时间戳。核对请求体中的 event_id 是否与请求头一致。签名密钥对应指定 API 密钥及环境，不要依赖 payload 自行选择项目。
2. 保存： 先将事件写入持久化收件箱，并设置以下唯一约束： (projeto, ambiente, event_id)，再返回 2xx。重复的已保存事件直接返回 2xx，不重复执行。写入失败时返回错误，以便重试。不要静默丢弃已通过身份验证的未知事件。
3. 对账： 后台任务处理收件箱，必要时查询权威资源。按交易串行更新，避免旧响应覆盖新查询。分别保存收到的事件历史、查询状态及最后查询时间。
4. 更新界面： 您的后端通过 SSE、WebSocket 或轮询，将结果发布给应用中已验证身份的会话。每次读取及连接均须校验项目和客户权限。这些通道由合作伙伴自行实现；本接口契约未提供 Lunium 公开 SSE/WebSocket 接口。
5. 恢复： 定期核对未完成或交付结果不确定的交易，采用可调整间隔、退避机制及密钥限额；不要为每个打开的浏览器单独向 API 发起查询。客户端重连后，加载已保存状态，并提示更新是否延迟。

Lunium 监控提供现成的运行视图，合作伙伴控制台可补充自己的订单、客户及持久历史。Webhook 不替代流水，也不记录交易所、银行或其他服务商的每个内部步骤。

还须保存创建交易时自行设置的 external_id 。Cash-in 状态可能提供 timeline 并传入 etapa、 em、 detalhe；cash-out 状态可能提供 timeline 并传入 state、 at。仅展示接口实际返回的阶段及时间。确认数、哈希或凭证可能在生成前缺失或为 null。不要编造进度百分比、完成时间、链上交易或失败原因。

各事件在界面中的含义

settlement_status=incerto 须先对账，再考虑任何新的交付。旧 webhook 可能晚于已显示完成的查询到达；将其保存到历史，但不要回退当前状态。已完成交易也可能有合法后续更新，例如退款；应查询权威来源，而不是首次成功后忽略全部更新。

配置、测试与恢复通知

在正确环境的密钥中配置公开 HTTPS 接收端。系统会拒绝私网 / 本地地址。签名密钥仅在生成时返回，请保存在后端。更新 URL 不一定生成或返回新签名密钥；如需轮换，请使用 rotate_webhook_secret协调切换，后续尝试使用届时有效的签名密钥。

curl --fail-with-body -X PATCH 'https://api.luniumpay.com/keys/me' \
  -H "X-API-Key: $LUNIUM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"webhook_url":"https://seu-dominio.example/webhooks/lunium"}'

# 仅测试投递与签名，不创建付款。
curl --fail-with-body -X POST 'https://api.luniumpay.com/webhooks/test' \
  -H "X-API-Key: $LUNIUM_API_KEY"

curl --fail-with-body 'https://api.luniumpay.com/webhooks/deliveries?status=failed&limit=100' \
  -H "X-API-Key: $LUNIUM_API_KEY"

# 修复接收端后再重发，使用属于当前密钥的 event_id。
curl --fail-with-body -X POST \
  "https://api.luniumpay.com/webhooks/deliveries/$EVENT_ID/retry" \
  -H "X-API-Key: $LUNIUM_API_KEY"

请将示例域名替换为真实接收端。 POST /webhooks/test 在生产环境每个密钥每分钟最多调用 6 次，返回 ok、 status_code、 ms、 event_id 及 delivery_id。此类单次测试不会保存至生产投递队列，只验证通信，不验证真实结算或应用的所有业务路径。

GET /webhooks/deliveries 接受在请求头中传入 status (pending、 sent、 failed), event 及 limit （默认 50，最多 200）。每行提供 event_id、 operation_id、 attempts、 last_error、 url、 next_attempt_at、 created_at 及 updated_at，以及事件 / 状态。 failed_count 仅统计 本次返回记录中的失败数量。该接口不支持按 operation_id 筛选，也没有分页游标；请维护自己的持久历史，并从返回记录中查找交易。

重试响应：200 表示投递成功；202 表示失败且已重新入队；409 表示之前已送达；404 表示该密钥下不存在对应记录。 pending/sent/failed 在此表示 webhook 的投递结果，不是付款结果。重发通知不会重新付款，也不会修复未完成的结算。

实时跟踪接入验收

• 在测试密钥中配置接收端，并执行以下指南中的适用场景： 测试环境。 GET /sandbox/events 用于查看模拟事件；不要用生产运行事件流证明测试环境覆盖范围。
• 验证签名错误 / 过期、重复事件、乱序、接收端不可用、重连后的恢复，以及项目 / 客户之间的隔离。
• 确认 cashin.paid 不会标记为加密资产已交付，冻结资金不会变成可用余额，且 webhook.test 不会改变余额。
• 将同一交易的创建响应、webhook 及 GET 状态按 ID 关联核对，超时后不创建新交易。
• 验证结算错误、结果不确定、退款及通知恢复；需要调查时，将 ID 提供给人工支持群组。
• 控制台应展示交易、外部订单、获授权客户、币种 / 网络、实际返回金额、资金状态、webhook 投递状态、最后更新时间，以及可用的凭证 / 哈希。资料过期时予以提示，不要误导用户认为仍在实时更新。

11. 错误、幂等性与对账#

结合 HTTP 状态码与 erro、 acao、 detail、 request_id 及 agent_guidance 等字段（如有）判断。有些路径仅返回部分字段，不要仅依据以下字段的自由文本内容编写业务分支： detail。

发送 external_id ，长度不超过 64 个字符，适用于支持该字段的金融交易。每个业务意图使用一个持久标识，重试时保持 所有参数完全相同。收款单及加密资产提现共用密钥的引用命名空间，应使用不同前缀。不要利用差异校验修改已有交易，各接口的比较规则可能不同。

超时恢复时，根据交易类型查询 /cashin/charges?external_id=...、 /cash-outs?external_id=... 或 /payouts?external_id=...。确需重试时，保持相同请求体及标识；不要仅因响应丢失就生成新 ID。

保存 ID、金额、币种 / 网络、 customer_ref、时间戳、已处理事件及流水引用。BRL 使用整数分，加密资产使用十进制字符串。日期包含明确时区，舍入及兑换须以 API 返回值为准。

操作指南：查询内容与客户提示

任何交易流程中，若控制台资料过期，都应显示“最后更新时间”及连接状态。不要将超时、空响应或未收到 webhook 视为资金成功或失败。结果不确定的交易必须先对账，不要仅为消除告警就手动另发转账。

联系人工支持群组时，请提供环境、交易 ID、 external_id、含时区的时间、HTTP 状态码、 erro/acao、 request_id （如有）及最近查询状态。Webhook 问题还须提供 event_id 及尝试的 HTTP 响应 / 时间，并对日志脱敏。不要在公开社区发送密钥、签名密钥、私密监控链接、完整 CPF 或含客户资料的 payload。本手册不保证统一的支持或结算期限。

Fable 可参考 结构化故障处理指南。它提供查询及对账步骤，不授予提现、修改费用或再次转账的权限。

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 可用于检查事件；已配置的回调使用产品自带的签名队列。价格与时间均为模拟值，不代表合作交易所的实际条件。

USDT/USDC 钱包： 测试密钥使用钱包模拟器，接口及数据结构相同。充值 .02 会过期；Pix .01 会进入审核， .02 会失败并释放预留款， .05 会延迟完成。详情参阅 USDT/USDC 钱包。

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

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

13. 查询当前规则#

GET /keys/me 本身不包含所有条件。每日限额为 null 仅表示密钥没有该项总额上限；付款人、收款人、单笔、余额及可能的 mandate 限制仍有效。不要根据手册示例将目录、费用、期限或限额固定写入代码。

14. 佣金、智能体与其他操作#

配置合作伙伴佣金

Sub fee 是在 Lunium 费用之外另计的合作伙伴佣金。 100 bps = 1%； 200 bps = 2%。配置前，请通过 GET /comissao 查询规则及允许的上限。 下方示例会改变该密钥新建收款单的价格，仅应应用项目负责人同意的费率。

curl --fail-with-body -X PATCH https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"partner_fee_bps":200}'

核对已保存的配置值： GET /keys/me。费率会记录在每张新收款单中；修改配置不会重新计算已有收款单，也不会生成追溯佣金。Telegram 中， /comissao 用于查询； /comissao 2 用于提交变更并请求确认。管理员须核对密钥身份，使用机器人返回的确认命令（含密钥 ID），不得替其他项目确认。

区分费用、佣金、汇率与交付数量

Cash-in 的计费基数为 收到金额减去 Lunium 固定费用，再对该基数计算 Lunium 及合作伙伴比例费用。余额充值仅扣 R$ 1.00，无比例费用、分档费率或佣金。收款单保存的参数及交易返回金额优先于示例。

以下示例以分计算，仅作教学，不代表当前报价： 收到 10000 （R$ 100），固定费用 100 （R$ 1），Lunium 费率 200 bps （2%），合作伙伴费率 100 bps (1%).

计算使用 floor(base_cents * (10000 - lunium_bps - partner_bps) / 10000)。佣金为扣除 sub fee 前后净额的差值，并保留产品的舍入规则。不要对已报价的加密资产数量再次扣除佣金。

POST /cashin/preview 可能返回 lunium_fee_cents、 partner_fee_cents、 fee_total_cents、 net_cents ，加密资产预估数量列于 asset_amount，已扣网络提现费用（withdraw_fee）。提供此项拆分的响应中， fee_total_cents + net_cents = amount_cents。旧版字段 brl_per_usdt 及 usdt_amount须结合响应中的资产判断，USDC 也可能沿用相同字段名。

汇率并非另一笔合作伙伴佣金。 兑换采用 Binance 卖一价（ask），不再使用旧溢价。Lunium 费用及佣金与汇率分别计算。Cash-in 预览仅为预估，不锁定付款时汇率。路由 / 网络成本及最低金额也可能影响交付，请读取目录及响应中的适用字段。不要对已计入该费用的数量，再次加上 withdrawFee 。实际结算数量须在交易状态及凭证中核对。

托管充值的结果为 BRL，不会立即购买加密资产。后续提现另有费用及兑换条件，cash-in 预览不是托管提现的完整预览。Pix 对外付款响应分别列出 fee_service_total_cents （Lunium + 合作伙伴）及 fee_provider_cents； fee_cents 为费用总额。合作伙伴佣金、客户余额及 Lunium 利润属于不同账目，单凭预估与实际交付之间的差额，不能证明利润。

佣金入账、流水与提现

1. 查询 GET /comissao： disponivel_cents、 creditado_cents、 estornado_cents、 sacado_cents、 min_saque_cents、 pode_sacar_agora、 proximo_saque_em 及 politica。
2. 查询 GET /comissao/extrato?limit=50。下一页使用 next_before 作为 before 。请将 origem_id 关联到收款单或提现，并读取 kind、 valor_cents 及 partner_fee_bps。
3. 佣金在 status=paid 及 settlement_status=sent之后核算，晚于结算本身。Pix 已付款不代表佣金已可用。新余额充值不产生佣金；购买及转出分别使用对应类别的佣金，须查询交易保存值。测试环境不累积真实佣金。
4. 以下流水类型 credito、 estorno、 saque 及 saque_estorno 用于解释余额。请核对正负号，避免重复计数。符合条件的交易在核算后仍未显示时，请将 ID 提供给人工支持群组对账，不要通过修改费率尝试补记历史。
5. 提现前，查询当前规则、余额及可交付路由。以 BRL 换算的最低金额（目前按实时汇率折合 US$ 10）及提现间隔以 API 为准；若 min_saque_cents 为 null，则无有效报价用于验证最低金额。 pode_sacar_agora 不能替代网络、地址、memo、流动性及路由最低金额校验。

POST /comissao/sacar 接受 amount_cents、 asset、 chain、 payout_address、必要时的 payout_tag 及 external_id。提现不再收取 sub fee 或 Lunium 管理费，但仍须考虑兑换及路由成本。响应包含 saque 及 comissao；请跟踪以下公共交易标识： saque → GET /cashin/{cashin_id}/status ，直至确认交付。HTTP 成功不代表加密资产已交付。

使用独立前缀，例如 comissao-...，用于 external_id，因为引用命名空间与收款单共用。超时后，先查找 /cashin/charges?external_id=... 并跟踪已有 ID。提现会先校验规则及间隔，再查找引用，因此重试可能返回 429 ，即使之前的请求已经获接受。不要生成新 ID 或并发重复提现来尝试解除限制。

PATCH /keys/me 接受在请求头中传入 partner_fee_bps 用于 sub fee。当前规则、可用佣金及提现条件见 GET /comissao；流水见 GET /comissao/extrato；提现使用 POST /comissao/sacar。佣金余额与客户托管余额分开，不要相加，也不要将佣金当作 Mesh 推荐奖励。

面向智能体的 Mesh 提供发现、注册、验证、mandate 授权及激活能力。请使用 GET /mesh 及其返回的后续操作。MCP 地址为 https://api.luniumpay.com/mcp；通过 tools/list发现工具，因为 MCP 工具范围并不等同于全部 HTTP 接口。没有专用工具的操作，仍可通过已验证身份的 API 调用。

下方清单由本次修订所依据的 OpenAPI 生成，亦包含 webhook 投递查询、监控访问恢复、DEX 目录、佣金及 Mesh 生命周期。管理及内部接口不属于合作伙伴公开 API。

15. 上线检查清单#

• 已在正确密钥中配置佣金，费用拆分与流水已核对，无重复扣费。
• 已核对恢复邮箱，分别保管监控链接、API 密钥及 webhook 签名密钥。
• 已演练故障处理流程，不将开发中的能力视为已上线。
• 建议技术及运营负责人加入 Lunium Partners ，并明确持续跟踪通知及变更的安排。
• 强烈建议与 @luniumb2b 及 @luniumb2c 建立项目专属群组，由 Lunium 或合作伙伴创建，并明确负责人。
• 已核验私密监控；自建控制台按项目 / 客户授权，并显示最后更新时间。
• 已测试持久化收件箱、重复事件、乱序、接收端不可用、重试及 webhook 对账。
• 密钥保存在服务器端，测试环境与生产环境分离。
• /keys/me 及 /saldo 已按密钥及各客户范围核对。
• 托管收款使用 destino: "saldo"；只有在提取加密资产时才选择钱包。
• 界面读取当前目录及限额，展示资金冻结条件，并在需要时要求填写 memo。
• 已持久化保存 ID；重试保持相同请求体及 external_id；已测试超时后的恢复流程。
• Webhook 验证 HMAC 与时间戳，按事件去重，并在超时前响应。
• 对账明确区分 Pix 已支付、入账已登记、资金可提现及加密资产已交付。
• 处理余额、等待期、接口、费用、服务商及密钥错误时，不重复执行交易。
• Telegram 由身份明确的管理员绑定，提现须在正确的会话及项目中确认。
• 接入验收覆盖成功、资金冻结、过期、失败、重发及响应丢失后的查询。

技术支持： @luniumb2b · @luniumb2c · contato@luniumpay.com。请关注 服务状态 及 Lunium Partners。请求支持时，请提供交易 ID 及 request_id （如有），不要分享完整 API 密钥。

16. 本次修订内容#

• 2026年10月9日 · OpenAPI 1.44.1 · 修订 2026-10-09.1： 测试环境： POST /sandbox/operations/{operation_id}/resolve 会返回 400 outcome_invalido ，条件为 outcome 不是 sent 或 failed 时（此前，请求体缺少 outcome 时，可能返回 200 却未解决任何操作）。校验发生在查找交易之前，模拟器不会因此改变。 余额：在 GET /saldo、 proximas_liberacoes 中，可返回所查询账户范围最多 200 项资金释放记录（原先最多 20 项）；格式及范围（主账户或 customer_ref）保持不变。
• 2026年10月8日 · OpenAPI 1.44.0 · 修订 2026-10-08.2： DePix 卖出： refund_address 在创建时不再必填，仅在卖出失败时才要求退款钱包（退款钱包）。未提供钱包时，订单停留于 AWAITING_REFUND_ADDRESS （webhook： cashout.awaiting_refund_address），之后通过以下接口填写 Liquid 地址： POST /cash-outs/{cashout_id}/refund-address；订单随后进入 REFUNDING 及 REFUNDED，并发送对应 webhook。错误包括： 400 refund_address_invalida （含 Lunium 自身地址）、 409 refund_address_imutavel 及 409 devolucao_indisponivel。已发送至服务商的 DePix，须在链上确认返还后才可向客户退款；此前订单保持 MANUAL_REVIEW，退款金额最高为实际返还金额。有关付款人限额拒绝的 detail 及 allow_hold: false 说明已修订，金额采用巴西格式（R$ 1.234,56），相关字段说明亦已更新： GET /cashin/limits； erro 及 code 保持不变。佣金提现最低 US$ 10。 合作伙伴控制台 （第 2 节）：新账户通过邮件 6 位验证码激活；通过验证码或 Google 登录的用户可一键接受邀请； 我的访问权限 并传入 退出其他会话、无密码账户可用代码关闭双重验证，密码变更时发送邮件通知；成员失去所有者角色时通知其他所有者； 使用加密资产付款 支持稳定币及 30 种主要加密资产，提高可读性，会话有效期为 12 小时并随使用续期。第 8 节。
• 2026年10月8日 · OpenAPI 1.43.1： USDT/USDC 钱包 充值请求有效期改为 1 小时 (deposit_validity_hours = 1; expires_at ，即创建时间 + 1 小时，此前为 3 小时。新增 合作伙伴新控制台 （第 2 节）：parceiros.luniumpay.com 提供业务概览、PDF 凭证、带地址二维码及倒计时的钱包充值、通知，以及支持角色和双重验证的团队管理。仅所有者可在控制台绑定 Telegram、修改结算钱包及 sub fee。钱包充值与余额支付 Pix 的流程图见 USDT/USDC 钱包。
• 2026年10月7日 · OpenAPI 1.43.0： USDT/USDC 钱包 (/carteira-usdt）：支持多网络充值 USDT 或 USDC、使用余额通过收款标识或 Copia e Cola 支付 Pix、查询流水，以及 webhook： wallet.* ，并提供测试环境模拟器。
• 2026年10月7日：cash-in 预览（POST /cashin/preview）在生产环境开始使用与测试环境相同的字段名： asset_amount （钱包预计收到的数量）、 withdraw_fee （网络提现费用，以资产单位表示）、 withdraw_min 及 brl_per_asset （用于换算 BRL）。 amount 及 network_min 仍作为旧名称保留。
• 2026年10月3日：第 Pix 官方付款凭证 （8）节说明凭证内容、四种形式（pix_e2e、 receipt_url、 receipt_pdf_url、 verify_url），以及 API、webhook、合作伙伴控制台和 Telegram 等获取渠道。
• 通过示例核对费用与佣金，补充访问恢复及故障场景。
• 面向 AI 的结构化资料与 OpenAPI 对齐；未来能力须待发布并验证后使用。
• 在开头、Telegram 操作及检查清单中突出 Lunium Partners 官方社区。
• 恢复人工支持群组建议：加入 @luniumb2b 及 @luniumb2c，由 Lunium 或合作伙伴创建。
• 详述私密监控、事件流、自建实时控制台、各流程状态、验签、恢复与验收。
• 本次更新重点为支持与交易跟踪，并更新引用的 OpenAPI 版本。
• 记录无需固定钱包的托管流程及 Telegram 提现。
• 区分 API 的 destino 默认值与机器人的默认值。
• 将费用及限额关联到正确查询接口，移除固定价格与时效承诺。
• 区分本地冻结、服务商冻结及余额等待期。
• 区分入金与交付目录，包括 entregavel 筛选，以及提现中不支持 Liquid/DePix 的限制。
• 说明 Pix 收款人查询可能为可选或不可用，以及 br_code 须受可用性限制。
• 将 webhook 超时修正为 10 秒，完善稳健验签及故障恢复。
• 结合接口核对状态、字段、示例及 OpenAPI 清单。
• HTML、Markdown 及 PDF 使用同一内容生成，发布前校验接口契约。

下载 PDF · Markdown · 结构化示例 · 接口契约核查