开始之前
请确保您已备好:API凭证
用于身份验证的有效 API 凭据和访问令牌。
账户设置
为您的目标国家/地区正确设置账户并进行业务验证。
IP白名单
将服务器 IP 地址加入 API 访问白名单。
Webhook endpoint
设置 webhook URL 以接收付款通知。
第一步:申请预授权
要发起预授权,您需要向 创建 Payin endpoint 发送POST 请求,并将 x-capture 请求头设置为 true。
关键请求参数
该请求需要几个关键对象:paymentMethod.code 取决于国家/地区、卡品牌和产品(信用卡或借记卡)。在秘鲁,它还取决于货币。完整列表请参阅卡支付方式代码。
示例请求
以下是使用curl 的示例:
curl
步骤 2:处理响应
成功响应
成功的响应应包含详细的交易信息和跟踪标识符。关键响应字段
错误响应
请求失败时,您将收到详细的错误信息:步骤 3:扣款
预授权交易后,您必须扣款以从客户账户中扣除相应金额。请确保扣款金额与预授权金额一致。预授权资金冻结期为7天。如果您未在此期限内扣款,资金将自动退回至客户卡。 要对预授权进行扣款,请向 扣款已授权 Payin endpoint 发送PATCH 请求。
示例请求
curl
成功响应
释放未使用的资金
为了确保良好的客户体验,建议您释放任何未使用的预授权资金。通过 API 请求发起释放,可以避免客户等待 7 天的自动释放时间。 要释放未使用的资金,请向 取消 Payin 授权 endpoint 发送PATCH 请求。
示例请求
curl
成功响应
步骤 4:跟踪交易状态
发起预授权付款后,可通过以下方式监控付款进度:Webhooks(推荐)
交易状态变更时接收实时通知。最适用于生产环境。
状态 API endpoint
以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。
Business Portal 视图
用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。
常用状态码
Localpayment API 提供各种状态代码,以在响应中指示付款的进度和结果。APPROVED 不是最终状态。 它表示银行卡付款已确认,但资金尚未计入您的余额。您可以看到该付款,但在状态变为 Completed 之前无法提取资金。这通常需要 1 到 2 天,具体取决于服务商。
有关完整的状态代码参考,请参阅 交易状态 文档。
测试您的集成
测试场景
请确认您的集成方案能够处理以下场景:- 交易成功:标准支付流程
- 验证错误:无效的银行账户,缺少字段
- 处理延迟:需要时间处理的事务
- 交易失败:资金不足、收款人被冻结
- 状态更新:Webhook 处理和状态轮询
后续步骤
预授权处理完毕后,您可能需要执行其他操作,例如:退款
如有必要,您可以将款项退还给客户。详情请参阅退款政策文档。
处理拒付
如果发生争议,您可能需要处理拒付。有关此流程的信息,请参阅拒付文档。
查看交易详情
使用 Localpayment API 获取交易信息。详情请参阅交易信息文档。

