跳转到主要内容
Localpayment 使您能够处理银行卡支付的退款,您可以通过 API 集成和 Business Portal 界面将款项退回到客户的信用卡或借记卡。本指南涵盖了银行卡交易的完整退款流程。

开始之前

请确保您已备好:

API凭证

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

账户设置

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

IP白名单

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

Webhook endpoint

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

其他退款要求:

  • 您的Localpayment账户余额足以支付退款金额。
  • 具有退款权限的用户角色(请参阅用户角色文档)。
  • 原始交易必须处于 Completed 状态。
  • 原始支付交易的 externalId。

实施指南

Localpayment 提供两种处理信用卡退款的方法:API 集成用于自动处理,Business Portal 用于手动操作。

API退款处理

通过 REST API 以编程方式处理退款,实现自动化工作流程并与您的系统集成。

Business Portal 退款处理

通过 Localpayment Business Portal 手动处理退款,该门户网站拥有用户友好的界面。

信用卡支付直接退款

对于银行卡交易,退款将作为直接退款处理,即您只需提供原始交易的 externalId。由于资金会退回到支付时使用的原卡,因此无需提供额外的收款人或银行信息。

步骤 1:通过 API 处理退款

要通过 API 退还银行卡付款,请向退款endpoint 发送 PATCH 请求。

关键请求参数

该请求需要几个关键参数:

示例请求

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

步骤 2:处理响应

成功响应

成功处理的退款确认详情:

关键响应字段

错误响应

退款申请失败时,您将收到错误信息:

常见错误场景


Business Portal 退款

信用卡退款也可以通过LocalpaymentBusiness Portal 界面进行处理。这种方法提供了一个可视化的退款管理工作流程,尤其适用于以下情况:
  • 偶尔会出现不需要 API 自动化处理的退款情况。
  • 在需要审批流程的地方进行行政监督。
  • 无需开发资源即可快速处理退款。
有关通过 Business Portal 处理退款的详细说明,包括分步指南和界面演示,请参阅Business Portal 退款指南。
需要审批:所有通过 Localpayment Business Portal 发起的退款都需要经过指定的授权流程才能获得批准。请确保您拥有必要的用户权限后再尝试通过 Business Portal 进行退款。

步骤 3:追踪退款状态

发起退款后,可通过以下方式监控退款进度:

Webhooks(推荐)

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

状态 API endpoint

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

Business Portal 视图

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

常用退款状态代码

退款不会立即到达客户账户。 您发起退款后,退款金额可能需要几天时间才会显示在客户的银行卡账单上。具体时间取决于支付服务商和发卡机构。
完整参考请查看我们的交易状态文档,了解所有状态代码。

测试您的集成

测试场景

请确认您的集成方案能够处理以下场景:
  1. 退款成功:使用有效的 externalId 并在资金充足的情况下处理退款。
  2. 资金不足:尝试退款但账户余额不足。
  3. 无效交易:尝试对不存在的 externalId 退款。
  4. 重复退款:尝试对已退款的交易进行退款。
  5. 权限验证:使用具有不同权限级别的用户进行测试。

后续步骤

查看交易状态

使用交易状态 API 查看交易和退款的当前状态。

配置 Webhook

设置 Webhook 以接收退款状态变更的实时通知。

审核用户角色

管理退款处理功能的用户权限和角色。
最后修改于 2026年11月20日