Query Refund Status
Request Method and Path
POST /payin/v1/getRefundStatus
Request Headers
| Field Name | Type | Required | Description |
|---|---|---|---|
| content-type | string | Yes | application/json |
| x-api-key | string | Yes | Provided by Paydify, same as appId |
| x-api-timestamp | string | Yes | Timestamp in milliseconds |
| x-api-signature | string | Yes | Signature, see Signature Algorithm |
Request Body
| Field Name | Type | Required | Description |
|---|---|---|---|
| mchTxnId | string | No | Merchant refund order ID, at least one of mchTxnId, refundTxnId, or paymentTxnId must be provided |
| refundTxnId | string | No | Paydify refund order ID, at least one of mchTxnId, refundTxnId, or paymentTxnId must be provided |
| paymentTxnId | string | No | Associated Paydify payment order ID, at least one of mchTxnId, refundTxnId, or paymentTxnId must be provided |
Response Headers
| Field Name | Type | Required | Description |
|---|---|---|---|
| x-api-key | string | Yes | Provided by Paydify, same as appId |
| x-api-timestamp | string | Yes | Timestamp in milliseconds |
| x-api-signature | string | Yes | Signature, see Signature Algorithm |
Response
| Field Name | Type | Description |
|---|---|---|
| code | string | Response code, SYS_SUCCESS indicates success |
| message | string | Response message |
| messageDetail | string | Detailed response message |
| success | boolean | Whether the request was successful |
| data[i].refundTxnId | string | Paydify refund order ID |
| data[i].mchTxnId | string | Merchant order ID |
| data[i].paymentTxnId | string | Associated Paydify payment order ID |
| data[i].txnHash | string | Blockchain transaction hash |
| data[i].txnAmount | string | Refund order amount, if currency is USDT, then 1.23 means 1.23 USDT |
| data[i].currency | string | Refund currency |
| data[i].payMethod2 | string | Payment blockchain, enum values see Supported Blockchains and Currencies |
| data[i].appId | string | Provided by Paydify |
| data[i].state | string | Refund status, enum values see Refund Status |
| data[i].mchExtInfo | string | Merchant extension information, JSON string |
| data[i].errorMsg | string | Refund failure reason description |
| data[i].envType | string | appId tag, indicates whether it belongs to production or testing |
| data[i].checkoutMode | int | Checkout mode, possible values: MERCHANT (merchant-specified payment amount), CUSTOMER (customer input payment amount) |
| data[i].refundedTime | int | Refund success timestamp in milliseconds, only has value when refund is successful |
| data[i].createdTime | int | Payment initiation timestamp in milliseconds |
| data[i].updatedTime | int | Last update timestamp in milliseconds |
Request Example
shell
# Request
# Successful response
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": [{
"refundTxnId": "R2209141130105863014",
"txnHash": "0x123456789",
"paymentTxnId": "P220914xxx",
"txnAmount": "1.00",
"currency": "USDC",
"payMethod1": "bitkeep",
"payMethod2": "bnb",
"mchTxnId": "MCH_REFUND_123456",
"appId": "A1111",
"envType": "live",
"mchExtInfo": "{\"orderId\":\"123\"}",
"errorMsg": "",
"state": "pending",
"refundedTime": 1756725871000,
"createdTime": 1756697092000,
"updatedTime": 1756814549000
}],
"success": true
}
# Failed response
{
"code": "SYS_ERROR",
"message": "System error",
"messageDetail": "Error details",
"data": null,
"success": false
}# Request
# Successful response
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": [{
"refundTxnId": "R2209141130105863014",
"txnHash": "0x123456789",
"paymentTxnId": "P220914xxx",
"txnAmount": "1.00",
"currency": "USDC",
"payMethod1": "bitkeep",
"payMethod2": "bnb",
"mchTxnId": "MCH_REFUND_123456",
"appId": "A1111",
"envType": "live",
"mchExtInfo": "{\"orderId\":\"123\"}",
"errorMsg": "",
"state": "pending",
"refundedTime": 1756725871000,
"createdTime": 1756697092000,
"updatedTime": 1756814549000
}],
"success": true
}
# Failed response
{
"code": "SYS_ERROR",
"message": "System error",
"messageDetail": "Error details",
"data": null,
"success": false
}