用同一 API 接入巴西法币与加密资产的双向兑换

适用对象

• 希望在巴西销售、付款或收款，又无需从零搭建本地支付基础设施的境外企业。
• 需要接入 BRL 交易对的交易所或经纪服务商。
• 已计划接入 Pix，并希望整合支付渠道的全球化产品。

什么是 On-ramp 与 Off-ramp？

On-ramp（法币兑换加密资产） 指传统法币进入加密资产的过程。在此流程中，客户支付 Pix，应用跟踪资产在所选网络上的交付。 Off-ramp（加密资产兑换法币） 指加密资产兑换回法币：报价、接受报价及充值确认后，交易进入 Pix 付款流程。

Pix 托管收款是另一种选择，资金保持为 BRL，直至请求提现。收到 Pix 不代表余额已兑换为稳定币。

完整交易流程

1. 入金： POST /cashin/charge 按实际付款人的 CPF/CNPJ 创建实名 Pix 二维码。付款后，持续跟踪可能的资金冻结及加密资产交付，直至最终状态。
2. 出金： POST /cash-outs 获取报价， /accept 接受后锁定价格并取得地址；充值确认后，Pix 收款账户收到 BRL。
3. 托管余额（可选）： 并传入 destino: "saldo" 可将 Pix 收款记入子账户 BRL 余额，之后使用 POST /payouts 发起付款。
4. 双向流程共用同一密钥、相同错误格式（erro + acao）及相同的 external_id。
5. 请验证 webhook 签名，并通过状态查询核对缺失或延迟事件。

使用的接口

请求示例 — 请替换示例资料

# 入金：Pix 兑换稳定币并发送至钱包
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":100000,"asset":"usdc","chain":"polygon",
       "payout_address":"0xTesouraria","payer_tax_number":"12345678909",
       "external_id":"in-9001"}'

# 出金：稳定币兑换为指定收款人的 Pix 付款
curl -X POST https://api.luniumpay.com/cash-outs -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset":"USDC","network":"polygon","brl_amount":"1000.00",
       "pix_key":"11122233344","pix_key_type":"cpf","external_id":"out-9001"}'

const API = "https://api.luniumpay.com";
const h = { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" };

export const entrada = (cents, carteira, docPagador, id) =>
  fetch(`${API}/cashin/charge`, { method: "POST", headers: h, body: JSON.stringify({
    amount_cents: cents, asset: "usdc", chain: "polygon",
    payout_address: carteira, payer_tax_number: docPagador, external_id: id,
  })}).then((r) => r.json());

export const saida = (brl, chave, tipo, id) =>
  fetch(`${API}/cash-outs`, { method: "POST", headers: h, body: JSON.stringify({
    asset: "USDC", network: "polygon", brl_amount: brl,
    pix_key: chave, pix_key_type: tipo, external_id: id,
  })}).then((r) => r.json());

import os, requests

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

def entrada(cents, carteira, doc_pagador, ident):
    return requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdc", "chain": "polygon",
        "payout_address": carteira, "payer_tax_number": doc_pagador,
        "external_id": ident}).json()

def saida(brl, chave, tipo, ident):
    return requests.post(f"{API}/cash-outs", headers=H, timeout=30, json={
        "asset": "USDC", "network": "polygon", "brl_amount": brl,
        "pix_key": chave, "pix_key_type": tipo, "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。

异常处理

各错误包含 erro （发生了什么）及 acao （如何处理）： corrigir、 repetir、 esperar 或 parar。智能体或自动重试程序可依此采取操作，无需猜测自由文本。

parar 尤其重要：提现遇到 provedor_sem_resposta 时，Pix 可能已发出。请查询原交易，不要重复发送。

安全机制

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

从哪里开始接入

一次调用即可获取测试密钥，无需预先审批。测试环境使用虚拟金额验证文档列出的流程及场景，报价及部分模拟响应有独立字段。服务真实客户前，请核对手册，并通过生产试点验证配置及实际结算。

Pix、On-ramp 与 Off-ramp 常见问题

为团队准备接入方案

通过检查清单明确流程、核对余额与最低金额、测试失败场景，并在试点前保存证据。清单既可由开发者填写，也可用作 AI 智能体的上下文。

下载接入检查清单（Markdown） · 使用 AI 接入 · 全部指南

LuniumPay 团队技术资料 · 核查日期 2026年9月18日。 了解公司。