退款集成

PayerMax支持商户平台退款和API退款两种方式进行下载。

1. 退款前提（通用条件）

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

支付方式支持退款
订单状态为支付成功
订单不在退款中状态
退款金额低于订单可退金额
申请时间在支付成功后 180天 内
待结算余额充足(PayerMax会在待结算中扣除退款金额，若不足会返回REFUND_INSUFFICIENT_BALANCE)
（商户平台退款）操作员已开通退款权限

2. 商户平台退款

登录商户平台
进入 收单产品 → 订单查询
找到目标订单，进入详情页，点击退款按钮，并按流程完成后续操作

3. 通过API退款

3.1 交互流程

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as 用户
    participant Client as 商户端
    participant PayerMax as PayerMax
    participant Channel as 支付渠道
钱包/银行等

    %% 1. 申请退款
    User->>Client: 1.1 申请退款

    %% 2. 发起退款逻辑框
    rect rgb(235, 245, 255)
        Note over Client, PayerMax: 发起退款
        
        Note over Client, PayerMax: 通过PayerMax商户平台
        Client->>PayerMax: 2.1 登录PayerMax商户平台
        Client->>PayerMax: 2.2 选定订单，发起退款

        Note over Client, PayerMax: 通过退款API
        Client->>PayerMax: 2.3 调用退款申请接口，发起退款
    end

    %% 3. 渠道处理
    PayerMax->>Channel: 2.4 退款请求
    Channel-->>PayerMax: 2.5 退款请求响应

    %% 4. 退款结果逻辑框
    rect rgb(235, 245, 255)
        Note over Client, PayerMax: 获取退款结果
        
        Note over Client, PayerMax: 通过退款结果通知
        PayerMax->>Client: 3.1 退款结果通知
        Client->>PayerMax: 3.2 退款通知响应

        Note over Client, PayerMax: 通过退款交易查询
        Client->>PayerMax: 4.1 调用退款交易查询
        PayerMax-->>Client: 4.2 返回退款详情
    end

3.2 接口列表

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

3.3 发起退款

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

json

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"
  }
}

3.4 获取退款结果

PayerMax受理退款成功，会向渠道发起原路退款请求，并会通过退款通知同步商户退款状态，商户也可主动查询获取退款状态。退款的状态如下：

退款状态	描述
`REFUND_SUCCESS`	退款成功
`REFUND_PENDING`	退款处理中
`REFUND_FAILED`	退款失败

3.4.1 退款通知

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

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

通过接口参数指定：退款申请时，设置退款申请/refund API 请求入参refundNotifyUrl。该配置仅对单笔支付生效，可覆盖商户平台配置。
通过商户平台配置：通过PayerMax商户平台，配置统一的退款结果回调地址，具体配置方式参看集成指引-配置测试环境的集成信息。该配置对所有退款申请生效。

请注意通过data.status判定退款状态，勿使用code或msg判定退款状态

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

json

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"
}

3.4.2 退款查询

退款查询/refundQuery API 接口请求示例：

json

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"
  }
}

退款查询/refundQuery API 接口响应示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outRefundNo": "R1642411016202",
    "refundTradeNo": "20220117091657TI790000055087",
    "totalAmount": 10000,
    "refundCurrency": "IDR",
    "outTradeNo": "P1642410680681",
    "status": "REFUND_SUCCESS", //请注意通过data.status判定退款状态，勿使用code或msg判定退款状态
    "refundFinishTime": "2023-10-20T03:28:23.092Z",
    "resultMsg": "Success"
  }
}

4. FAQ

1. 商户平台发起的退款是否会回调通知

默认商户平台发起的退款不会触发回调通知，如需开通，可创建工单联系PayerMax工作人员进行配置

2. API发起的退款，商户平台是否会记录

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

3. 商户平台退款是否支持退款审批

通过商户平台发起的退款交易，支持设置退款审批，请参考该文档如何开通付款_退款审批流程

4. 退款成功是否代表用户已收到退款

退款成功仅表示渠道方成功受理该笔退款申请，具体到账时间受渠道限制而有所不同

5. 退款到账时效

当您成功发起退款申请后，退款金额预计将于21日内原路退还用户

6. 退款成功后如何获取真实资金动向

受渠道约束，退款状态仅供查询受理是否成功，暂不支持查询退款资金处理的实际状态。但各渠道一般遵循下述规律处理退款：

退款请求受理成功后，于21天内资金将原路退还用户
若产生客诉，商户可按上述口径应答用户。如用户侧退款未在有效时间内收到，可创建工单接洽PayerMax工作人员予以支持

集成模式详细介绍

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

PayerMax管理订阅计划

商户管理订阅计划

非周期性代扣

前置组件

Tokenization

Auth-Capture

争议

业务风险管控

错误排查

支付方式分类介绍

国家支付方式详情

亚太

中亚

中东及非洲

欧洲

北美拉美

全球

退款集成 ​

1. 退款前提（通用条件） ​

2. 商户平台退款 ​

3. 通过API退款 ​

3.1 交互流程 ​

3.2 接口列表 ​

3.3 发起退款 ​

3.4 获取退款结果 ​

3.4.1 退款通知 ​

3.4.2 退款查询 ​

4. FAQ ​

1. 商户平台发起的退款是否会回调通知 ​

2. API发起的退款，商户平台是否会记录 ​

3. 商户平台退款是否支持退款审批 ​

4. 退款成功是否代表用户已收到退款 ​

5. 退款到账时效 ​

6. 退款成功后如何获取真实资金动向 ​

退款集成

1. 退款前提（通用条件）

2. 商户平台退款

3. 通过API退款

3.1 交互流程

3.2 接口列表

3.3 发起退款

3.4 获取退款结果

3.4.1 退款通知

3.4.2 退款查询

4. FAQ

1. 商户平台发起的退款是否会回调通知

2. API发起的退款，商户平台是否会记录

3. 商户平台退款是否支持退款审批

4. 退款成功是否代表用户已收到退款

5. 退款到账时效

6. 退款成功后如何获取真实资金动向