🔔 Notification Webhook

Configurez le Webhook pour recevoir les notifications. HaloPay informera le marchand des résultats finaux des transactions. Vous pouvez configurer l'URL du Webhook sur la page de gestion des applications.

Les transactions lanceront une requête vers l'interface de callback définie par le marchand lors des événements suivants :

✅ Transaction de paiement réussie
⏱️ Délai de paiement dépassé
💡 Paiement insuffisant
✅ Transaction de versement réussie
❌ Échec du versement

Fréquence des callbacks : 5s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h. Total : 24h3m50s

Le contenu du callback est toujours chiffré. Pour plus d'informations, consultez la Signature.

Notification Webhook

En-têtes

Nom	Valeur	Requis	Type	Description
X-Appid	h3j6k9m2n...	Y	string	Identifiant unique du marchand. Trouvez-le sur la page de gestion des applications.
X-Timestamp	1700349280	Y	string	Horodatage en secondes (10 chiffres). La requête est valide pendant deux minutes.
X-Sign	e0c6a719ebc366da...	Y	string	hmacSHA256 (body (chaîne json)+timestamp+appKey)
X-EventType	Paid	Y	string	Code de statut de transaction

Body du paiement

{
  "appid": "ad4cyr8dpfs...",
  "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": "008f81782daa47709d67bc2073ffff639035cfd...",
  "status": "PAID",  (TO-BE-PAID/PAID/TIME-OUT)
  "time": 1773471015
}

💡

Même si le client ne paie pas le montant complet, nous enverrons toujours une notification de callback avec le champ de statut défini sur TO-BE-PAID, et le champ amount_collected indiquera le nombre de tokens qui ont été payés.

Si le délai de paiement est dépassé, nous enverrons un callback avec le champ de statut défini sur TIME-OUT, et le champ amount_collected indiquera à nouveau le nombre de tokens qui ont été payés.

Body du versement

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

Body du paiement QR

{
  "appid": "1aiqfs0agr...", (Par défaut, il est différent du APPID de paiement.)
  "trade_no": "2c8b150bf35abc59189e333c107247db",
  "type": "QR_PAYMENT",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TRX",
  "txid": "2cdf12e85ec73a61280daaf49c4f27686519407f...",
  "currency_id": 75,
  "from_address": "TSpjU4PUYzAyY88wyKEEMD7MryneC1WL...",
  "to_address": "TY1RJdyJh4y1tgmPFrnSaWFhM1HwqTvC...",
  "token_amount": "11",
  "status": "PAID",  (PAID)
  "time": 1773473913
}

Paramètres

Champ	Type	Description
appid	string	APPID du marchand
trade_no	string	ID de transaction
out_trade_no	string	ID de commande du marchand
amount	string	Montant de la transaction (montant en devise fiduciaire)
token_amount	string	Montant de la transaction en tokens
chain	string	Nom de la chaîne
chain_id	int	ID de la chaîne
type	string	Type de transaction ("PAYMENT/TRANSFER/QR_PAYMENT")
currency_id	int	ID de devise unique global TokenList
txid	string	Hash de transaction sur la chaîne
status	string	Statut de la transaction (TO-BE-PAID/PAID/TIME-OUT/FAIL). Un callback TO-BE-PAID sera déclenché lorsqu'une commande n'est pas entièrement payée.
time	int	Heure finale sur la chaîne (en cas d'échec, retourne la période de timeout)
amount_collected	string	Nombre de tokens que l'utilisateur a payés
contract	string	Adresse du contrat pour le token, la devise principale étant ETH/TRX/BNB
from_address	string	Adresse du portefeuille de paiement
to_address	string	Adresse du portefeuille de réception

💡

Les marchands signent pour garantir la sécurité des informations. Une fois la commande traitée avec succès, veuillez retourner "Success" dans le corps de la réponse HTTP. Si le traitement échoue, HaloPay tentera de renvoyer la commande et le Webhook réessaiera jusqu'à 15 fois (Fréquence des callbacks : 5s, 15s, 30s, 3m, 10m, 20m, 30m, 30m, 30m, 60m, 3h, 3h, 3h, 6h, 6h, Total : 24h3m50s).

📌 Exemple

Requête vers le serveur Webhook du marchand

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

{
  "appid": "ad4cyr8dpfs...",
  "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": "008f81782daa47709d67bc2073ffff639035cfd...",
  "status": "PAID",
  "time": 1773471015
}

Réponse du serveur Webhook du marchand

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

Success

Notification Webhook​

📌 Exemple​

Notification Webhook

📌 Exemple