面向钱包与应用的 Pix 稳定币服务

适用对象

• 已上线并准备替换巴西 On-ramp / Off-ramp 渠道的钱包或应用。
• 希望用同一接入同时处理充值与提现的产品。
• 希望向用户展示实际交易进展，而非仅显示加载动画的团队。

面临的问题

钱包应用中的充值体验会影响用户是否继续操作。金额被拒绝却没有可用额度提示，或付款后无法了解进展，都容易造成困惑。明确的限额与状态信息有助于改善这一流程。

API 分别提供两类信息： 每位付款人 的额度可在输入金额前查询；状态响应提供服务器记录的时间线及可能的阶段统计。仅在返回实际数据时展示相应阶段与典型耗时，不要编造进度或完成时间。

完整交易流程

1. 用户提供 CPF 后，查询 GET /cashin/limits?payer_tax= ，提前展示可充值额度，区分 无冻结期 及可接受但须冻结的金额。
2. 用户选择金额。 POST /cashin/charge 并传入 customer_ref （用户在您系统中的 ID），响应会返回 Pix Copia e Cola 支付码。
3. 用户付款后，webhook cashin.paid 到达，您的后端可更新界面阶段，并通过状态查询对账。
4. 交付后， cashin.settled 提供哈希。若目的地为 saldo，则记入 BRL 余额，可用性仍须按冻结及等待期规则核对。
5. 提现使用： POST /payouts （Pix）或 POST /saldo/sacar-cripto （目录中可交付的币种），并始终使用相同的 customer_ref。

使用的接口

可运行示例

# 用户入金：按其 CPF 识别 Pix，向其钱包交付加密资产
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":15000,"asset":"usdt","chain":"polygon",
       "payout_address":"0xCarteiraDoUsuario",
       "payer_tax_number":"12345678909",
       "customer_ref":"user_8842","external_id":"dep-8842-17"}'

# 展示金额输入前，先查询该用户限额
curl "https://api.luniumpay.com/cashin/limits?payer_tax=12345678909" -H "X-API-Key: $LUNIUM_KEY"

async function limiteDoUsuario(cpf) {
  const r = await fetch(`${API}/cashin/limits?payer_tax=${cpf}`, {
    headers: { "X-API-Key": process.env.LUNIUM_KEY },
  });
  const l = await r.json();
  return { naHora: l.instant_available_cents, comRetencao: l.held_qr?.available_cents ?? 0 };
}

async function depositar({ cents, cpf, carteira, userId, idempotencia }) {
  const r = await fetch(`${API}/cashin/charge`, {
    method: "POST",
    headers: { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      amount_cents: cents, asset: "usdt", chain: "polygon",
      payout_address: carteira, payer_tax_number: cpf,
      customer_ref: userId, external_id: idempotencia,
    }),
  });
  if (r.status === 403) throw new Error("acima do limite deste pagador");
  return r.json();
}

import os, requests

API, H = "https://api.luniumpay.com", {"X-API-Key": os.environ["LUNIUM_KEY"]}

def limite_do_usuario(cpf):
    l = requests.get(f"{API}/cashin/limits", headers=H, params={"payer_tax": cpf}, timeout=20).json()
    return l["instant_available_cents"], (l.get("held_qr") or {}).get("available_cents", 0)

def depositar(cents, cpf, carteira, user_id, idempotencia):
    r = requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdt", "chain": "polygon",
        "payout_address": carteira, "payer_tax_number": cpf,
        "customer_ref": user_id, "external_id": idempotencia})
    if r.status_code == 403:
        raise RuntimeError("acima do limite deste pagador")
    return r.json()

测试环境：先验证，再使用真实资金

只需一次调用，无需预先审批或绑定银行卡，仅测试人员邮箱为必填项，手册、流程图及接入步骤将发送至该邮箱。 lun_test_ 密钥可用于验证文档列出的功能，不涉及真实资金。

curl -X POST https://api.luniumpay.com/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@empresa.com","name":"meu-teste"}'

