Lunium 接入

# 通过 ChatGPT 与智能体完成接入

## Lunium Partners

官方接入者社区，提供运行通告、维护、API 变更及伙伴交流。强烈建议从接入初期开始关注。

[加入 Lunium Partners](https://t.me/+FerOZMRRP_g5MDk5)[参与方式](/zh/manual#lunium-partners)

## 业务操作与对账

配置佣金、理解费用、恢复监控访问，并按当前接口契约处理故障。

[费用与佣金](/zh/manual#comissoes)[恢复账户访问权限](/zh/manual#recuperar-acesso)[处理故障](/zh/manual#incidentes)

修订日期：2026 年 10 月 6 日。引导入口：https://luniumpay.com/zh/integrar 。机器可读规范：https://docs.luniumpay.com/zh/integration.json 。

## 通过 Pix 收款，将 USDT 收入钱包

向 AI 提出需求： **“我希望通过 Pix 收取 R$100，并将 USDT 收入我的钱包。请显示预计净到账数量，生成二维码，并跟踪付款。”**

1. **提供收款信息：** 巴西雷亚尔金额、实际付款人的证件信息，以及钱包地址和正确网络。AI 会查询费率、最低金额与预计净到账数量。
2. **展示二维码：** 收款单返回二维码图片、Pix 复制粘贴码和有效期。付款人通过银行应用完成支付。
3. **跟踪结果：** AI 会告知 Pix 已收款及 USDT 发送已登记，并在可用时提供交易链接。链上确认属于后续独立阶段。

开展真实收款前，请通过 [自助注册](https://luniumpay.com/zh/#chave-producao) 创建访问凭证，并连接到兼容以下端点的宿主： `https://api.luniumpay.com/mcp`。在宿主的安全配置中设置密钥，不要将密钥粘贴到对话中。下方公开连接仅提供演示；目前尚不支持通过 OAuth 关联生产账户。

费用、最低金额和资金暂缓可用规则会在创建收款单前告知。USDT 数量在兑换完成前均为估算。注册与接入无需先进行商务洽谈。 [结构化规范](/zh/integration.json) 提供完整流程，见 `receive_pix_usdt_in_chat`。

## 使用加密资产支付 Pix，并获取付款凭证

向 AI 提出需求： **“我希望使用加密资产向这个 Pix 收款键支付 R$100。请显示报价与转入说明，随后跟踪付款并提供凭证。”**

1. **提供 Pix 信息：** 收款键和巴西雷亚尔金额，或收款单完整的 Pix 复制粘贴码。
2. **选择币种与网络：** AI 会查询可用选项，并显示加密资产数量、巴西雷亚尔金额、费用和有效期。复制粘贴码付款目前在兼容通道支持 USDT／USDC；按收款键付款还可使用目录中的其他币种。
3. **核对信息并获取转入说明：** 接受报价后，系统提供入金地址，以及必需时的 memo／tag。
4. **转入加密资产：** 在返回的有效期内，按照指定数量和网络转入，并填写必要的 memo／tag。跟踪信息包括入金、确认数、所需兑换及 Pix 付款。
5. **获取付款凭证：** Pix 付款完成后，AI 会提供 E2E 标识，以及可用的凭证、PDF 和验证链接。如凭证仍在生成，则继续跟踪同一笔付款。

处理时长取决于网络和 Pix 处理情况。转入前请核对报价费用；使用复制粘贴码付款时，额外处理金额已计入显示的总额。请始终使用原始收款码，不要将 Pix 复制粘贴码付款改为向其中提取的收款键转账。

如交易延迟、审核或退款，请持续跟踪原订单。不要因超时或凭证暂未生成而再次转账。真实操作使用上述完整 MCP 及安全配置；下方公开连接仅用于演示。

## 在 ChatGPT 中了解并测试

符合条件的账户或工作区可按策略添加自定义 MCP 服务器并创建插件。功能与菜单以官方说明为准：https://developers.openai.com/plugins/deploy/connect-chatgpt 。

1. 打开 ChatGPT 的 Plugins（插件）页面，选择添加自定义 MCP 服务器。
2. 填写连接名称与描述，例如 **Lunium — 接入**，并在连接配置中提供 URL `https://api.luniumpay.com/mcp/onboarding`。此公开演示连接无需账户认证。检查工具与风险提示后，按界面指引创建插件；可用性取决于账户和工作区策略。
3. 安装插件，在新的 Work（工作）对话中通过 @ 选择它，再提出：“请规划一个通过 Node.js 接入 Lunium、将 Pix 收款记入托管余额的方案。执行沙盒演示，并为我的项目准备代码。”
4. 智能体会查询 `lunium_plan_integration`，调用 `lunium_start_sandbox_demo` 时传入 UUID、测试者的 `email` （MCP 工具中为选填，但强烈建议提供：LuniumPay 会向本人发送一次接入指南，内容包括服务介绍、手册、流程图与后续步骤。未提供邮箱时仍应创建密钥，之后可通过 `lunium_contact`补充）及 `flow` 等于 `custody`、 `cashin`、 `payout` 或 `cashout`，并跟踪 `lunium_get_sandbox_demo`。模拟流程最终进入 `COMPLETED`；不会发生真实资金流动。
5. 随后继续使用代码工具包和上线检查表。如需人工协助，请提供邮箱并授权调用 `lunium_contact`。人工联系为可选服务。

公开连接支持方案规划、目录查询、模拟测试和经同意的联系，不会关联生产账户。Lunium 账户连接 ChatGPT 的 OAuth 功能尚未实现；相关要求见 https://developers.openai.com/plugins/build/auth 。完整 MCP 端点 `/mcp` 还提供账户工具，供能够安全配置 `X-API-Key` 的宿主使用。不要在对话中粘贴生产密钥。

提供 MCP 端点并不代表已经自动上架 ChatGPT 应用目录。如果账户中没有连接选项，请使用下方接入需求模板与工具包。

## 使用任意编程 AI 开始接入

打开 https://luniumpay.com/zh/integrar ，选择业务流程和编程语言，然后复制接入需求模板。提供要修改的项目。模板会指向现行规范，并要求完成实现、测试，以及说明仍待验证的项目。

下载 https://docs.luniumpay.com/zh/starter/lunium-starter.zip 。运行 `node sandbox.mjs all` （Node 20+），或 `python3 sandbox.py all` （Python 3.9+）。无需额外依赖。脚本会在内存中创建测试密钥，使用 `LUNIUM_SANDBOX_EMAIL`提供测试人员邮箱；随后模拟选定流程，或通过 `all`运行全部流程，查询状态，并拒绝生产密钥。也可通过环境变量复用 `lun_test_` 测试密钥，变量名为 `LUNIUM_API_KEY`。

工具包中的 `AGENTS.md` 文件用于指导仓库内的 AI，不替代项目自身的指令。测试代码：https://docs.luniumpay.com/zh/starter/sandbox.mjs 和 https://docs.luniumpay.com/zh/starter/sandbox.py 。

## 选择要实现的业务流程

- **Pix 收款记入托管余额：** `POST /cashin/charge` 并传入 `destino: "saldo"`。入账币种为 BRL，不要求固定钱包。 `payer_tax_number` 必须为实际付款人的证件信息。 `customer_ref` 用于选择子账户。
- **从托管余额提取加密资产：** 通过 `/saldo`查询可用余额，通过 `/cashin/catalog` 查询通道，再选择币种、 `chain`、地址及必需的 memo。提交 `POST /saldo/sacar-cripto`。不要承诺目录中所有币种都可用；请核对 `entregavel` 及限额。
- **Pix 收款后直接交付加密资产：** 使用 `destino: "cripto"`、交付目录及 `POST /cashin/preview` ，再创建收款单。
- **加密资产卖出至 Pix：** 使用 `/catalog`、 `POST /cash-outs`、接受报价与状态跟踪。沙盒也支持此流程。
- **Pix 对外付款：** 通过 `/keys/me`确认权限，通过 `/saldo`查询可用余额与费用；通过 `POST /payouts` 创建付款，并跟踪返回的 ID。

买入及加密资产提现的网络字段为 `chain`；卖出流程的网络字段为 `network`。买入和付款流程中的巴西雷亚尔金额以整数分表示。卖出流程中， `brl_amount` 为以巴西雷亚尔为单位的十进制字符串，例如 `"100.00"`；加密资产数量同样使用十进制字符串。各接口结构定义见 https://docs.luniumpay.com/zh/openapi.json 。

## 测试能够证明什么

沙盒覆盖 Pix 入金、托管余额入账、加密资产提现与交付、Pix 付款、内部转账及加密资产卖出。二维码不是银行支付码；通过以下接口模拟确认付款： `POST /sandbox/cashin/{cashin_id}/pay`。所有数据均为模拟数据，不会调用银行、交易所或区块链。故障场景、资金暂缓可用、余额不足、结果不确定、签名 Webhook 及与生产环境的差异，见 https://docs.luniumpay.com/zh/sandbox 。

公开演示使用固定的模拟数据，不接收真实钱包、Pix、金额或生产密钥。测试标识符在两小时后失效；模拟财务状态在重启后仍保留；卖出流程的资金保留时长为两小时。重试时复用 `request_id` ，并使用 `demo_id` 跟踪状态。一次测试通过并不代表整个接入已完成验证。

## 操作真实资金之前

请阅读 https://docs.luniumpay.com/zh/manual 。核对密钥权限和限额、各通道最低金额及费用、实际证件与收款对象、可用余额和暂缓可用规则。为每个操作意图持久化保存 `external_id` ，重试时不更改请求；验证 Webhook 原始请求体的 HMAC、时间戳，并对事件去重。请求超时后，先查询原操作。

买入流程仅在以下条件同时满足后完成： `status=paid` **及** `settlement_status=sent`；卖出流程为 `state=COMPLETED`；付款流程为 `status=sent`。不要将 `delayed` 视为失败。密钥与密文仅保存在后端。首次执行所选流程的真实交易前，须取得明确授权。

## 人工支持与实时跟踪

**强烈建议建立人工支持群组：** Lunium 或合作伙伴可创建项目群组，并添加 [@luniumb2b](https://t.me/luniumb2b) 及 [@luniumb2c](https://t.me/luniumb2c)，以及 [@LuniumNotifyBot](https://t.me/LuniumNotifyBot)。 [查看群组使用指南](/zh/manual#telegram)。交易跟踪可使用以下接口返回的私密监控： `/keys/me` ，并实现 [Webhook、实时控制台及对账](/zh/manual#monitor-ao-vivo)。不要向未授权人员分享密钥、签名密钥或私密监控链接。

简体中文版：2026年10月17日 · 当前 API：1.44.7。历史修订日期按原记录保留。