跳转到主要内容
预授权是一个两步流程,允许商家在完成交易前验证客户的支付方式。此流程会暂时冻结客户账户中的交易金额,但不会实际扣款。 第一步,系统会发出预授权请求,预留指定金额。这可以确保客户账户余额充足且支付方式有效。但在此阶段,资金不会转给商家。 第二步,执行扣款请求以完成付款。预授权金额随后从客户账户中扣除,并记入商户账户。

开始之前

请确保您已备好:

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 天,具体取决于服务商。
有关完整的状态代码参考,请参阅 交易状态 文档。

测试您的集成

测试场景

请确认您的集成方案能够处理以下场景:
  1. 交易成功:标准支付流程
  2. 验证错误:无效的银行账户,缺少字段
  3. 处理延迟:需要时间处理的事务
  4. 交易失败:资金不足、收款人被冻结
  5. 状态更新:Webhook 处理和状态轮询

后续步骤

预授权处理完毕后,您可能需要执行其他操作,例如:

退款

如有必要,您可以将款项退还给客户。详情请参阅退款政策文档。

处理拒付

如果发生争议,您可能需要处理拒付。有关此流程的信息,请参阅拒付文档。

查看交易详情

使用 Localpayment API 获取交易信息。详情请参阅交易信息文档。

最后修改于 2026年11月20日