面向钱包与平台 · 加密资产 → Pix
使用加密资产支付 Pix，跟踪付款并取得凭证
使用外部钱包的加密资产向收款人支付 Pix。发送前先查询报价、确认金额并取得充值说明。跟踪付款，在凭证链接可用后获取证明。
如何与您的 AI 开始接入
可使用 Gemini、ChatGPT 或其他 AI，了解流程并准备接入。
填写 Pix 并选择加密资产
提供收款标识及 BRL 金额，或完整 Copia e Cola 支付码。AI 查询支持的币种与网络，并展示报价、成本及到期时间。
确认并发送
核对实际 Pix 金额及精确加密资产数量。接受报价后，按正确网络向返回地址发送，必要时填写 memo/tag。
跟踪付款进度
跟踪充值、网络确认及 Pix 付款。交易会在可用时提供 E2E 及凭证链接，凭证可能晚于付款生成。
可交给 AI 的需求示例
我想通过 Lunium 使用加密资产支付 Pix。请核对可用币种及网络，展示报价并说明如何连接账户。连接工具后，请在接受报价前征求我确认，并跟踪至取得凭证。
收款标识付款按目录支持范围执行。Copia e Cola 目前仅支持兼容路由上的 USDT/USDC。时效取决于网络及 Pix 处理。
聊天中执行真实交易，需要已连接到您账户的智能体。Lunium 公共连接器提供演示，目前尚不支持在 ChatGPT 中通过 OAuth 连接生产账户。不要在聊天中粘贴生产密钥。
从客户钱包到 Pix 收款账户
Cash-out 将外部加密资产兑换为 BRL，适用于向持有链上资产的用户提供 Pix 提现的钱包或平台。入金币种及网络须存在于 GET /catalog；该目录与 Pix 收款后交付加密资产的目录不同。
先报价，再充值
使用 POST /cash-outs ，传入加密资产数量或期望 BRL 金额。展示净额、收款人、网络及有效期。
接受报价
调用 POST /cash-outs/{cashout_id}/accept，之后才展示充值地址、精确金额及必要的 memo。
跟踪直至 Pix 完成
查询订单或接收 webhook。充值确认不代表 Pix 已支付，请等待 state=COMPLETED。
资金已位于 Lunium BRL 余额中？请使用 Pix 对外付款 扣减该余额；cash-out 用于接收一笔新的外部加密资产充值。
USDT 兑换 Pix 报价示例
使用 lun_test_密钥并保存在后端，确认 key.sandbox=true → GET /keys/me。下方示例的证件及收款地址均为虚构数据，不要使用生产凭证提交。
POST /cash-outs · 测试环境请求体示例
{
"asset": "USDT",
"network": "polygon",
"amount": "10.00",
"pix_key": "teste@example.com",
"pix_key_type": "email",
"external_id": "sandbox-usdt-pix-001"
}发送至 https://api.luniumpay.com/cash-outs 并传入 X-API-Key ，并以 JSON 提交。保存返回的 cashout_id ，接受报价后持续跟踪 GET /cash-outs/{cashout_id}。创建在生产环境可能返回 200，测试环境可能返回 201；按契约处理成功，不要只接受其中一个状态码。
| 字段 | 接入规则 |
|---|---|
amount | 加密资产数量须为十进制字符串，例如 "10.00"，不要使用浮点数。 |
brl_amount | 也可从期望 Pix 金额反向报价，例如 "50.00"。向收款标识付款时传入 amount 或 brl_amount；带金额的收款码则仅传入 br_code 的完整内容，不传上述两个金额字段及 pix_key，且须为兼容的 USDT/USDC 路由。 |
network | 以下目录中的加密资产入金网络： GET /catalog。不要直接使用交付目录中的网络列表。 |
refund_address | 请确认退款钱包由退款收款人控制，且符合退款资产与网络。兑换后，退款资产及网络可能与最初发送的资产不同。订单要求地址时，请遵守 refund_asset、 refund_network ，并使用已验证身份的 AWAITING_REFUND_ADDRESS。 |
测试环境在接受报价后模拟充值及 Pix，切勿向虚构地址发送真实加密资产。完整测试可使用 node sandbox.mjs cashout 或 python3 sandbox.py cashout 否 接入工具包。
何时视为 Pix 已完成
| 步骤 | 状态与处理方式 |
|---|---|
| 报价与充值 | QUOTE_CREATED、 AWAITING_DEPOSIT、 DEPOSIT_DETECTED：保持同一订单，展示其对应说明。 |
| 网络确认与执行 | DEPOSIT_CONFIRMED、 SELLING、 SOLD、 FORWARDING、 PAYING_OUT：持续跟踪，并非每条路由都会经历全部阶段。 |
| 付款完成 | COMPLETED：核对 pix_e2e、 pix_paid_at、 receipt_url 及 verify_url等字段（如有）。链接可能稍后生成，请继续查询原订单或跟踪 cashout.receipt_ready。 |
| 异常情况 | MANUAL_REVIEW、 REFUNDING_CRYPTO、 REFUNDED、 EXPIRED 及 FAILED 须分别处理。 |
请使用接口返回的凭证链接。公开 E2E 查询仅核验已知 Pix，不能替代完整流程确认。退款时持续跟踪 REFUNDED 及 refund_tx_hash，金额及时效取决于已到达的阶段及服务商。
保存 external_id 及返回标识后，再更新您的订单。重试保持相同引用及请求体。配置 HTTPS 接收端，对原始请求体验证 HMAC 签名，并按 event_id去重。超时后，先查询原交易再决定是否重试。 Webhook 与对账手册 提供完整实现说明。
收银台中的网络、退款及限额
通过以下接口查询密钥限额： GET /keys/me ，并查看报价中的实际条件。仅在报价有效时展示交易选项，按返回网络发送精确金额，并在需要时填写 deposit_tag 。逾期或金额不符的充值须在原订单中核对，不得将地址用于另一笔卖出交易。
生产环境不要将充值链上来源直接用作退款地址，须确认客户控制权；交易所提币可能来自共用钱包。请登记适合的 refund_address 。路由可用性、成本及确认要求可能变化。
接入常见问题
USDT 兑换 Pix 与 Pix 对外付款有何区别？
USDT 兑换 Pix 接收新的加密资产转账后支付 BRL；Pix 对外付款使用已可用的 BRL 托管余额。请根据交易开始前资金所在位置选择流程。
可以指定收款人应收到的 BRL 金额吗？
使用 brl_amount 指定目标 BRL 金额。报价返回精确加密资产数量及实际 Pix 金额，后者可能因舍入略有差异。接受前须核对金额、有效期、费用及限额。
必须用 CPF 识别收款人吗？
须提供有效 Pix 收款标识。11 位纯数字标识必须明确其类型为 cpf 或 phone。辅助收款人查询可能不可用；若返回 verified=false。
可以使用加密资产支付任意 Pix 二维码吗？
通过 br_code 付款的可用性独立判断，生产环境可能拒绝。不要将其视为与收款标识付款完全等同，或默认始终启用。