# 退款集成

::: tip  
PayerMax支持[商户平台退款](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities-integration/refund-integration.md#_2-商户平台退款)和[API退款](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities-integration/refund-integration.md#_3-通过api退款)两种方式进行下载。
:::

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

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

- 支付方式支持退款

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

## 2. 商户平台退款

1. 登录 [商户平台](https://mmc.payermax.com/#/login) 
2. 进入 **收单产品** → **订单查询**
3. 找到目标订单，进入详情页，点击 **退款** 按钮，并按流程完成后续操作

<video class="integration-image" controls preload="auto" style="max-width:100%;border-radius:6px;">
  <source src="https://img-cdn-sg.payermax.com/public/20260518-79852e5f-fda8-498f-ba18-fee306d55b87.mp4" type="video/mp4">
</video>

## 3. 通过API退款

### 3.1 交互流程

```mermaid
%%{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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refund/post)           |
| 3.1 退款结果通知   | `PayerMax` -> `商户` | [/refundResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/RefundResultNotifyUrl/post)       |
| 4.1 查询退款交易   | `商户` -> `PayerMax` | [/refundQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refundQuery/post) |

### 3.3 发起退款

 [退款申请/refund API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refund/post) 接口请求示例：

``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refund/post) 接口响应示例：

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

### 3.4 获取退款结果

PayerMax受理退款成功，会向渠道发起原路退款请求，并会通过[退款通知](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/RefundResultNotifyUrl/post)同步商户退款状态，商户也可主动查询获取退款状态。退款的状态如下：

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

#### 3.4.1 退款通知

退款到达终态后，PayerMax会主动通知商户指定的回调地址，发起[退款通知](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/RefundResultNotifyUrl/post)。PayerMax可能会多次回调通知商户，直到接收到商户的成功响应。

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

1. 通过接口参数指定：退款申请时，设置[退款申请/refund API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refund/post) 请求入参`refundNotifyUrl`。该配置仅对单笔支付生效，可覆盖商户平台配置。

2. 通过商户平台配置：通过PayerMax商户平台，配置统一的退款结果回调地址，具体配置方式参看[集成指引-配置测试环境的集成信息](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-2-配置测试环境的回调地址)。该配置对所有退款申请生效。

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

[退款结果通知/refundResultNotifyUrl API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/RefundResultNotifyUrl/post) 接口请求示例：

``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/RefundResultNotifyUrl/post) 接口响应示例：

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

#### 3.4.2 退款查询

[退款查询/refundQuery API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refundQuery/post) 接口请求示例：

``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-refundQuery/post) 接口响应示例：

``` 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. 商户平台发起的退款是否会回调通知

默认商户平台发起的退款不会触发回调通知，如需开通，可 [创建工单](https://docs.payermax.com/202606-version/appendix/faq/ticket.md) 联系PayerMax工作人员进行配置  

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

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

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

通过商户平台发起的退款交易，支持设置退款审批，请参考该文档 [如何开通付款_退款审批流程](https://docs-server-sg.payermax.com/Public/Uploads/2022-12-29/%E5%A6%82%E4%BD%95%E5%BC%80%E9%80%9A%E4%BB%98%E6%AC%BE_%E9%80%80%E6%AC%BE%E5%AE%A1%E6%89%B9%E6%B5%81%E7%A8%8B.pdf)  

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

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

#### 5. 退款到账时效

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

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

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

1. 退款请求受理成功后，于21天内资金将原路退还用户

2. 若产生客诉，商户可按上述口径应答用户。如用户侧退款未在有效时间内收到，可 [创建工单](https://docs-v2.payermax.com/202606-version/appendix/faq/ticket.html) 接洽PayerMax工作人员予以支持