---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/api/services/marketplaces/mpRefund/index.md
description: >-
  申请退款API允许商家发起退款请求。适用于需要处理消费者退款请求的场景，支持全球多个市场。主要功能包括指定订单ID、退款金额及原因。关键参数有order_id（订单标识）、refund_amount（退款金额）和reason（退款理由）。
---
# 申请退款

```apidef
endpoint: POST /v4/payment/refund
name: 申请退款
```

申请退款API允许商家发起退款请求。适用于需要处理消费者退款请求的场景，支持全球多个市场。主要功能包括指定订单ID、退款金额及原因。关键参数有order_id（订单标识）、refund_amount（退款金额）和reason（退款理由）。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| accId | string | M | 店铺唯一标识 |
| clientId | string | M | PingPong 商户号 |
| signType | string | M | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | M | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| version | string | M | 版本号，当前固定为1.0，后续随接口变动可能有调整 |
| bizContent | string | M | 请求参数的集合，最大长度不限，除公共请求参数外所有请求参数都必须放在这个参数中传递，格式：JSON字符串。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ merchantTransactionId | string | M | 商户网站订单号 |
| └─ merchantRefundId | string | M | 商户的退款交易流水号，全局唯一。 |
| └─ amount | string | M | 退款交易金额，最小单位查询 附件交易币种: /notes/zh/appendix/transactionCurrency/表 |
| └─ currency | string | M | 交易币种，ISO 4217 三位币种，具体支持币种见 附件交易币种: /notes/zh/appendix/transactionCurrency/表 |
| └─ accountNumber | string | C | 退款账户号，特殊支付方式必传，具体见特殊支付方式退款说明: /notes/zh/guide/bestPractices/specialRefund/ |
| └─ channelCode | string | C | 银行code，特殊支付方式退款必传，具体见特殊支付方式退款说明: /notes/zh/guide/bestPractices/specialRefund/ |
| └─ phone | string | C | 手机号，特殊支付方式退款必传，具体见特殊支付方式退款说明: /notes/zh/guide/bestPractices/specialRefund/ |
| └─ identificationId | string | C | 证件号，特殊支付方式退款必传，具体见特殊支付方式退款说明: /notes/zh/guide/bestPractices/specialRefund/ |
| └─ email | string | C | 邮箱，特殊支付方式退款必传，具体见特殊支付方式退款说明: /notes/zh/guide/bestPractices/specialRefund/ |
| └─ customer | object | C | 用户信息，特殊支付方式退款必传，具体见特殊支付方式退款说明: /notes/zh/guide/bestPractices/specialRefund/ |
| └─ └─ name | string | C | 用户银行账户下的姓名 |
| └─ notificationUrl | string | O | 由商户自定义本次交易结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 Post 方式异步推送交易结果到该地址 |
| └─ remark | string | C | 商户扩展字段 |
| └─ subOrderList | array | O | 子订单信息列表 |
| └─ └─ subMerchantId | string | M | 商户平台的子商户号 |
| └─ └─ subMerchantTransactionId | string | M | 子商户订单号，子订单唯一标识 |
| └─ └─ amount | string | M | 子订单金额 |
| └─ └─ currency | string | M | 子订单金额币种，需与原交易金额币种一致 |

### 请求示例

```json
{
  "accId": "2023042011040310224447",
  "bizContent": "{\"amount\":100,\"currency\":\"USD\",\"merchantTransactionId\":\"PMT-2S7RR3K4LQ1715047351210\",\"notificationUrl\":\"https://test-acquirerpay.pingpongx.com/qa/result.html\",\"merchantRefundId\":\"PMT-4DNTI3AWXR1715049316146\"}",
  "clientId": "2023042011040310224",
  "sign": "7F271F64F5ADDF225D76A8F3EADFD5E4F6E71716635D2F18DD51DB6D8CD50E78",
  "signType": "SHA256",
  "version": "1.0"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| accId | string | 店铺唯一标识 |
| clientId | string | PingPong 商户号 |
| signType | string | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| code | string | 结果状态码，见附录状态码表: /notes/zh/appendix/successCodeList/ |
| description | string | 结果描述 |
| bizContent | string | 业务响应参数。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ transactionId | string | PingPong 原交易流水号 |
| └─ merchantTransactionId | string | 商户网站的原交易流水号 |
| └─ merchantRefundId | string | 商户网站的退款交易流水号 |
| └─ refundId | string | PingPong退款交易流水号 |
| └─ currency | string | 交易币种 |
| └─ amount | string | 交易金额 |
| └─ refundTime | string | 退款发起时间，时间戳 |
| └─ refundEndingTime | string | 退款到达终态时间，时间戳 |
| └─ status | string | SUCCESS-成功; FAILED-失败; PROCESSING-进行中; |
| └─ remark | string | 商户拓展字段 |

### 响应示例

```json
{
  "accId": "2023042011040310224447",
  "bizContent": "{\"amount\":\"100.000000\",\"refundTime\":\"1715049319280\",\"transactionId\":\"2024050750046460\",\"merchantTransactionId\":\"PMT-2S7RR3K4LQ1715047351210\",\"currency\":\"USD\",\"merchantRefundId\":\"PMT-4DNTI3AWXR1715049316146\",\"refundId\":\"2024050750046461\",\"status\":\"SUCCESS\"}",
  "clientId": "2023042011040310224",
  "code": "000000",
  "description": "Transaction succeeded",
  "sign": "9475FF30D4DF1A3FD9696EBFBAC72729A7E6140D4E39490097C7F06BDD69020C",
  "signType": "SHA256"
}
```