收银台接收 Pix，财资钱包接收稳定币

适用对象

• 面向巴西销售，并希望以稳定币管理资金的 B2C 商户或 marketplace。
• 付款人众多、单笔金额较小或中等的业务。
• 希望将手动 Pix 对账，升级为系统付款事件的团队。

面临的问题

电商接入加密资产结算时，常会担心全店当日交易量触及账户上限。该产品的关键限制按 实际付款人的证件及单笔交易计算，收款 API 密钥没有合并所有买家的每日总额上限。

另一个问题是对账。固定 Pix 收款标识收到款项后，未必能直接匹配订单。这里每张收款单关联买家 CPF 及您的 external_id；若由不同证件的账户付款，将按规则退款，而非静默成为无法归属的入账。

完整交易流程

1. 在收银台调用 POST /cashin/charge ，并提交总额、买家 CPF，以及以下字段中的订单号： external_id。
2. 向客户展示 qr_copypaste 。通常有效期为 15 分钟，实际以返回的到期时间为准；请在客户准备付款时生成。
3. 买家付款后，会收到 cashin.paid，可据此更新订单付款状态；加密资产交付仍须单独跟踪。
4. 稳定币交付至企业钱包后， cashin.settled 会提供交易哈希。
5. 对账： GET /cashin/charges?external_id= 可查询该订单对应的收款单。

使用的接口

可运行示例

# 一个订单对应一笔收款单，并提供实际购买人的 CPF
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":34990,"asset":"usdt","chain":"polygon",
       "payout_address":"0xCarteiraDaEmpresa",
       "payer_tax_number":"12345678909",
       "payer_name":"Maria S.",
       "external_id":"pedido-2026-33871"}'

// 结账：购买人准备付款时生成二维码
app.post("/checkout/:pedido/pix", async (req, res) => {
  const { total_cents, cpf, nome } = req.body;
  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: total_cents, asset: "usdt", chain: "polygon",
      payout_address: process.env.CARTEIRA_EMPRESA,
      payer_tax_number: cpf, payer_name: nome,
      external_id: `pedido-${req.params.pedido}`,
    }),
  });
  const c = await r.json();
  if (!r.ok) return res.status(r.status).json({ erro: c.erro, detalhe: c.detail });
  res.json({ copiaECola: c.qr_copypaste, expiraEm: c.expires_at });
});

// Webhook：验证签名后，才依据业务状态更新订单
app.post("/webhooks/lunium", verificarAssinatura, async (req, res) => {
  if (req.body.event === "cashin.paid") await marcarPago(req.body.data.external_id);
  res.sendStatus(200);
});

import os, requests
from flask import Flask, request, jsonify

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

@app.post("/checkout/<pedido>/pix")
def cobrar(pedido):
    dados = request.get_json()
    r = requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": dados["total_cents"], "asset": "usdt", "chain": "polygon",
        "payout_address": os.environ["CARTEIRA_EMPRESA"],
        "payer_tax_number": dados["cpf"], "payer_name": dados.get("nome"),
        "external_id": f"pedido-{pedido}"})
    c = r.json()
    if not r.ok:
        return jsonify(erro=c.get("erro"), detalhe=c.get("detail")), r.status_code
    return jsonify(copia_e_cola=c["qr_copypaste"], expira_em=c["expires_at"])

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

只需一次调用，无需预先审批或绑定银行卡，仅测试人员邮箱为必填项，手册、流程图及接入步骤将发送至该邮箱。 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。

异常处理

新付款人，金额较高： 分级即时到账额度从 R$ 100.00 开始。超出后仍可能接受二维码付款，但冻结 24 小时；如产品无法等待，可传入 allow_hold: false ，在创建时拒绝需要冻结的收款单，并显示可接受金额。

其他人代付： 由不同证件账户支付的 Pix 将按规则自动退回。与固定收款标识相比，此流程可明确识别资料不符的付款。

二维码过期： 收款单进入 expired。新建收款单须使用新的 external_id ；复用原 ID 会返回旧的过期二维码。

安全机制

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

从哪里开始接入

核心接入包含收银台接口与 webhook 处理器。一次调用可获得测试密钥，便于先验证流程；实际开发时间取决于产品及验收范围。

接入常见问题