Query Payment Status

Request Method and Path

POST /payin/v1/getPaymentStatus

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 order ID, either `mchTxnId` or `txnId` must be provided
txnId	string	No	`Paydify` order ID. Supports comma-separated batch lookup (e.g. `P1,P2,P3`), up to 500 characters total. Either `mchTxnId` or `txnId` must be provided. When both are supplied, `txnId` takes precedence
merchantId	string	No	Merchant ID of the order 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

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].txnId	string	`Paydify` order ID
data[i].mchTxnId	string	Merchant order ID
data[i].txnHash	string	Blockchain transaction hash
data[i].txnAmount	string	Order amount, returns fiat amount for fiat orders (e.g., "100" USD), crypto amount for crypto orders (e.g., "100" USDT)
data[i].orderCurrency	string	Order currency
data[i].paidAmount	string	Actual paid amount, if currency is USDT, then 1.23 means 1.23 USDT
data[i].mchReceivedAmount	string	Amount merchant should receive, if currency is USDT, then 1.23 means 1.23 USDT
data[i].settlementCurrency	string	Settlement currency for merchant. USDT/USDC for crypto settlement, USD for fiat settlement
data[i].mchFee	string	Fee charged by `Paydify`, if currency is USDT, then 0.23 means 0.23 USDT
data[i].mchFeeRate	string	Fee rate charged by `Paydify`, 1 means 1%
data[i].currency	string	Payment currency
data[i].gasFee	string	Blockchain gas fee
data[i].gasFeeCurrency	string	Gas fee 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	Payment status, enum values see Payment Status
data[i].refundType	string	Refund identifier, note distinction from refund status
data[i].mchExtInfo	string	Merchant extension information, JSON string
data[i].errorMsg	string	Payment failure reason description
data[i].failType	string	Failure type, only set when `state = FAILED`. Enum: `TIMEOUT` (order timed out) / `PAYFAIL` (channel-side payment failure)
data[i].envType	string	appId tag. Enum: `LIVE` / `TEST`
data[i].fromAddress	string	Payer address
data[i].checkoutMode	string	Checkout mode, possible values: `MERCHANT` (merchant-specified payment amount), `CUSTOMER` (customer input payment amount)
data[i].successReturnUrl	string	Success redirect URL configured at order creation
data[i].failReturnUrl	string	Failure redirect URL configured at order creation
data[i].pendingReturnUrl	string	Pending redirect URL configured at order creation
data[i].paidTime	string	Payment success timestamp, 13-digit millisecond string. Only has value when payment is successful
data[i].failedTime	string	Payment failure timestamp, 13-digit millisecond string. Only has value when payment fails/times out
data[i].expiredTime	string	Expected payment timeout timestamp, 13-digit millisecond string
data[i].createdTime	string	Payment initiation timestamp, 13-digit millisecond string

Request Example

# Request

# Successful response
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": [{
    "txnId": "2209141130105863014",
    "mchTxnId": "220914xxx",
    "state": "PENDING",
    "checkoutMode": "MERCHANT",
    "envType": "LIVE",
    "errorMsg": "",
    "paidTime": "1756725871000",
    "failedTime": "0",
    "expiredTime": "1756729471000",
    "createdTime": "1756697092000"
  }],
  "success": true
}

# Failed response
{
  "code": "SYS_ERROR",
  "message": "System error",
  "messageDetail": "Error details",
  "data": null,
  "success": false
}