REST + JSON文档
直达您需要的内容
直接链接到 docs.localpayment.com 的指南、API 参考和工具。
身份验证
用 API 用户名和密码换取 5 分钟有效的访问令牌和 24 小时有效的刷新令牌。
身份验证 —第一笔测试支付
分步引导您在 Stage 创建并确认一笔收款。
第一笔测试支付 —收款（Pay-in）
银行卡、虚拟账户和本地支付方式，全部通过同一个 Create Payin 端点。
收款（Pay-in） —付款（Payout）
通过本地清算通道向银行账户和电子钱包付款，可选双重签名审批。
付款（Payout） —虚拟账户
为每位客户开立本地账号，每笔转入资金自动匹配。
虚拟账户 —Webhook
每次状态变化都会实时推送签名通知。
Webhook —状态码与错误码
按交易类型列出全部代码，从 100 INPROGRESS 到 906 拒付。
状态码与错误码 —Postman 集合
现成的请求示例，附带 Stage 环境文件。
Postman 集合 —系统状态
实时查看收款、付款和身份验证服务的可用性及历史事件。
系统状态 —
最初的几次调用
验证身份、发起收款、确认结果
三步即可跑通核心流程：获取令牌、创建收款、验证确认该笔收款的签名 Webhook。同一套请求、状态和 Webhook 模型适用于各个国家和支付方式。
- 令牌 5 分钟后过期，可通过 POST /api/token/refresh/ 刷新
- 每笔交易都要传入您自己的唯一 externalId
- 最终状态通过 Webhook 送达，并以 HMAC-SHA256 签名
# 1) 获取访问令牌（Stage · 有效期 5 分钟）
ACCESS_TOKEN=$(curl -s -X POST https://api.stage.localpayment.com/api/token/ \
-H "Content-Type: application/json" \
-d "{\"username\": \"$LP_API_USER\", \"password\": \"$LP_API_PASSWORD\"}" \
| jq -r .access)
# 2) 创建 Pix 收款（示例，数值均为虚构）
curl -X POST https://api.stage.localpayment.com/api/payin/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"paymentMethod": { "type": "BankTransfer", "code": "1314", "flow": "DIRECT" },
"externalId": "7c1e2f7a-0000-4000-8000-000000000001",
"country": "BRA",
"currency": "USD",
"amount": 100,
"accountNumber": "<your-account-number>",
"conceptCode": "0003",
"merchant": { "type": "COMPANY", "name": "Nortia Commerce Ltda" },
"payer": {
"type": "INDIVIDUAL",
"name": "Maria",
"lastname": "Silva",
"document": { "type": "CPF", "id": "000.000.000-00" }
}
}'API 设计
设计上可预期
跨产品、跨国家保持一致的约定，让您的集成代码同样保持稳定。
REST 与 JSON
面向资源的 URL、标准 HTTP 方法和状态码、JSON 请求体。国家使用 ISO-3 代码，例如 BRA 或 MEX。
短时效 Bearer 令牌
POST /api/token/ 返回 5 分钟有效的访问令牌和 24 小时有效的刷新令牌，以 Authorization: Bearer 方式发送。
您的 ID 与我们的 ID
每笔交易携带您的 externalId，我们返回自己的 internalId。两者都可用于查询状态或对账。
防重复提交
重复使用 externalId 会返回 409 Conflict，而不会创建第二笔交易，因此超时的请求可以安全重试。
可据以分支的状态码
每个响应都包含带 code、description 和 detail 的 status 对象及 errors 数组，代码族告诉您下一步该做什么。
限流与退避
请求过多会返回 429。请使用指数退避和熔断器重试，5xx 响应和代码 800 同样适用。
错误处理
状态码族一览
每个响应都包含 status.code，首位数字告诉您应该等待、修正、重试还是冲正。
1xx
- 含义
- 处理中
- 示例
- 100 INPROGRESS
- 处理方式
- 等待 Webhook，或主动查询状态
2xx
- 含义
- 成功
- 示例
- 200 COMPLETED
- 处理方式
- 履约并更新您的账本
3xx
- 含义
- 校验失败
- 示例
- 300 被拒（参数无效）· 301 未获该国授权
- 处理方式
- 修正请求，不要原样重试
7xx
- 含义
- 业务规则
- 示例
- 701 账户无效 · 702 余额不足
- 处理方式
- 向用户给出清晰提示，或通知运营团队
8xx
- 含义
- 通道或系统
- 示例
- 800 可重试错误
- 处理方式
- 使用指数退避重试
9xx
- 含义
- 冲正类
- 示例
- 902 已退款 · 904 多次重试失败后订阅取消 · 906 拒付
- 处理方式
- 撤销履约并更新账本
使用的 HTTP 状态码：200、201、400、401、403、404、409、429、500、502 和 503。各交易类型的完整代码表见文档参考。
集成流程
从第一次调用到正式上线
大部分工作在 Stage 完成。通过安全评审和企业验证后即可获得生产环境访问权限。
- 01
获取 Stage 凭证
合作启动时即发放 Stage 凭证。在 Business Portal 中将服务器 IP 加入白名单。
Stage
- 02
开发与测试
集成收款、付款或虚拟账户，处理 Webhook，并用测试数据演练各种失败场景。
Stage
- 03
安全评审与 KYB
我们会评审您的集成并完成企业验证（KYB），随后发放生产凭证。
合规
- 04
上线并扩展
切换到生产凭证和 IP。通过配置增加国家和支付方式，无需重新集成。
生产
AI 开发者工具
让您的 AI 助手读懂我们的文档
Localpayment 文档专为 AI 辅助开发工具而构建，包括 MCP 服务器、即用型提示词，以及面向 AI 系统设计的结构化访问。
- MCP 服务器地址 docs.localpayment.com/mcp，无需身份验证
- llms.txt 索引，且每个文档页面都有 Markdown 版本
- 提示词库，以及适配主流智能体框架的集成与 QA 智能体
- 文档内置 “Ask AI” 问答
{
"mcpServers": {
"localpayment-docs": {
"url": "https://docs.localpayment.com/mcp"
}
}
}安全
默认安全，从第一个请求开始
安全控制内建于 API 和 Business Portal，而不是事后补上。
传输与存储加密
传输中使用 TLS 1.2+，静态数据使用 AES-256 加密，并通过 AWS KMS 轮换密钥。
仅限服务器间调用
调用必须通过 HTTPS 从您的后端发起。切勿在浏览器或移动应用中暴露凭证或令牌。
IP 白名单
只有在 Business Portal 中加入白名单的服务器 IP 才能调用 API，Stage 和生产环境分别配置。
签名 Webhook
每条通知都带有 HMAC-SHA256 签名，任何非我们发出的请求都可以拒绝。
付款双重签名
付款离开账户前可要求第二位审批人确认，支持 API 和门户两种方式。
MFA 与基于角色的权限
Business Portal 用户通过多因素认证登录，只获得其角色所需的权限。
开发者常见问题
有 SDK 吗？
没有官方服务端 SDK：API 是标准的 REST 和 JSON，任何 HTTP 客户端都能使用。对于银行卡表单，Smart Fields JavaScript SDK 会在托管字段中对卡数据进行令牌化，缩小您的 PCI 范围。
如何获取沙盒凭证？
Stage 凭证在合作启动时发放。请通过联系表单告诉我们您的项目，我们的团队会全程协助您完成入驻。
应该使用哪些 Base URL？
Stage：https://api.stage.localpayment.com。生产：https://api.v3.localpayment.com。每个环境都有独立的凭证。
集成需要多长时间？
团队通常在数周内上线。完成集成后，新市场通过配置开通，无需重新集成。
如何处理重试和重复请求？
每笔交易传入唯一的 externalId。使用相同 externalId 重试时会收到 409 Conflict，而不会产生重复交易。遇到 429、5xx 和代码 800 时请使用指数退避重试。
在哪里查看服务状态？
访问 status.localpayment.com，可查看收款、付款、身份验证服务、本地通道及历史事件。如需帮助，请发送邮件至 support@localpayment.com，我们提供 24/7 支持。