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
merchantId	string	No	Merchant ID of the refund owner (sub-merchant). Required when calling with a partner credential on behalf of a sub-merchant; can be omitted with a merchant-owned credential (defaults to the credential owner). Max 64 characters
merchantAppId	string	No	App ID under the owner merchant, used for disambiguation when the owner merchant has multiple authorized apps. Required if the credential covers multiple apps of the owner merchant; can be omitted when only one app is authorized (resolved automatically). Max 64 characters

When multiple query fields are provided, the server matches them with AND semantics.

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].payMethod1	string	Payment wallet, enum values see Supported Blockchains and Currencies
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. Enum: LIVE / TEST
data[i].refundedTime	string	Refund success timestamp, 13-digit millisecond string. Only has value when refund is successful
data[i].createdTime	string	Refund initiation timestamp, 13-digit millisecond string
data[i].updatedTime	string	Last update timestamp, 13-digit millisecond string

Request Example

# Request

# Successful response
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": [{
    "refundTxnId": "R2209141130105863014",
    "txnHash": "0x123456789",
    "paymentTxnId": "P220914xxx",
    "txnAmount": "1.00",
    "currency": "USDC",
    "payMethod1": "BGW",
    "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
}