退款集成

本文说明退款集成流程。

1. 集成准备

接口注册开发者中心账号；
上传测试商户公钥，获取平台公钥、AppID、测试商户号等集成信息；
配置回调地址（WebHook），包括支付结果回调地址、退款结果回调地址等；
设置测试环境服务器IP白名单；
配置并开通相应支付方式；
查看不同环境的请求地址；
理解请求报文加签和验签的原理，用于生成每次HTTP请求Header的sign签名字符串。

2. 交互流程

3. 接口列表

关联交互时序	调用方向	接口PATH
2.2 & 2.3 发起退款	`商户` -> `PayerMax`	/refund
3.1 退款结果通知	`PayerMax` -> `商户`	/refundResultNotifyUrl
4.1 查询退款交易	`商户` -> `PayerMax`	/refundQuery

4. 集成步骤

4.1 发起退款

在用户支付成功后，商户可以通过退款申请 API 接口或通过PayerMax 商户平台（MMC）两种方式发起退款。

订单需要如下满足条件，才能成功发起退款：

已支付成功；
不在退款过程中；
未成功退款；
订单支付成功后的365天内；
商户账户余额足以支付退款。PayerMax会从您的待结算账户（待结算额）中扣除退款金额，若待结算账户（待结算额）中金额不足，则会返回REFUND_INSUFFICIENT_BALANCE，收到此错误码后，请等有支付成功的交易后，再次发起；
如果通过商户平台发起退款，请确认发起者是否具有申请退款的权限。

若未满足退款条件仍希望发起退款，建议使用PayerMax付款服务进行退款。

退款申请成功后，退款金额会按原交易方式退还至用户账户中。比如：用户通过Paytm Wallet付款，退款成功后，金额会返回至用户的Paytm Wallet账户中。

注意：

退款金额通常将于21日内返回用户银行账户。但受渠道限制，不同银行的实际到账时间可能存在差异。

4.1.1 通过商户平台退款

在商户激活PayerMax 商户平台（MMC）后，可登录PayerMax 商户平台（MMC），进入 收款管理 → 订单查询，搜索需要进行退款的交易订单，进入该笔订单的详情页，点击 发起退款 按钮。

商户可根据需要，设置退款申请审批。若未设置退款审批功能，默认发起退款申请后，无需审批，直接执行退款处理。如果需要开通退款审批功能，请参考【如何开通退款审批功能】。

审批驳回或退款失败的订单，只要处于退款有效期内，都可以再次发起退款申请。

4.1.2 通过退款API退款

退款申请/refund API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/refund \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:20:54.047+00:00",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "data": {
    "outRefundNo": "R1642411016202", # 商户退款单号
    "refundAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681", # 要退款的商户订单号
    "tradeToken": "T2025020713159038685354",
    "comments": "20220117070423TI408900055079",
    "refundNotifyUrl": "https://www.payermax.com" # 退款结果回调通知接口
  }
}'

退款申请/refund API 接口响应示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "tradeOrderNo": "20220117091121TI366100056090",
    "refundTradeNo": "20220117091657TI790000055087",
    "status": "REFUND_PENDING"
  }
}

4.2 获取退款结果

PayerMax受理成功后，会向银行或机构发起原路退款请求，并会通过【回调通知】同步商户退款状态。退款的状态如下：

退款状态	描述	备注
`REFUND_SUCCESS`	退款成功	退款成功仅表示渠道方已成功受理该笔退款申请，具体到账时间受渠道限制而有所不同。当您成功发起退款申请后，退款金额预计将于21日内返回用户银行账户。受渠道约束，退款状态仅供查询受理是否成功，暂不支持查询退款资金处理的实际状态。但各渠道一般遵循下述规律处理退款： 1.退款请求受理成功后，于1-21天内资金将原路退还至用户支付所用银行卡或账户。 2.若产生客诉，商户可按上述口径应答用户，如用户侧退款未在有效时间内处理，可接洽PayerMax给予售后支持。
`REFUND_PENDING`	退款处理中
`REFUND_FAILED`	退款失败

4.1.1 通过退款结果通知

退款成功后，PayerMax会主动回调商户指定的回调地址，发起退款通知 API。PayerMax可能会多次回调通知商户，直到接收到商户的成功响应。

商户可以通过两种方式设置退款结果回调地址：

通过接口参数指定：退款申请时，设置退款申请/refund API 请求入参refundNotifyUrl。该配置仅对单笔支付生效，可覆盖全局配置。
通过商户平台配置：通过PayerMax商户平台，配置统一的退款结果回调地址，具体配置方式参看【链接】。该配置对所有退款申请生效。

