跳转到主要内容
了解如何使用 Localpayment API 进行首次测试付款,并了解在沙盒环境中运行安全支付流程的基本要素。 首先,在沙盒环境中使用 Localpayment API 进行首次测试支付。您将验证请求、探索可用的支付方式、执行信用卡支付、管理 Webhook 并检查最终交易状态。

概述

Localpayment 沙盒是一个完整的测试平台,它模拟了我们的生产环境,但不会处理真实交易。它提供了一个安全的空间,让您在正式上线前测试各种支付方式、货币和国家/地区的集成情况。

沙盒环境

所有测试活动请使用我们专用的沙箱 API endpoint

测试数据

获取涵盖所有场景的全面测试卡和账户

实时仿真

接收所有测试交易的即时 webhook 通知

API 参考

浏览我们完整的 API 文档及示例

开始之前

开始之前,请确保您已准备好:

API凭证

用于身份验证的有效 API 凭据和访问令牌。

账户设置

为您的目标国家/地区正确设置账户并进行业务验证。

IP白名单

将服务器 IP 地址加入 API 访问白名单。

Webhook endpoint

设置 webhook URL 以接收付款通知。

步骤 1:生成访问令牌

要与 Localpayment 的 API 进行交互,您需要一个用于身份验证的访问令牌。所有 API 请求都需要此令牌。 要生成访问令牌,您需要向生成访问令牌endpoint 发送 POST 请求,并在请求正文中以 JSON 对象的形式包含您的 Localpayment username 和 password。

示例请求

curl

成功响应

重要的在所有后续 API 请求中使用响应中的 access 令牌。将其作为 Bearer <your_access_token> 放入 Authorization 标头中。出于安全原因,令牌会过期 - 请使用刷新令牌获取新的访问令牌,而无需重新验证。

步骤 2:检索可用的付款方式

创建付款前,请检查您的账户和目标国家/地区有哪些付款方式可用。 要获取可用的付款方式,请向获取可用的付款方式endpoint 发送 GET 请求,并将您的 accountNumber 作为查询参数包含在内。

示例请求

curl

成功响应

对于银行卡支付,请查找 paymentMethodType 为 CreditCard 或 DebitCard 的支付方式。请记下 code 值(例如,阿根廷 Visa 卡对应的 1000),因为您在付款请求中需要用到它。

步骤 3:创建付款请求

现在您可以创建您的第一笔测试付款了。我们将以阿根廷的信用卡付款为例。 要创建信用卡付款,请向创建付款endpoint 发送 POST 请求,并在 Authorization 标头中包含您的 access 令牌。

关键请求字段

该请求需要几个关键参数:

示例请求

以下是使用 curl 的示例:
curl

成功响应

成功的响应应包含详细的交易信息和跟踪标识符:

关键响应字段


第四步:处理 Webhook 通知

Webhook 可提供交易状态变更的实时通知。请在 Localpayment Business Portal 中配置您的 Webhook URL 以接收这些通知。

Webhook 载荷示例

实施提示:您的 webhook endpoint 在收到 webhook 后应立即返回 200 OK 状态,然后异步处理通知以避免超时。

步骤五:跟踪交易状态

您可以使用获取交易状态endpoint 主动检查交易状态。发送 GET 请求,将 {externalId} 替换为您的唯一交易标识符,即可获取交易状态。

示例请求

curl

成功响应

常用状态码

重要的请务必检查 status.code 字段以确定交易结果。有关所有可能的交易状态的完整列表,请参阅完整的状态参考。

测试不同的支付方式

Localpayment 除了信用卡之外,还支持多种支付方式。每种方式都有其特定的请求参数和响应结构。以下是银行转账的示例,并重点突出了关键区别。
银行转账支付允许客户通过本地支付系统直接从其银行账户付款。

示例请求

成功响应

银行转账的主要请求差异

银行转账的关键响应差异


后续步骤

探索收款选项

了解所有可用的支付方式,包括银行卡和 APM。

探索付款选项

了解如何向银行账户和电子钱包汇款。

探索国家/地区覆盖范围

查看各个国家/地区可用的付款方式、货币和具体要求。

API 参考

查看包含 endpoint、参数和代码示例的完整 API 文档。
最后修改于 2026年11月10日