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

