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

NameDefinition
typeInvoice type (wallet / payment)
uuidmethods.UUID of the payment
order_idOrder ID in your system (to identify the order)
amountThe amount of the invoice
payment_amountAmount actually paid by client
payment_amount_usdAmount actually paid by client in USD
merchant_amountThe amount added to the merchant's balance, with all commissions subtracted.
commissionCryptomus commission amount
is_finalWhether the invoice is finalized. When invoice is finalized it is impossible to pay an invoice (it's either paid or expired)
statusPayment statusAvailable options:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid
fromPayer's wallet address
wallet_address_uuidmethods.UUID of the static wallet
networkThe blockchain network in which the payment is made
currencyInvoice currency
payer_currencyThe currency that the client actually paid with
additional_dataAdditional information string that you provided when creating an invoice
convertInformation 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
txidTransaction 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
signSignature

Definition

Invoice type (wallet / payment)

Definition

methods.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

methods.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

NameDefinition
to_currencyThe currency code to which the payment will be converted
commissionConversion fee
rateConversion rate
amountConversion 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