开始之前
请确保您已备好: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 提供多种状态码,用于指示订阅的状态。完整参考请查看我们的交易状态文档,了解所有状态代码。
测试您的集成
测试场景
请确认您的集成方案能够处理以下场景:- 订阅创建成功:使用有效银行卡的标准订阅流程。
- 固定计划订阅:使用预定义计划的订阅。
- 自定义订阅:使用自定义计费参数的订阅。
- 验证错误:无效的银行卡、缺少必填字段
- 状态更新:Webhook 处理和状态轮询
后续步骤
订阅创建后,您可能需要执行其他操作,例如:更新订阅
修改现有订阅详情,包括计费金额、频率或
客户信息。
取消订阅
终止有效订阅,同时保留交易历史和
账单记录。
处理订阅 webhook
设置 webhook 以接收订阅事件
和付款状态变更的实时通知。

