跳转到主要内容
Localpayment 支持您通过 API 集成和 Business Portal 界面处理替代支付方式(APM)的退款。本指南涵盖使用数据必要退款流程处理 APM 交易退款的完整工作流程。

开始之前

请确保您已备好:

API 凭证

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

账户设置

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

IP 白名单

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

Webhook endpoint

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

其他退款要求:

  • 您的 Localpayment 账户余额足以支付退款金额。
  • 具有退款权限的用户角色(请参阅用户角色文档)。
  • 原始交易必须处于 Completed 状态。
  • 原始支付交易的 externalId。
  • 提供完整的受益人信息,以便进行数据必要退款。

实施指南

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

API 退款处理

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

Business Portal 退款处理

通过 Localpayment Business Portal 手动处理退款,该门户拥有用户友好的界面。注意:所有企业门户退款都需要获得批准。

APM 的数据必要退款

APM 退款按数据必要退款处理,这意味着您既需要原始交易的 externalId,也需要完整的受益人信息。与直接退款不同,此流程需要额外的付款人和银行详细信息,因为二维码支付涉及必须经过验证的特定受益人信息。
重要提示:APM 交易仅允许全额退款,不支持部分退款。

各国具体要求

APM 退款的具体要求和限制因国家/地区和支付方式而异。以下是各国的主要注意事项:
  • 退款流程:需要提供完整受益人信息的数据必要退款。
  • 证件类型:支持的阿根廷证件类型(CUIL、DNI 等)。
  • 处理方式:退款通过阿根廷当地银行网络处理。

步骤 1:通过 API 处理退款

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

关键请求参数

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

示例请求

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

步骤 2:处理响应

成功响应

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

关键响应字段

错误响应

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

常见错误场景


Business Portal 退款

APM 退款也可以通过 Localpayment Business 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月10日