Webhook

Webhook is a kind of feedback method for payment information.
When invoice status changes, a POST request is sent to the url_callback specified when creating the invoice.

Response

Response parameters

Name	Definition
type	Invoice type (wallet / payment)
uuid	uuid of the payment
order_id	Order ID in your system (to identify the order)
amount	The amount of the invoice
payment_amount	Amount actually paid by client
payment_amount_usd	Amount actually paid by client in USD
merchant_amount	The amount added to the merchant's balance, with all commissions subtracted.
commission	Cryptomus commission amount
is_final	Whether the invoice is finalized. When invoice is finalized it is impossible to pay an invoice (it's either paid or expired)
status	Payment statusAvailable options:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid
from	Payer's wallet address
wallet_address_uuid	uuid of the static wallet
network	The blockchain network in which the payment is made
currency	Invoice currency
payer_currency	The currency that the client actually paid with
additional_data	Additional information string that you provided when creating an invoice
convert	Information about the currency to which the payment will be automatically converted. Conversion is performed from payer_currency to USDTThe convert field will not exist if you have not enabled the automatic conversion function for payer_currency (e.g. auto convert BTC to USDT) Structure
txid	Transaction hash on the blockchain.The txid field will not exist if1) payment was paid by p2p (The payer withdrew funds from his Cryptomus account to the address indicated in the invoice and the payment was made without blockchain, only in our system)2) Payment was not paid3) Something was wrong with the payment or the client made a mistake and we marked it as ‘paid’ manually
sign	Signature

: Definition
Invoice type (wallet / payment)
: Definition
uuid of the payment
: Definition
Order ID in your system (to identify the order)
: Definition
The amount of the invoice
: Definition
Amount actually paid by client
: Definition
Amount actually paid by client in USD
: Definition
The amount added to the merchant's balance, with all commissions subtracted.
: Definition
Cryptomus commission amount
: Definition
Whether the invoice is finalized. When invoice is finalized it is impossible to pay an invoice (it's either paid or expired)
: Definition
Payment statusAvailable options:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid
: Definition
Payer's wallet address
: Definition
uuid of the static wallet
: Definition
The blockchain network in which the payment is made
: Definition
Invoice currency
: Definition
The currency that the client actually paid with
: Definition
Additional information string that you provided when creating an invoice
: Definition
Information about the currency to which the payment will be automatically converted. Conversion is performed from payer_currency to USDTThe convert field will not exist if you have not enabled the automatic conversion function for payer_currency (e.g. auto convert BTC to USDT) Structure
: Definition
Transaction hash on the blockchain.The txid field will not exist if1) payment was paid by p2p (The payer withdrew funds from his Cryptomus account to the address indicated in the invoice and the payment was made without blockchain, only in our system)2) Payment was not paid3) Something was wrong with the payment or the client made a mistake and we marked it as ‘paid’ manually
: Definition
Signature

Structure of convert

Name	Definition
to_currency	The currency code to which the payment will be converted
commission	Conversion fee
rate	Conversion rate
amount	Conversion amount in to_currency that was added to the merchant's balance, with all commissions subtracted.amount here equals merchant_amount * rate

: Definition
The currency code to which the payment will be converted
: Definition
Conversion fee
: Definition
Conversion rate
: Definition
Conversion amount in to_currency that was added to the merchant's balance, with all commissions subtracted.amount here equals merchant_amount * rate

Response example


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}

COPY

Webhook verification

Since by receiving webhooks you are releasing products or crediting your users' balances, you need to make sure that you are receiving webhooks from cryptomus and not from anyone else.

We recommend you to check it both ways:

use the ip address whitelist and allow requests to url_callback only from our ips. We send webhooks from ip. 91.227.144.54
Verify signature in every webhook that is coming to your url_callback, read more about this below.

Verifying webhook signature

Your api keys are secret and no one except you and cryptomus should know them. So, when verifying the signature, you will be sure that the webhook was sent by cryptomus.

We create a sign using this algorithm. MD5 hash of the body of the POST request encoded in base64 and combined with your API key.

As the signature comes in the body of the request, to verify it, you need to extract the sign from the response body, generate a hash from the body and your API KEY and match it with the sign parameter.

An example in php:

To receive a json data sent by post to your webhook handler:


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

COPY

Lets say we received webhook with data in this array
First, we need to extract the sign from the array:


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

COPY

Now lets generate a sign using our api payment key:


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

COPY

Finally, we can check if the sign we generated with our api payment key equals the sign that came to webhook.


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

COPY

At this point, you can be sure that the webhook was from cryptomus and that you received all the data correctly

There is a difference when encoding an array of data in php and other languages. PHP does escape slashes and some other languages don’t. Therefore, you may encounter a sign mismatch. You have to escape slashes with backslash to make it work properly.

in 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"}

COPY

in 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

COPY