开始之前
请确保您已备好: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 自动化处理的退款情况。
- 在需要审批流程的地方进行行政监督。
- 无需开发资源即可快速处理退款。
步骤 3:追踪退款状态
发起退款后,可通过以下方式监控退款进度:Webhooks(推荐)
交易状态变更时接收实时通知。最适用于生产环境。
状态 API endpoint
以编程方式查询事务状态。可用于轮询或恢复丢失的 webhook 通知。
Business Portal 视图
用于监控交易的可视化界面。非常适合人工监督和详细的交易分析。
常用退款状态代码
退款不会立即到达客户账户。 您发起退款后,退款金额可能需要几天时间才会显示在客户的银行卡账单上。具体时间取决于支付服务商和发卡机构。
完整参考请查看我们的交易状态文档,了解所有状态代码。
测试您的集成
测试场景
请确认您的集成方案能够处理以下场景:- 退款成功:使用有效的
externalId并在资金充足的情况下处理退款。 - 资金不足:尝试退款但账户余额不足。
- 无效交易:尝试对不存在的
externalId退款。 - 重复退款:尝试对已退款的交易进行退款。
- 权限验证:使用具有不同权限级别的用户进行测试。
后续步骤
查看交易状态
使用交易状态
API 查看交易和退款的当前状态。
配置 Webhook
设置
Webhook 以接收退款状态变更的实时通知。
审核用户角色
管理退款处理功能的用户权限和角色。

