开始之前
开始之前,请确保您已准备好:API凭证
用于身份验证的有效 API 凭据和访问令牌。
账户设置
为您的目标国家/地区正确设置账户并进行业务验证。
IP白名单
将服务器 IP 地址加入 API 访问白名单。
Webhook endpoint
设置 webhook URL 以接收付款通知。
第一步:申请刷卡付款
要发起一次性卡支付,您需要向 Create Payin endpoint 发送POST 请求。
关键请求参数
该请求需要几个关键对象:paymentMethod.code 取决于国家/地区、卡品牌和产品(信用卡或借记卡)。在秘鲁,它还取决于货币。完整列表请参阅卡支付方式代码。
示例请求
以下是使用curl 的示例:
curl
使用代币化卡支付
如果您之前已对客户的银行卡进行令牌化处理,则可以使用该令牌代替发送完整的银行卡信息来处理一次性付款。这提高了安全性,并简化了支付流程,无需再次请求银行卡信息。 有关卡片令牌化的详细信息,请参阅令牌化文档。使用 3D 安全支付
如果持卡人需要额外身份验证,流程将通过 3D Secure 进行。在这种情况下,Localpayment 会在 API 响应中返回发卡行的验证 URL,商家有责任将客户重定向到该 URL 或在结账流程中显示验证信息。这样,持卡人即可完成所需的验证。具体的 3D Secure 体验可能因发卡行和客户所在国家/地区而异。 有关 3D Secure 支付的详细信息,请参阅 3D Secure 文档。步骤 2:处理响应
成功响应
成功的响应应包含详细的交易信息和跟踪标识符:关键响应字段
错误响应
请求失败时,您将收到详细的错误信息:步骤 3:跟踪交易状态
发起一次性付款后,可通过以下方式监控付款进度:Webhooks(推荐)
交易状态变更时接收实时通知。最适用于生产环境。
状态 API endpoint
以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。
Business Portal 视图
用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。
常用状态码
Localpayment API 提供各种状态代码,以在响应中指示付款的进度和结果。APPROVED 不是最终状态。 它表示银行卡付款已确认,但资金尚未计入您的余额。您可以看到该付款,但在状态变为 Completed 之前无法提取资金。这通常需要 1 到 2 天,具体取决于服务商。
完整参考请查看我们的交易状态文档,了解所有状态代码。
测试您的集成
测试场景
请确认您的集成方案能够处理以下场景:- 交易成功:标准支付流程
- 验证错误:无效的银行账户,缺少字段
- 处理延迟:需要时间处理的事务
- 交易失败:资金不足、收款人被冻结
- 状态更新:Webhook 处理和状态轮询
后续步骤
一次性付款处理完毕后,您可能需要执行其他操作,例如:退款
如有必要,您可以将款项退还给客户。详情请参阅相关文档。
处理拒付
如果发生争议,您可能需要处理拒付事宜。请参阅相关文档了解具体流程。
查看交易详情
您可以使用 Localpayment API 获取交易信息,以获得更详细的分析。

