Webhook

WebHook est une sorte de mode de rétroaction pour les informations de paiement.
Lorsque l'état de la facture change, une demande de poste est envoyée à l'URL_CALLBACK spécifiée lors de la création de la facture.

Réponse

Paramètres de réponse

Nom	Définition
type	Type de facture (portefeuille / paiement)
uuid	uuid du paiement
order_id	ID de commande dans votre système (pour identifier la commande)
amount	Le montant de la facture
payment_amount	Montant réellement payé par le client
payment_amount_usd	Montant réellement payé par le client en USD
merchant_amount	Le montant ajouté au solde du marchand, avec toutes les commissions soustraites.
commission	Montant de la commission Cryptomus
is_final	Si la facture est finalisée. Lorsque la facture est finalisée, il est impossible de payer une facture (elle est payée ou expirée)
status	Statut de paiementOptions disponibles:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid
from	Adresse du portefeuille du payeur
wallet_address_uuid	uuid du portefeuille statique
network	Le réseau de blockchain dans lequel le paiement est effectué
currency	Facture monnaie
payer_currency	La monnaie avec laquelle le client a réellement payé
additional_data	Chaîne d'informations supplémentaires que vous avez fournie lors de la création d'une facture
convert	Des informations sur la monnaie à laquelle le paiement sera automatiquement converti. La conversion est effectuée à partir de Payer_Currency en USDTLe champ convert n'existera pas si vous n'avez pas activé la fonction de conversion automatique pour payer_currency (par exemple, converti Auto BTC en USDT) Structure
txid	Hash de transaction sur la blockchain.Le champ txid n'existera pas si1) Le paiement a été payé par P2P (le payeur a retiré les fonds de son compte Cryptomus à l'adresse indiquée dans la facture et le paiement a été effectué sans blockchain, seulement dans notre système)2) Le paiement n'a pas été payé3) Quelque chose n'allait pas avec le paiement ou le client a fait une erreur et nous l'avons marqué manuellement comme «payé»
sign	Signature

: Définition
Type de facture (portefeuille / paiement)
: Définition
uuid du paiement
: Définition
ID de commande dans votre système (pour identifier la commande)
: Définition
Le montant de la facture
: Définition
Montant réellement payé par le client
: Définition
Montant réellement payé par le client en USD
: Définition
Le montant ajouté au solde du marchand, avec toutes les commissions soustraites.
: Définition
Montant de la commission Cryptomus
: Définition
Si la facture est finalisée. Lorsque la facture est finalisée, il est impossible de payer une facture (elle est payée ou expirée)
: Définition
Statut de paiementOptions disponibles:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid
: Définition
Adresse du portefeuille du payeur
: Définition
uuid du portefeuille statique
: Définition
Le réseau de blockchain dans lequel le paiement est effectué
: Définition
Facture monnaie
: Définition
La monnaie avec laquelle le client a réellement payé
: Définition
Chaîne d'informations supplémentaires que vous avez fournie lors de la création d'une facture
: Définition
Des informations sur la monnaie à laquelle le paiement sera automatiquement converti. La conversion est effectuée à partir de Payer_Currency en USDTLe champ convert n'existera pas si vous n'avez pas activé la fonction de conversion automatique pour payer_currency (par exemple, converti Auto BTC en USDT) Structure
: Définition
Hash de transaction sur la blockchain.Le champ txid n'existera pas si1) Le paiement a été payé par P2P (le payeur a retiré les fonds de son compte Cryptomus à l'adresse indiquée dans la facture et le paiement a été effectué sans blockchain, seulement dans notre système)2) Le paiement n'a pas été payé3) Quelque chose n'allait pas avec le paiement ou le client a fait une erreur et nous l'avons marqué manuellement comme «payé»
: Définition
Signature

Structure de convert

Nom	Définition
to_currency	Le code de devise auquel le paiement sera converti
commission	Frais de conversion
rate	Taux de conversion
amount	Montant de conversion to_currency qui a été ajouté au solde du marchand, avec toutes les commissions soustraites.Le montant ici équivaut à Merchant_amount *

: Définition
Le code de devise auquel le paiement sera converti
: Définition
Frais de conversion
: Définition
Taux de conversion
: Définition
Montant de conversion to_currency qui a été ajouté au solde du marchand, avec toutes les commissions soustraites.Le montant ici équivaut à Merchant_amount *

Exemple de réponse


