Webhook Notifications to Merchants

Payment Callback

Method: POST

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	Description
appId	string	Provided by `Paydify`
txnId	string	`Paydify` payment order ID
mchTxnId	string	Merchant order ID
state	string	Payment status, enum values see Payment Status
txnHash	string	Blockchain transaction hash
txnAmount	string	Order amount. If currency is USDT, then 1.23 means 1.23 USDT
orderCurrency	string	Order currency
paidAmount	string	Actual payment amount, if currency is USDT, then 1.23 means 1.23 USDT
mchReceivedAmount	string	Amount merchant should receive, if currency is USDT, then 1.23 means 1.23 USDT
mchFee	string	Fee charged by `Paydify`, if currency is USDT, then 0.23 means 0.23 USDT
currency	string	Payment currency
settlementCurrency	string	Settlement currency for merchant. USDT/USDC for crypto settlement, USD for fiat settlement
notifyType	string	Notification type, fixed value: `payment`
fromAddress	string	Payer address
paidTime	int	Payment success timestamp in milliseconds, only has value when payment is successful
failedTime	int	Payment failure timestamp in milliseconds, only has value when payment fails/times out

Response

Return HTTP 200 after receiving the callback. Paydify determines success from the response body:

Response Value	Description
`success`	Callback acknowledged, no further retries
`fail`	Callback explicitly failed, will be retried per the retry policy

Recommended:

Set Content-Type to text/plain
Return the bare string success or fail (case-insensitive)

Also accepted as success (no further retries):

Leading/trailing whitespace or trailing newline: success , success\n
JSON string literal: "success"

Still treated as failure and retried:

JSON objects: {"status":"success"} / {"code":0} / {"result":"success"}
HTML error pages or empty body
Any value other than success (including fail)

Any response that cannot be recognized as success triggers retries, up to 7 attempts.

Request Example

curl -X POST '{endpoint}' \
  -H 'content-type: application/json' \
  -H 'x-api-key: xxx' \
  -H 'x-api-timestamp: 121212121' \
  -H 'x-api-signature: xxxx' \
  -d '{
    "appId": "Axxxxxxxx",
    "txnId": "P4687529510003120897",
    "mchTxnId": "DCS20250905175704ICVAa11111211",
    "currency": "USDC",
    "state": "PAID",
    "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "fromAddress": "0x1111111111222222222233333333334444444444",
    "notifyType": "payment",
    "paidAmount": "0.22",
    "mchReceivedAmount": "0.22",
    "mchFee": "0",
    "txnAmount": "0.22",
    "paidTime": 1757328167000,
    "failedTime": 0
}'

Refund Callback