---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/checkout/api/modifications/refund/index.md
description: >-
  The refund request interface is used to handle user refund requests after
  payment. It applies to scenarios requiring refund operations and supports both
  instant and delayed refunds. Main functions include submitting refund
  applications, querying refund status, etc. Key parameters include order
  number, refund amount, and refund reason.
---
# Request Refund

```apidef
endpoint: POST /v4/payment/refund
name: Request Refund
summary: Create a refund request
tags: Checkout, Modification
```

The refund request interface is used to handle user refund requests after payment. It applies to scenarios requiring refund operations and supports both instant and delayed refunds. Main functions include submitting refund applications, querying refund status, etc. Key parameters include order number, refund amount, and 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, which is globally unique. |
| └─ amount | string | M | Refund transaction amount, in the smallest unit. Refer to the attached Transaction Currencies: /en/notes/appendix/transactionCurrency/ table for more details. |
| └─ currency | string | M | Transaction currency, ISO 4217 three-letter code. For specific supported currencies, see the attached Transaction Currencies: /en/notes/appendix/transactionCurrency/ table. |
| └─ accountNumber | string | C | Refund account number, required for special payment methods. See the Special Payment Methods Refund Instructions: /en/notes/guide/bestPractices/specialRefund/ for more details. |
| └─ channelCode | string | C | Bank code, required for refunds via special payment methods. See the Special Payment Methods Refund Instructions: /en/notes/guide/bestPractices/specialRefund/ for more details. |
| └─ phone | string | C | Phone number, required for refunds via special payment methods. See the Special Payment Methods Refund Instructions: /en/notes/guide/bestPractices/specialRefund/ for more details. |
| └─ identificationId | string | C | ID number, required for refunds via special payment methods. See the Special Payment Methods Refund Instructions: /en/notes/guide/bestPractices/specialRefund/ for more details. |
| └─ email | string | C | Email, required for refunds via special payment methods. See the Special Payment Methods Refund Instructions: /en/notes/guide/bestPractices/specialRefund/ for more details. |
| └─ customer | object | C | User information, required for refunds via special payment methods. See the Special Payment Methods Refund Instructions: /en/notes/guide/bestPractices/specialRefund/ for more details. |
| └─ └─ name | string | C | Name under the user's bank account |
| └─ notificationUrl | string | O | A custom notification address defined by the merchant for this transaction result. Once this parameter is filled, PingPongCheckout will asynchronously push the transaction result to this address via Post method. |
| └─ remark | string | C | Merchant extended fields |

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