---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/api/services/InPersonPayments/refund/index.md
description: >-
  申请退款API用于处理PingPongCheckout中已支付订单的退款请求。适用于需要为客户提供退款服务的场景，支持全球主要市场的多种货币。通过此接口，开发者可以指定退款金额、原因等关键参数，实现快速且安全的资金回退。
---
# 申请退款

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

申请退款API用于处理PingPongCheckout中已支付订单的退款请求。适用于需要为客户提供退款服务的场景，支持全球主要市场的多种货币。通过此接口，开发者可以指定退款金额、原因等关键参数，实现快速且安全的资金回退。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| 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。 |
| └─ requestTime | string | M | 商户侧请求时间。时间戳，到毫秒 |
| └─ deviceSn | string | O | 设备序列号，用于指定目标POS机支付。POS退款必传 |
| └─ deviceModel | string | O | 设备型号，用于指定目标POS机支付。POS退款必传 |
| └─ merchantTransactionId | string | M | 原商户的订单流水号，订单唯一标识，可用于后续订单查询和对账 |
| └─ merchantRefundId | string | M | 商户退款的订单流水号，订单唯一标识 |
| └─ amount | string | M | 退款金额，精确位数和币种有关，请查询附录交易币种: /notes/zh/appendix/transactionCurrency/ |
| └─ currency | string | M | 退款币种，ISO 4217 三位币种，具体支持币种⻅附件交易币种: /notes/zh/appendix/transactionCurrency/ |
| └─ cashierDeviceId | string | M | 收银机设备序列号唯一ID |

### 请求示例

```json
{
  "accId": "2018092520455210043243",
  "bizContent": "{\"requestTime\":\"1748597280752\",\"merchantTransactionId\":\"PMT-15ZSIRMPKT1748591387687\",\"merchantRefundId\":\"REF-15ZSIRMPKT1748591800000\",\"deviceSn\":\"NEC300067041\",\"deviceModel\":\"N950S\",\"amount\":\"121.23\",\"currency\":\"MYR\",\"cashierDeviceId\":\"111\"}",
  "clientId": "2018092520455210043",
  "sign": "6D214AE3A1926127C3240D4F7604130362B2007EB3D81C67C43CB7C9D9D97F4A",
  "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。 |
| └─ transactionRefundId | string | PingPong 退款流水号 |
| └─ merchantRefundId | string | 商户网站的的交易流水号 |
| └─ status | string | 交易状态: ACCEPT_SUCCESS-受理成功; FAILED-失败; PROCESSING-进行中; |

### 响应示例

```json
{
  "accId": "2018092520455210043243",
  "bizContent": "{\"merchantRefundId\":\"REF-15ZSIRMPKT1748591800000\",\"transactionRefundId\":\"OS202505300010000211\",\"status\":\"PROCESSING\"}",
  "clientId": "2018092520455210043",
  "code": "002000",
  "description": "Transaction processing"
}
```