🔔 Webhook Notification

Configure Webhook to receive notifications. HaloPay will notify merchant of the final transaction results. You can configure the Webhook URL on the AppManage page

Transactions will start a request to the callback interface set by the merchant when involving the following events:

✅ Payment transaction successful
⏱️ Payment transaction timeout
💡 Insufficient payment
✅ Payout successful
❌ Payout failed

Callback Frequency: 5s、15s、30s、3m、10m、20m、30m、30m、30m、60m、3h、3h、3h、6h、6h. Total: 24h3m50s

The callback content is still encrypted. For more information see the Signature.

Webhook notification

Header

Name	Value	Required	Type	Description
X-Appid	h3j6k9m2n...	Y	string	Merchant's unique credential. Find it on the AppManage page.
X-Timestamp	1700349280	Y	string	Timestamp in seconds (10-digit). The request is valid for two minutes.
X-Sign	e0c6a719ebc366da...	Y	string	hmacSHA256 (body (json string)+timestamp+appKey)
X-EventType	Paid	Y	string	Transaction Status Code

Payment Body

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",  (TO-BE-PAID/PAID/TIME-OUT)
  "time": 1773471015
}

💡

Even if the customer doesn't pay the full amount, we will still send a callback notification with the status field set to TO-BE-PAID, and the amount_collected field will show the number of tokens that have been paid.

If the payment time limit is exceeded, we will send a callback with the status field set to TIME-OUT, and the amount_collected field will again show the number of tokens that have been paid.

PayOut Body

 {
  "appid": "ad4cyr8dpfs9j2u1",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "currency_id": 75,
  "status": "PAID",  (PAID/FAIL)
  "time": 1773473637,
  "token_amount": "1",
  "trade_no": "202603141533083d1eba01c48c2a873c",
  "txid": "aa23e0aebd2e4c5b82786a5e8b1f414222c7c525a438b95e2cc7d67c81187a5d",
  "type": "TRANSFER"
}

QRPayment Body

{
  "appid": "1aiqfs0agrd3b9fm", (By default, it is different from the payment APPID.)
  "trade_no": "2c8b150bf35abc59189e333c107247db",
  "type": "QR_PAYMENT"
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TRX",
  "txid": "2cdf12e85ec73a61280daaf49c4f27686519407fa0dc7b7744596cad29cbd53c",
  "currency_id": 75,
  "from_address": "TSpjU4PUYzAyY88wyKEEMD7MryneC1WLeb",
  "to_address": "TY1RJdyJh4y1tgmPFrnSaWFhM1HwqTvCQ1",
  "token_amount": "11",
  "status": "PAID",  (PAID)
  "time": 1773473913,
}

Parameters

Field	Type	Description
appid	string	Merchant APPID
trade_no	string	Transaction ID
out_trade_no	string	Merchant order ID
amount	string	Transaction amount (fiat currency amount)
token_amount	string	Transaction amount
chain	string	Chain name
chain_id	int	Chain ID
type	string	Transaction type ("PAYMENT/TRANSFER/QR_PAYMENT")
currency_id	int	Global unique currency ID TokenList
txid	string	On-chain transaction hash
status	string	Transaction status (TO-BE-PAID/PAID/TIME-OUT/FAIL), A TO-BE-PAID callback will be triggered when an order is not fully paid.
time	int	Final on-chain time(If it fails, return the timeout period.)
amount_collected	string	The number of tokens the user has paid for
contract	string	The contract address for the token, with the main currency being ETH/TRX/BNB
from_address	string	Payment wallet address
to_address	string	Receiving wallet address

💡

Merchants sign to ensure information safety. Once the merchant has processed the order, please return "Success" in the body of the HTTP response if the processing has been successful. If the process fails, HaloPay will attempt to send the order again and the Webhook will retry up to 15 times (Callback Frequency: 5s、15s、30s、3m、10m、20m、30m、30m、30m、60m、3h、3h、3h、6h、6h, Total: 24h3m50s).

📌 Example

Request to Merchant Webhook Server

POST /webhook/callback HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Appid: ad4cyr8dpfs9j2u1
X-Timestamp: 1773471015
X-Sign: e0c6a719ebc366da...
X-EventType: Paid

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",
  "time": 1773471015
}

Response from Merchant Webhook Server

HTTP/1.1 200 OK
Content-Type: text/plain

Success

Webhook notification​

📌 Example​

Webhook notification

📌 Example