测试环境无法 不 证明真实结算。不会转移加密资产或支付真实 Pix；它用于验证接口契约，不能衡量实际结算渠道。

资产与网络

加密资产入金目录为 GET /catalog；Pix 收款后的交付目录为 GET /cashin/catalog。报价前，请查询所选流程的资产及网络。可用性和最低金额可能变化。

使用 deposit_tag 处理需要 memo 的充值；交付时，若路由要求，还须传入 payout_tag 。有关各字段， API 手册 提供了完整说明。

限额与资金冻结

查询 GET /keys/me 查询账户限额及费用，通过 GET /cashin/limits?payer_tax=... 查询付款人额度，并通过预览查询路由最低金额。不要为 cash-in、cash-out 及 Pix 对外付款共用固定上限。

收款单已付款后，仍可能等待资金解冻才能结算。通过状态、时间线及签名事件，区分款项收到、余额可用及最终交付。交易有效期见 expires_at。

依据实际跟踪，不作固定时效承诺

处理时间取决于流程、可用路由、网络确认及可能的资金冻结。请跟踪至最终状态，并查询 服务状态。模拟耗时不代表真实结算时间。

幂等性

传入 external_id 于支持该字段的资金操作中。重复相同请求会返回 同一笔 交易，不会新建第二笔。相同参数配合不同 ID 可能创建两笔交易；相同 ID 配合不同参数则返回 409 external_id_divergente ，而不会擅自猜测。

超时不等于拒绝。未收到响应时，须先通过 external_id 查询，原交易可能已经存在。

Webhook 与对账

状态变化通过带时间戳的 HMAC SHA-256 签名事件通知，请求头为 X-Lunium-Signature，格式为 t=…,v1=…。校验时间戳有效期可防止已捕获事件被重放；信任请求体前，须先完成验签。

Webhook 是主要通知方式，也可辅以轮询。查询状态时，请根据 timeline 中记录的 服务器时间 展示阶段，因为轮询计时器测得的是您的查询间隔，不能代表交易实际耗时。

未收到 2xx 时，系统按退避策略重试。可通过以下接口手动重发： POST /webhooks/deliveries/{event_id}/retry ；测试接收端 URL 使用 POST /webhooks/test。

异常处理

超过付款人限额： 403 limite_do_pagador 并传入 acao: "corrigir" 及可接受金额。应显示具体数值，而不是仅显示“错误”。

低于路由最低金额： 响应提供预估最低 BRL 金额，且 不会扣款。可让用户快捷选择正确金额。

该证件的首次充值： 余额可用性以项目条件为准。即时释放项目中，新付款人超过 R$ 100.00 的首次 Pix 仍可能由服务商冻结 24 小时（delayed，之后会通过 saldo.liberado自动释放）。展示返回的时间，勿仅提示“稍后再试”。

安全机制

• Webhook 签名 — Webhook 使用带时间戳的 HMAC SHA-256 签名，位于 X-Lunium-Signature，格式为 t=…,v1=…。须验证签名及时间戳有效期，以防重放。
• 幂等性 — Cash-in、cash-out 及 Pix 对外付款使用 external_id。相同内容重试返回同一交易，不创建第二笔；同一 external_id 配合不同参数会返回 409。
• 出站连接验证 — 每次投递前解析并验证 webhook URL，拒绝内网地址、云元数据地址及跳转至私网的重定向，并将连接固定至已验证 IP。
• 冻结限制默认拒绝放行 — 结算时检查资金冻结，并在 SQL 任务领取时再次校验，防止 worker、状态查询或队列提前结算。
• 付款持久化 — 提现会在调用服务商前，于同一数据库事务内保存订单并扣减余额，确保每笔扣款均有可对账的订单。
• 公开核验 — GET /v1/verificar/{e2e} 无需密钥即可核验已结算 Pix，交易对方可自行验证。

公开核验有助于交易对方独立检查 Pix，无需 API 密钥或人工确认。

从哪里开始接入

应用核心流程包括查询额度及创建收款单，测试环境均可验证。团队可先构建并测试界面，再与接入团队确认商业及生产条件。

接入常见问题