跳转到主要内容
Localpayment 使商户能够通过信用卡和借记卡设置周期性付款订阅,支持跨多个国家/地区的固定计划和自定义计费场景。本指南概述了通过 Localpayment 的 API 创建订阅的流程,详细说明所需参数、响应处理以及状态码的含义。

开始之前

请确保您已备好:

API凭证

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

账户设置

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

IP白名单

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

Webhook endpoint

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

步骤 1:创建订阅

要创建新订阅,您需要向创建订阅endpoint 发送 POST 请求。

关键请求参数

该请求需要若干关键参数,具体取决于您创建的是固定计划订阅还是自定义订阅:

订阅类型

  • 固定计划订阅:适用于已通过创建订阅计划endpoint 创建了预定义订阅计划的情况。
  • 自定义订阅:适用于每次付款金额或时间可能不同的浮动计费场景。

支付方式代码

在每个国家/地区,paymentMethod.code 都用于标识国家/地区、卡品牌和产品(信用卡或借记卡),因此请发送与卡片及订阅的 country 相匹配的代码。在秘鲁,卡片支持两种货币,代码还必须与 currency 相匹配:例如,Visa 信用卡在使用 PEN 时为 6000,使用 USD 时为 6004。所有国家/地区的代码请参阅银行卡支付方式代码。

示例请求

以下是使用 curl 的示例:
curl
查看请求中所有可用的参数。

步骤 2:处理响应

成功响应

成功的响应包含详细的订阅信息和标识符:

关键响应字段

错误响应

请求失败时,您将收到详细的错误信息:

步骤 3:跟踪交易状态

创建订阅后,可通过以下方法监控其生命周期:

Webhooks(推荐)

交易状态变更时接收实时通知。最适用于生产环境。

状态 API endpoint

以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。

Business Portal 视图

用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。

常用状态码

Localpayment API 提供多种状态码,用于指示订阅的状态。
完整参考请查看我们的交易状态文档,了解所有状态代码。

测试您的集成

测试场景

请确认您的集成方案能够处理以下场景:
  1. 订阅创建成功:使用有效银行卡的标准订阅流程。
  2. 固定计划订阅:使用预定义计划的订阅。
  3. 自定义订阅:使用自定义计费参数的订阅。
  4. 验证错误:无效的银行卡、缺少必填字段
  5. 状态更新:Webhook 处理和状态轮询

后续步骤

订阅创建后,您可能需要执行其他操作,例如:

更新订阅

修改现有订阅详情,包括计费金额、频率或 客户信息。

取消订阅

终止有效订阅,同时保留交易历史和 账单记录。

处理订阅 webhook

设置 webhook 以接收订阅事件 和付款状态变更的实时通知。
最后修改于 2026年11月10日