退款结果通知/refundResultNotifyUrl API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/RefundResultNotifyUrl \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
  "code": "APPLY_SUCCESS",
  "msg": "Success.",
  "keyVersion": "1",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "notifyTime": "2022-01-17T09:33:54.540+00:00",
  "notifyType": "REFUND",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundTradeNo": "20220117091657TI790000055087",
    "outTradeNo": "P1642410680681",
    "refundAmount": 10000,
    "refundCurrency": "IDR",
    "refundFinishTime": "2023-10-20T03:28:23.092Z",
    "status": "REFUND_SUCCESS"
  }
}'

商户可以通过data.status判定退款状态，请勿使用code或msg判定退款状态。

退款结果通知/refundResultNotifyUrl API 接口响应示例：

json

{
  "code": "SUCCESS",
  "msg": "Success"
}

商户接收到退款结果通知后，可返回成功或失败。如果商户未响应或响应失败，则PayerMax会尝试重发退款结果通知，通知频率为0s/30s/300s/600s/3600s/43200s，最多重试6次。

在退款状态不明或者没有收到PayerMax退款结果通知的情况下，商户主动通过退款交易查询，获取退款结果。

特别提醒：

通过商户平台发起的退款，PayerMax默认不会对商户发起退款结果回调通知，如需要开通，请联系PayerMax技术支持团队。

4.1.2 通过退款交易查询

商户还可以通过调用交易查询/orderQuery API 接口，获取支付结果。

交易查询/orderQuery API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/refundQuery \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2022-01-17T07:01:23.737+00:00",
  "appId": "a0dddd1f622243cb9aa1b676e808b5f8",
  "merchantNo": "02021382719993",
  "data": {
    "outRefundNo": "R1642411016202"
  }
}'

交易查询/orderQuery API 接口响应示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundTradeNo": "20220117091657TI790000055087",
    "totalAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681",
    "status": "REFUND_SUCCESS",
    "refundFinishTime": "2023-10-20T03:28:23.092Z",
    "resultMsg": "Success"
  }
}

商户可以通过code判定本次退款查询成功与否，通过data.status进一步判定退款状态，请勿使用code或msg或data.resultMsg判定退款状态。

4.1.3 通过商户平台

无论通过何种方式发起退款，商户均可以登录PayerMax商户平台（MMC），通过 收款管理 → 退款查询，查询退款结果和进程。

5. 测试上线

在商户完成上述集成步骤后，可以发起实际支付请求进行初步测试验证，具体步骤参看【集成测试-发起测试】。

在测试通过后，最终发布上线前，须联系PayerMax技术支持，提交测试的订单信息，以便于PayerMax检查请求日志和数据，确认您已经正确集成相关能力，具体步骤参看【集成测试-发起验收】。

验收通过后，商户可以【配置生产环境的集成信息】，并准备开量事宜。

另外，在【支付方式】下有PayerMax支持的各类支付方式的集成文档，其中包含每种支付方式的测试上线说明。

6. 错误排查

测试或验收过程中的响应错误，可以参看【错误排查-错误码】。同时，在【错误排查-常见问题】中，总结列举各类常见的问题及其处理方式。

您还可以直接联系PayerMax技术支持团队，咨询集成、测试、验收过程中的任何问题。

集成

收银台支付

支付方式列表

纯API支付

前置组件

卡支付

ApplePay

GooglePay

订阅代扣

Tokenization支付

链接支付

相关能力（退款/争议等）

交易结果

争议

业务风险管控

集成

API付款

支付方式列表

欧洲

相关能力（交易查询/通知）

交易对账

全球收单

退款集成

1. 集成准备

2. 交互流程

3. 接口列表

4. 集成步骤

4.1 发起退款

4.1.1 通过商户平台退款

4.1.2 通过退款API退款

4.2 获取退款结果

4.1.1 通过退款结果通知

4.1.2 通过退款交易查询

4.1.3 通过商户平台

5. 测试上线

6. 错误排查

收银台支付

支付方式列表

纯API支付

前置组件

卡支付

ApplePay

GooglePay

订阅代扣

Tokenization支付

链接支付

交易结果

争议

业务风险管控

API付款

支付方式列表

欧洲

退款集成 ​

1. 集成准备 ​

2. 交互流程 ​

3. 接口列表 ​

4. 集成步骤 ​

4.1 发起退款 ​

4.1.1 通过商户平台退款 ​

4.1.2 通过退款API退款 ​

4.2 获取退款结果 ​

4.1.1 通过退款结果通知 ​

4.1.2 通过退款交易查询 ​

4.1.3 通过商户平台 ​

5. 测试上线 ​

6. 错误排查 ​

退款集成

1. 集成准备

2. 交互流程

3. 接口列表

4. 集成步骤

4.1 发起退款

4.1.1 通过商户平台退款

4.1.2 通过退款API退款

4.2 获取退款结果

4.1.1 通过退款结果通知

4.1.2 通过退款交易查询

4.1.3 通过商户平台

5. 测试上线

6. 错误排查