开始之前
请确保您已备好: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 退款的具体要求和限制因国家/地区和支付方式而异。以下是各国的主要注意事项:- QR(阿根廷)
- 退款流程:需要提供完整受益人信息的数据必要退款。
- 证件类型:支持的阿根廷证件类型(CUIL、DNI 等)。
- 处理方式:退款通过阿根廷当地银行网络处理。
步骤 1:通过 API 处理退款
要通过 API 退还 APM 付款,请向退款endpoint 发送PATCH 请求。
关键请求参数
该请求需要几个关键参数:示例请求
以下是使用curl 的示例:
curl
步骤 2:处理响应
成功响应
成功处理的退款会返回确认详情:关键响应字段
错误响应
退款申请失败时,您将收到错误信息:常见错误场景
Business Portal 退款
APM 退款也可以通过 Localpayment Business Portal 界面进行处理。这种方法提供了一个可视化的退款管理工作流程,尤其适用于以下情况:- 偶尔发生且不需要 API 自动化处理的退款。
- 需要审批工作流程的行政监督。
- 无需开发资源即可快速处理退款。
步骤 3:追踪退款状态
发起退款后,可通过以下方式监控退款进度:Webhooks(推荐)
交易状态变更时接收实时通知。最适用于生产环境。
状态 API endpoint
以编程方式查询交易状态。可用于轮询或恢复丢失的 Webhook 通知。
Business Portal 视图
用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。
常用退款状态代码
完整参考请查看我们的交易状态文档,了解所有状态代码。
测试您的集成
测试场景
请确认您的集成能够处理以下场景:- 退款成功:使用有效的
externalId和充足的资金处理退款。 - 资金不足:在账户余额不足的情况下尝试退款。
- 无效交易:尝试对不存在的
externalId退款。 - 重复退款:尝试对已退款的交易进行退款。
- 权限验证:使用具有不同权限级别的用户进行测试。
后续步骤
查看交易状态
使用交易状态
API 查看交易和退款的当前状态。
配置 Webhook
设置 Webhook 以接收退款状态
变更的实时通知。
审核用户角色
管理退款处理功能的用户权限和角色。

