以您的品牌提供 Pix 与稳定币服务

适用对象

• 希望为最终客户提供 BRL 余额，而无需从零构建托管账本的产品。
• 需要统一接入充值、余额、Pix 提现及加密资产提现的平台。
• 已有用户，需要分别记录各客户资金并保留可核查轨迹的团队。

面临的问题

管理客户资金不仅是收款，还需要按客户隔离余额、冻结暂不可支用金额、追踪每笔变动，并能解释历史余额。这涉及账本、对账及审计记录，适合通过明确的接口能力接入。

使用同一个客户引用标识隔离余额。 customer_ref 贯穿收款单、余额、提现及流水；账本仅追加记录，每笔变动均有来源。您负责自有品牌体验，并将这些记录接入自身业务对账。

完整交易流程

1. 充值： POST /cashin/charge 并传入 destino: "saldo" 及 customer_ref 关联客户，Pix 记入其 BRL 子账户余额。
2. 查看： GET /saldo?customer_ref= 返回可用、冻结余额及后续释放时间。 GET /saldo/extrato 返回逐笔流水。
3. 以 BRL 提现： POST /payouts 使用同一 customer_ref ，确保从正确子账户扣款。
4. 以加密资产提现： POST /saldo/sacar-cripto 通过当前目录中的可交付路由发送，并在扣款前校验最低金额。
5. 客户之间转账： POST /saldo/transferir 在内部账本中处理，不调用外部支付渠道。

使用的接口

可运行示例

# 将收款记入终端客户子账户
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":50000,"destino":"saldo","customer_ref":"cliente_412",
       "payer_tax_number":"12345678909","external_id":"dep-412-88"}'

# 查询该客户余额
curl "https://api.luniumpay.com/saldo?customer_ref=cliente_412" -H "X-API-Key: $LUNIUM_KEY"

# 子账户之间的内部账本转账
curl -X POST https://api.luniumpay.com/saldo/transferir -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from_customer_ref":"cliente_412","to_customer_ref":"cliente_907",
       "amount_cents":15000,"external_id":"tr-9912"}'

const h = { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" };
const api = (rota, corpo) => fetch(`${API}${rota}`, corpo
  ? { method: "POST", headers: h, body: JSON.stringify(corpo) }
  : { headers: h }).then((r) => r.json());

export const depositar = (cliente, cents, cpf, id) => api("/cashin/charge", {
  amount_cents: cents, destino: "saldo", customer_ref: cliente,
  payer_tax_number: cpf, external_id: id,
});

export const saldoDe = (cliente) => api(`/saldo?customer_ref=${encodeURIComponent(cliente)}`);

export const sacarPix = (cliente, cents, chave, tipo, doc, id) => api("/payouts", {
  amount_cents: cents, pix_key: chave, pix_key_type: tipo,
  tax_number: doc, customer_ref: cliente, external_id: id,
});

export const sacarCripto = (cliente, cents, ativo, rede, carteira, doc, id) => api("/saldo/sacar-cripto", {
  amount_cents: cents, asset: ativo, chain: rede, payout_address: carteira,
  tax_number: doc, customer_ref: cliente, external_id: id,
});

import os, requests

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

def depositar(cliente, cents, cpf, ident):
    return requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": cents, "destino": "saldo", "customer_ref": cliente,
        "payer_tax_number": cpf, "external_id": ident}).json()

def saldo_de(cliente):
    return requests.get(f"{API}/saldo", headers=H, params={"customer_ref": cliente}, timeout=20).json()

def transferir(de, para, cents, ident):
    return requests.post(f"{API}/saldo/transferir", headers=H, timeout=30, json={
        "from_customer_ref": de, "to_customer_ref": para,
        "amount_cents": cents, "external_id": ident}).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。

异常处理

首次 Pix 的资金冻结： 余额可用性取决于项目条件。即时释放项目中，新付款人超过 R$ 100.00 的首次 Pix 仍可能由服务商冻结 24 小时，并显示为 delayed → GET /saldo，之后通过 saldo.liberado 自动释放。应向客户展示返回时间，而非通用错误。

余额不足： 402 会分别列明可用及冻结金额，不执行扣款。

提现低于币种最低金额： 会被拒绝，且发生在 扣款之前 ，并提供预估最低 BRL 金额，避免先扣款后才发现路由最低金额不满足。

安全机制

• 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 密钥或人工确认。

从哪里开始接入

充值与余额查询分别通过对应接口实现。API 提供当前费用及冻结条件，您的界面可据此解释资金状态，无需将规则固定写入代码。

接入常见问题