---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/api/services/marketplaces/mpRefund/index.md
description: >-
  The Request Refund API allows merchants to initiate refund requests. Suitable
  for scenarios requiring processing of consumer refund requests, supporting
  multiple global markets. Key features include specifying order ID, refund
  amount, and reason. Key parameters include order_id (order identifier),
  refund_amount (refund amount), and reason (refund reason).
---
# Request Refund

```apidef
endpoint: POST /v4/payment/refund
name: Request Refund
```

The Request Refund API allows merchants to initiate refund requests. Suitable for scenarios requiring processing of consumer refund requests, supporting multiple global markets. Key features include specifying order ID, refund amount, and reason. Key parameters include order_id (order identifier), refund_amount (refund amount), and reason (refund reason).

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| accId | string | M | Unique identifier for the store, which will appear in the response message after creation; inputting it means modifying the data |
| clientId | string | M | PingPong Merchant ID |
| signType | string | M | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | M | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| version | string | M | Version number, currently fixed at 1.0, may be adjusted with changes to the interface in the future |
| bizContent | string | M | Collection of request parameters, with no limit on maximum length. Except for common request parameters, all other request parameters must be passed within this parameter, format: JSON string |
| └─ merchantTransactionId | string | M | Merchant website order number |
| └─ merchantRefundId | string | M | The merchant's refund transaction serial number, globally unique. |
| └─ amount | string | M | Refund transaction amount, in the smallest unit. For currency details, see the attached Transaction Currencies: /en/notes/appendix/transactionCurrency/ table. |
| └─ currency | string | M | Transaction currency, ISO 4217 three-letter code. For supported currencies, refer to the Transaction Currencies: /en/notes/appendix/transactionCurrency/ table. |
| └─ accountNumber | string | C | Refund account number, required for specific payment methods. For more details, see the Special Payment Method Refund Instructions: /notes/zh/guide/bestPractices/specialRefund/. |
| └─ channelCode | string | C | Bank code, required for refunds using special payment methods. For more information, see the Special Payment Method Refund Instructions: /notes/zh/guide/bestPractices/specialRefund/. |
| └─ phone | string | C | Phone number, required for refunds using special payment methods. For further details, see the Special Payment Method Refund Instructions: /notes/zh/guide/bestPractices/specialRefund/. |
| └─ identificationId | string | C | ID number, required for refunds using special payment methods. For additional information, see the Special Payment Method Refund Instructions: /notes/zh/guide/bestPractices/specialRefund/. |
| └─ email | string | C | Email, required for refunds using special payment methods. For more details, see the Special Payment Method Refund Instructions: /notes/zh/guide/bestPractices/specialRefund/. |
| └─ customer | object | C | User information, required for refunds using special payment methods. For more details, see the Special Payment Method Refund Instructions: /notes/zh/guide/bestPractices/specialRefund/. |
| └─ └─ name | string | C | Name under the user's bank account |
| └─ notificationUrl | string | O | A custom address set by the merchant for notifying the transaction result. Once this parameter is filled, PingPongCheckout will asynchronously push the transaction result to this address via POST.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications. |
| └─ remark | string | C | Merchant extended field |
| └─ subOrderList | array | O | Sub-order information list |
| └─ └─ subMerchantId | string | M | Sub-merchant number on the merchant platform |
| └─ └─ subMerchantTransactionId | string | M | Sub-merchant order number, a unique identifier for the sub-order |
| └─ └─ amount | string | M | Sub-order amount |
| └─ └─ currency | string | M | Currency of the sub-order amount, must be consistent with the original transaction currency |

### Request Example

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

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| accId | string | Unique store identifier, which will appear in the response message after being added; inputting it means modifying the data |
| clientId | string | PingPong merchant number |
| signType | string | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| code | string | Result status code, see the appendix Status Code Table: /en/notes/appendix/successCodeList/ |
| description | string | Result description |
| bizContent | string | Business response parameters |
| └─ transactionId | string | PingPong original transaction serial number |
| └─ merchantTransactionId | string | Merchant website's original transaction serial number |
| └─ merchantRefundId | string | Merchant website's refund transaction serial number |
| └─ refundId | string | PingPong refund transaction serial number |
| └─ currency | string | Transaction currency |
| └─ amount | string | Transaction amount |
| └─ refundTime | string | Refund initiation time, timestamp |
| └─ refundEndingTime | string | Refund final state arrival time, timestamp |
| └─ status | string | SUCCESS - Success; FAILED - Failure; PROCESSING - In progress; |
| └─ remark | string | Merchant extended field |

### Response Example

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