Webhook Notifications to Merchants
Payment Callback
Notification Method
POST request
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 |
| txnHash | string | Blockchain transaction hash |
| txnAmount | string | Payment order amount, if currency is USDT, then 1.23 means 1.23 USDT |
| 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 |
| state | string | Payment status, enum values see Payment Status |
| 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
Paydify can only recognize the following two plain text response values
successfailIf other values are returned, up to 10 retries will be initiated
Request Example
shell
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": "A14456006",
"txnId": "P4687529510003120897",
"mchTxnId": "DCS20250905175704ICVAa11111211",
"currency": "USDC",
"state": "paid",
"txnHash": "0xf12b4e7aec3a19e8ccff31421b05f3830f23bf5a666e174542d9659a043b1df1",
"fromAddress": "0xa123Afb8d31503eeee49566F9F77E4d4071B7d5f",
"notifyType": "payment",
"paidAmount": "0.22",
"mchReceivedAmount": "0.22",
"mchFee": "0",
"txnAmount": "0.22",
"paidTime": 1757328167000,
"failedTime": 0
}'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": "A14456006",
"txnId": "P4687529510003120897",
"mchTxnId": "DCS20250905175704ICVAa11111211",
"currency": "USDC",
"state": "paid",
"txnHash": "0xf12b4e7aec3a19e8ccff31421b05f3830f23bf5a666e174542d9659a043b1df1",
"fromAddress": "0xa123Afb8d31503eeee49566F9F77E4d4071B7d5f",
"notifyType": "payment",
"paidAmount": "0.22",
"mchReceivedAmount": "0.22",
"mchFee": "0",
"txnAmount": "0.22",
"paidTime": 1757328167000,
"failedTime": 0
}'Refund Callback
Notification Method
POST request
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 refund order ID |
| mchTxnId | string | Merchant refund order ID |
| txnHash | string | Blockchain transaction hash |
| txnAmount | string | Refund amount, if currency is USDT, then 1.23 means 1.23 USDT |
| currency | string | Refund currency |
| state | string | Refund status, enum values: refunded(success), failed(failure) |
| notifyType | string | Notification type, fixed value refund |
| refundedTime | int | Refund success timestamp in milliseconds, only has value when refund is successful |
| failedTime | int | Refund failure timestamp in milliseconds, only has value when refund fails |
Response
Paydify can only recognize the following two plain text response values
successfailIf other values are returned, up to 10 retries will be initiated
Request Example
shell
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": "A14456006",
"txnId": "R4687326023007356672",
"mchTxnId": "DCS20250905175704ICVAa1111",
"currency": "USDC",
"state": "refunded",
"txnHash": "0xb2e811b1e6d40f11275378ce55c03427b79e94ea9f9edadb7a6c2e286ce474ad",
"notifyType": "refund",
"txnAmount": "0.11",
"failedTime": 0,
"refundedTime": 1757315967000
}'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": "A14456006",
"txnId": "R4687326023007356672",
"mchTxnId": "DCS20250905175704ICVAa1111",
"currency": "USDC",
"state": "refunded",
"txnHash": "0xb2e811b1e6d40f11275378ce55c03427b79e94ea9f9edadb7a6c2e286ce474ad",
"notifyType": "refund",
"txnAmount": "0.11",
"failedTime": 0,
"refundedTime": 1757315967000
}'Callback Retry Mechanism
If the callback does not receive the expected response value success, it will retry up to 10 times according to the following strategy.
| Request Number | Time Delay | Description |
|---|---|---|
| 0 | 0 | 1st normal callback, executed immediately, no delay |
| 1 | 15 seconds | 1st retry |
| 2 | 45 seconds | 2nd retry |
| 3 | 90 seconds | 3rd retry |
| 4 | 3 minutes | 4th retry |
| 5 | 10 minutes | 5th retry |
| 6 | 30 minutes | 6th retry |
| 7 | 60 minutes | 7th retry |
| 8 | 3 hours | 8th retry |
| 9 | 6 hours | 9th retry |
| 10 | 12 hours | 10th retry |