沙盒
在 Stage 测试每个流程，无需动用真实资金
Stage 与生产环境一致：同样的 API 契约、同样的 Webhook，以及独立的 Business Portal。您基于上线后将使用的同一契约进行开发和测试，只有资金是模拟的。
- 与生产环境一致
- 测试卡和模拟器
- Postman 集合
与生产环境一致概览
USD
1,284,560.00
+4.2%
BRL
3,420,118.40
+12.8%
MXN
8,905,332.10
+6.1%
- 收款 · Pixorder_8F2K-1043+ R$ 1,250.00
- 付款 · SPEIseller_0921− MX$ 18,400.00
- 换汇 · BRL → USDfx_3b7q250,000.00 USD
- 收款 · Bre-Border_9A1C-2210+ COP 890,000
环境
两个环境，一次集成
只需更换 Base URL 和加载的凭证即可切换环境。
API Base URL
- Stage（沙盒）
- https://api.stage.localpayment.com
- 生产
- https://api.v3.localpayment.com
Business Portal
- Stage（沙盒）
- ui.stage.localpayment.com
- 生产
- ui.v3.localpayment.com
资金
- Stage（沙盒）
- 模拟资金，不产生真实资金流动
- 生产
- 真实资金，经由真实通道
凭证
- Stage（沙盒）
- 合作启动时发放
- 生产
- 完成 Stage 测试、安全评审和 KYB 后发放
数据
- Stage（沙盒）
- 仅限虚构的测试数据
- 生产
- 真实客户数据，由您与我们双方的安全控制共同保护
IP 白名单
- Stage（沙盒）
- 必须配置
- 生产
- 必须配置
Stage 与生产环境的凭证不同，请分别作为独立密钥保存。
可测试的内容
预演您将在生产环境运行的一切
银行卡收款
授权成功、拒绝、3D Secure 验证和处理错误，每种结果都有对应的测试卡号。
虚拟账户
创建账户并模拟转入，完整演练匹配、对账和 Webhook 流程。
本地支付方式
创建 Pix 等本地支付方式的收款，查看二维码、付款说明和待处理状态。
付款（Payout）
运行文档中的付款沙盒场景，查看付款流程中的每个状态。
端到端 Webhook
把 Stage 的通知 URL 指向您的端点，在上线前完成签名验证。
失败处理
重复提交 externalId 查看 409 Conflict，让令牌过期，并演练带退避的重试。
测试卡
覆盖每种结果的测试卡号
有效期填写任意未来日期。CVC：任意 3 位数字（Amex 为 4 位）。
4242 4242 4242 4242
- 结果
- 授权成功
- 用于测试
- 正常流程：授权、确认和 Webhook
4000 0000 0000 0002
- 结果
- 拒绝
- 用于测试
- 结账页中的拒绝提示和重试引导
4000 0025 0000 3155
- 结果
- 3D Secure 验证
- 用于测试
- 身份验证环节及返回您的流程
4000 0000 0000 9995
- 结果
- 处理错误
- 用于测试
- 错误处理、日志记录和客户提示
仅适用于 Stage。银行卡收款支持阿根廷、哥伦比亚、墨西哥和秘鲁；3D Secure 适用于哥伦比亚、墨西哥和秘鲁。
虚拟账户模拟器
随时模拟一笔银行转账
无需等待真实转账：在 Stage 创建虚拟账户并调用模拟器，即可跟踪这笔模拟款项的匹配、状态变化和通知处理。
- POST /api/simulate/va 仅在 Stage 可用
- 上线前用它演练 VirtualAccount Webhook 的处理逻辑
- 非常适合在 CI 流水线中运行自动化端到端测试
# 仅限 Stage。请求体仅为示例，确切字段请参阅测试指南。
# 1) 为测试客户创建虚拟账户（墨西哥，CLABE）
curl -X POST https://api.stage.localpayment.com/api/virtual-account \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"externalId": "3b9f6c1e-0000-4000-8000-000000000123",
"country": "MEX",
"currency": "MXN",
"beneficiary": { "name": "Ana Torres", "document": { "type": "RFC", "id": "TOAA800101XXX" } }
}'
# 2) 模拟一笔转入该账户的银行转账
curl -X POST https://api.stage.localpayment.com/api/simulate/va \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountNumber": "646180000000004821",
"amount": 1250.00,
"currency": "MXN"
}'
# 3) 您的 Webhook 端点会收到一条 VirtualAccount 通知Postman
导入集合，发送第一个请求
Localpayment 的 Postman 集合附带 Stage 环境文件，让您在写代码之前就能探索 API。
- 附带 STAGE 环境文件，所有请求直接指向沙盒
- 配合 API 参考查看请求与响应的结构
- 在本地填入您的 Stage 凭证，切勿共享包含凭证的工作区
最佳实践
像对待生产环境一样测试
只用虚构数据
使用编造的姓名和证件号。绝不要把真实客户数据或银行卡数据导入 Stage。
密钥分开管理
Stage 与生产凭证分开存放，各自保存在密钥管理服务中。
测试异常路径
拒绝、3D Secure、超时、409 重复和令牌过期，而不只是成功场景。
演练 Webhook 重试
先返回一次非 200 响应，确认您的处理程序对重试投递只处理一次。
注意令牌有效期
访问令牌有效期为 5 分钟。现在就实现刷新逻辑，不要等到上线后。
自动化测试套件
在 CI 中借助虚拟账户模拟器，对 Stage 运行端到端测试。
获取访问权限
如何获取 Stage 凭证
- 01
介绍您的项目
通过联系表单告诉我们您的业务场景、目标市场和预期交易量。
- 02
启动合作
商定商务条款后开始入驻流程，其中包括合规审查。
- 03
获取 Stage 凭证
您将获得 Stage 的 API 用户名和密码，以及 Stage Business Portal 的访问权限。
- 04
配置白名单并开始开发
添加服务器 IP，导入 Postman 集合，然后按照快速入门操作。
沙盒常见问题
Stage 会产生真实资金流动吗？
不会。Stage 以模拟资金复现生产环境的行为，您在其中的任何操作都不会触达真实的银行、卡组织或电子钱包。
可以在 Stage 使用真实客户数据吗？
不可以。请只使用虚构的姓名、证件号和卡号。真实的个人数据或银行卡数据绝不能发送到测试环境。
Stage 与生产环境有何不同？
API 契约和 Webhook 完全相同。支付是模拟的（例如虚拟账户转账来自模拟器），因此处理时长不代表真实通道的表现。
如何切换到生产环境？
完成 Stage 测试、安全评审和企业验证（KYB）后，我们会发放生产凭证。完整的上线检查清单见快速入门。
遇到问题应该联系谁？
发送邮件至 support@localpayment.com（24/7 支持），或使用文档中的 “Ask AI” 快速获取答案。