1{
2  "type": "payment",
3  "uuid": "62f88b36-a9d5-4fa6-aa26-e040c3dbf26d",
4  "order_id": "97a75bf8eda5cca41ba9d2e104840fcd",
5  "amount": "3.00000000",
6  "payment_amount": "3.00000000",
7  "payment_amount_usd": "0.23",
8  "merchant_amount": "2.94000000",
9  "commission": "0.06000000",
10  "is_final": true,
11  "status": "paid",
12  "from": "THgEWubVc8tPKXLJ4VZ5zbiiAK7AgqSeGH",
13  "wallet_address_uuid": null,
14  "network": "tron",
15  "currency": "TRX",
16  "payer_currency": "TRX",
17  "additional_data": null,
18  "convert": {
19    "to_currency": "USDT",
20    "commission": null,
21    "rate": "0.07700000",
22    "amount": "0.22638000"
23  },
24  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
25  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
26}

COPIE

Vérification Webhook

Étant donné qu'en recevant des webhooks, vous publiez des produits ou créditez les soldes de vos utilisateurs, vous devez vous assurer que vous recevez des webhooks de Cryptomus et non de quelqu'un d'autre.

Nous vous recommandons de le vérifier dans les deux sens:

Utilisez la liste blanche de l'adresse IP et autorisez les demandes à URL_CALLBACK uniquement à partir de nos IPS. Nous envoyons des webhooks à partir d'IP. 91.227.144.54
Vérifiez la signature dans chaque webhook qui arrive sur votre URL_CALLBACK, en savoir plus à ce sujet ci-dessous.

Vérification de la signature de Webhook

Vos clés d'API sont secrètes et personne, sauf que vous et Cryptomus ne devriez les connaître. Ainsi, lors de la vérification de la signature, vous serez sûr que le webhook a été envoyé par Cryptomus.

Nous créons un signe en utilisant cet algorithme. Le hachage MD5 du corps de la demande post-demande encodé dans Base64 et combiné avec votre clé API.

Comme la signature vient dans le corps de la demande, pour la vérifier, vous devez extraire le signe du corps de réponse, générer un hachage à partir du corps et de votre clé API et de le faire correspondre avec le paramètre de signe.

Un exemple de PHP:

Pour recevoir des données JSON envoyées par publication à votre gestionnaire de webhook:


1$data = file_get_contents('php://input');
2$data = json_decode($data, true);

COPIE

Disons que nous avons reçu webhook avec des données dans ce tableau
Tout d'abord, nous devons extraire le panneau du tableau:


1$sign = $data['sign'];
2unset($data['sign']);

COPIE

Permet maintenant de générer un panneau en utilisant notre clé de paiement API:


1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);

COPIE

Enfin, nous pouvons vérifier si le signe que nous avons généré avec notre clé de paiement API est égal au signe qui est venu sur WebHook.


1if (!hash_equals($hash, $sign)) {
2   return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8   return new InvalidHashException();
9}

COPIE

À ce stade, vous pouvez être sûr que le webhook venait de Cryptomus et que vous avez reçu correctement toutes les données

Il y a une différence lors du codage d'un tableau de données en PHP et dans d'autres langues. PHP échappe aux barres obliques et certaines autres langues ne le font pas. Par conséquent, vous pouvez rencontrer un décalage des signes. Vous devez échapper aux barres obliques à barres oblidviennes pour le faire fonctionner correctement.

en php:


1//  data array
2$data = [
3    'amount' => '20',
4    'currency' => 'USDT',
5    'network' => 'tron',
6    'txid' => 'someTxidWith/Slash'
7];
8
9// json data we send to webhooks
10$data = json_encode($data, true);
11echo $data;
12// Outputs a string, slash in txid is escaped, pay attention to this.
13// we send a webhook data with all escaped slashes
14// {"amount":"20","currency":"USD","network":"btc","txid":"someTxidWith/Slash"}

COPIE

Dans JS:


1const data = {
2    amount: '20',
3    currency: 'USDT',
4    network: 'tron',
5    txid: 'someTxidWith/Slash'
6};
7
8const jsonData = JSON.stringify(data);
9console.log(jsonData);
10// {"amount":"20","currency":"USDT","network":"tron","txid":"someTxidWith/Slash"}
11// slash in txid is not escaped and you will get error checking sign.
12// Instead, you should do it like this:
13// const jsonData = JSON.stringify(data).replace(///mg, "\/");
14

COPIE