REST API七种路径
选择接入方式
每种路径背后都是同一套账户、余额和报表，你可以先轻量起步，之后再逐步扩展。
直接 REST API最灵活
完整掌控收款、付款、虚拟账户、外汇和报表。通过 HTTPS 在你的服务器端调用 JSON 接口，每次状态变化都有签名 Webhook 通知。
直接 REST API —托管 WebCheckout零代码
将客户引导至 Localpayment 托管的收银台，使用你启用的本地支付方式。无需维护前端代码。
托管 WebCheckout —支付链接零代码
在 Business Portal 创建链接，通过邮件、短信或社交媒体分享。适合账单、远程销售和一次性收款。
支付链接 —嵌入式 iframe白标
在你自己的页面中嵌入白标收银台，保留你的品牌呈现，同时缩小 PCI 范围。
嵌入式 iframe —Smart Fields JS SDK自定义表单
托管的银行卡字段在浏览器中完成令牌化，并合并为一次性令牌，再由你的服务器发起扣款。表单设计由你掌控。
Smart Fields JS SDK —Business Portal 批量上传运营
上传付款和虚拟账户文件，并在门户中跟踪结果。财务和运营团队无需任何集成开发。
Business Portal 批量上传 —面向 AI 工具的 MCP 服务器AI 辅助
公开的只读 MCP 服务器和 llms.txt 让 Cursor、VS Code、Claude 等助手基于已记录的 API 进行开发。
面向 AI 工具的 MCP 服务器 —
对比
工作量、PCI 范围与适用场景
这是帮助你初选的参考。最终的 PCI 范围取决于你如何采集和存储银行卡数据，请与你的评估机构确认。
直接 REST API
- 工作量
- 高：服务器端开发
- PCI 范围
- 取决于银行卡数据的采集方式；可搭配 Smart Fields 或托管方案
- 适用场景
- 需要完全掌控收款、付款和外汇的平台
托管 WebCheckout
- 工作量
- 低：页面跳转
- PCI 范围
- 最小
- 适用场景
- 希望快速上线本地支付方式的团队
支付链接
- 工作量
- 极低：无需代码
- PCI 范围
- 最小
- 适用场景
- 账单、远程销售、一次性收款
嵌入式 iframe
- 工作量
- 低到中
- PCI 范围
- 缩小
- 适用场景
- 带品牌的收银台，无需处理银行卡字段
Smart Fields JS SDK
- 工作量
- 中：前端加服务器
- PCI 范围
- 共享
- 适用场景
- 自定义收银台设计并使用托管银行卡字段
Business Portal 批量上传
- 工作量
- 极低：上传文件
- PCI 范围
- 不涉及银行卡数据
- 适用场景
- 执行付款和虚拟账户的财务与运营团队
面向 AI 工具的 MCP 服务器
- 工作量
- 低：添加一个 URL
- PCI 范围
- 不适用：不涉及支付数据
- 适用场景
- 使用 AI 编码助手的工程师
Stage（沙箱）凭证在合作开始时发放。生产环境权限需在完成测试、安全审查和企业验证之后开通。
API 实战
典型的 API 收款全流程
四个角色，六个步骤。你的后端只需对接一个 API，本地支付通道由我们处理。
- 1
商户后端Localpayment API:
认证
POST /api/token/ 返回短时效访问令牌。调用来自你的服务器，且来源 IP 已加入白名单。
- 2
商户后端Localpayment API:
创建收款
POST /api/payin/，带上你自己的 externalId、国家、币种、金额和支付方式。
- 3
Localpayment API本地通道:
路由至本地通道
Localpayment 通过你启用的通道（如 Pix、SPEI 或 PSE）发送请求。
- 4
本地通道Localpayment API:
客户付款
通道确认付款。实时通道可在数秒内确认，全天候 24/7。
- 5
Localpayment APIWebhook 接收端:
签名 Webhook
带有 X-Signature HMAC-SHA256 头的 Webhook 通知最新状态。
- 6
Webhook 接收端商户后端:
验证并更新
校验签名，按 externalId 或 internalId 去重，返回 200 并更新订单。
使用虚构数据的简化示意。具体的请求与响应字段请参阅快速入门。
上线
从签约到生产环境
获取 Stage 凭证
沙箱凭证在合作开始时发放，因此在合规审查进行的同时，工程团队即可开工。
在 Stage 中开发与测试
Stage 与生产环境一致但不涉及真实资金。可使用测试卡、虚拟账户模拟器和 Postman 集合。
审查与验证
完成测试、安全审查和企业验证后，即可获得生产凭证。
数周内上线
切换基础 URL 和凭证，将 IP 加入白名单即可开始。新市场通过配置启用，无需重新集成。
常见问题
集成相关问题
我们应该从哪种路径开始？
如果你需要控制权且有工程师，请从 REST API 开始；如果想尽快启用本地支付方式，请使用 WebCheckout 或支付链接。同一账户下可以组合多种路径。
是否提供服务器端 SDK？
没有官方的服务器端 SDK。REST API 是基于 HTTPS 的 JSON，文档提供 cURL 和 Node.js 示例。唯一的 SDK 是客户端的 Smart Fields JS SDK。
API 调用如何保障安全？
调用须在服务器环境中通过 HTTPS 和 Bearer 令牌发起，并要求 IP 白名单。Webhook 使用 HMAC-SHA256 签名，便于你验证其来自 Localpayment。
如何避免重复扣款？
每笔交易都传入你自己的唯一 externalId。重复请求会返回 HTTP 409，Webhook 接收方应按 externalId 或 internalId 去重。
这对我们的 PCI 范围有何影响？
取决于所选路径。托管 WebCheckout 和支付链接使范围保持最小，嵌入式 iframe 会缩小范围，Smart Fields 为共享范围。请与你的评估机构确认结果。
AI 编码工具能提供什么帮助？
把 docs.localpayment.com/mcp 上公开的只读 MCP 服务器添加到 Cursor、VS Code、Claude 等工具中，它们就会读取已记录的 API，而不是凭猜测编写。
集成需要多长时间？
Stage 凭证在合作开始时发放，上线需要数周，具体取决于所选路径和你的审查周期。请联系销售获取适合你的计划。