Webhook

WebHook to rodzaj informacji zwrotnej do informacji o płatności.
Po zmianie statusu faktury żądanie POST jest wysyłane do URL_CALLBACK określone podczas tworzenia faktury.

Odpowiedź

Parametry odpowiedzi

NazwaDefinicja
typeTyp faktury (portfel / płatność)
uuiduuid płatności
order_idIdentyfikator zamówienia w systemie (w celu zidentyfikowania zamówienia)
amountIlość faktury
payment_amountKwota faktycznie zapłacona przez klienta
payment_amount_usdKwota faktycznie opłacona przez klienta w USD
merchant_amountKwota dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji.
commissionKwota Komisji Cryptomus
is_finalCzy faktura jest sfinalizowana. Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)
statusStatus płatnościDostępne opcje:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid
fromAdres portfela płatnika
wallet_address_uuidUUID z portfela statycznego
networkSieć blockchain, w której dokonana jest płatność
currencyWaluta faktury
payer_currencyWaluta, którą klient faktycznie zapłacił
additional_dataDodatkowy ciąg informacji, który podałeś podczas tworzenia faktury
convertInformacje o walucie, do której płatność zostanie automatycznie przekonwertowana. Konwersja odbywa się z płatnika_currency do USDTPole convert nie będzie istniało, jeśli nie włączyłeś automatycznej funkcji konwersji dla payer_currency (np. Auto konwertuj BTC na USDT) Struktura
txidHash transakcji na blockchain.Pole txid nie będzie istniało, jeśli1) Płatność została wypłacona przez P2P (płatnik wycofał fundusze z jego konta kryptomusa na adres wskazany na fakturze, a płatność została dokonana bez blockchain, tylko w naszym systemie)2) Płatność nie została zapłacona3) Coś było nie tak z płatnością lub klient popełnił błąd i zaznaczyliśmy to jako „opłacone” ręcznie
signPodpis

Definicja

Typ faktury (portfel / płatność)

Definicja

uuid płatności

Definicja

Identyfikator zamówienia w systemie (w celu zidentyfikowania zamówienia)

Definicja

Ilość faktury

Definicja

Kwota faktycznie zapłacona przez klienta

Definicja

Kwota faktycznie opłacona przez klienta w USD

Definicja

Kwota dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji.

Definicja

Kwota Komisji Cryptomus

Definicja

Czy faktura jest sfinalizowana. Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)

Definicja

Status płatnościDostępne opcje:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid

Definicja

Adres portfela płatnika

Definicja

UUID z portfela statycznego

Definicja

Sieć blockchain, w której dokonana jest płatność

Definicja

Waluta faktury

Definicja

Waluta, którą klient faktycznie zapłacił

Definicja

Dodatkowy ciąg informacji, który podałeś podczas tworzenia faktury

Definicja

Informacje o walucie, do której płatność zostanie automatycznie przekonwertowana. Konwersja odbywa się z płatnika_currency do USDTPole convert nie będzie istniało, jeśli nie włączyłeś automatycznej funkcji konwersji dla payer_currency (np. Auto konwertuj BTC na USDT) Struktura

Definicja

Hash transakcji na blockchain.Pole txid nie będzie istniało, jeśli1) Płatność została wypłacona przez P2P (płatnik wycofał fundusze z jego konta kryptomusa na adres wskazany na fakturze, a płatność została dokonana bez blockchain, tylko w naszym systemie)2) Płatność nie została zapłacona3) Coś było nie tak z płatnością lub klient popełnił błąd i zaznaczyliśmy to jako „opłacone” ręcznie

Definicja

Podpis

Struktura convert

NazwaDefinicja
to_currencyKod waluty, do którego płatność zostanie przekonwertowana
commissionOpłata za konwersję
rateWspółczynnik konwersji
amountKwota konwersji w to_currency, która została dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji.Kwota tutaj równa się stawce merchant_amount *

Definicja

Kod waluty, do którego płatność zostanie przekonwertowana

Definicja

Opłata za konwersję

Definicja

Współczynnik konwersji

Definicja

Kwota konwersji w to_currency, która została dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji.Kwota tutaj równa się stawce merchant_amount *

Przykład odpowiedzi


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}
KOPIUJ

Weryfikacja WebHook

Ponieważ otrzymując haczyki internetowe, wypuszczasz produkty lub przypisujesz salda użytkowników, musisz upewnić się, że otrzymujesz haoki internetowe od Cryptomus, a nie od nikogo innego.

Zalecamy sprawdzenie tego na dwa sposoby:

  • Użyj białej listy adresów IP i zezwól na żądania na URL_CALLBACK tylko z naszych IPS. Wysyłamy haoki internetowe z IP. 91.227.144.54
  • Sprawdź podpis w każdym hacie internetowym, który przychodzi do twojego URL_CALLBACK, przeczytaj więcej o tym poniżej.

Weryfikacja podpisu Webhook

Twoje klucze API są tajne i nikt oprócz ciebie i Cryptomus nie powinni ich znać. Tak więc, weryfikując podpis, będziesz pewien, że Webhook został wysłany przez Cryptomus.

Tworzymy znak za pomocą tego algorytmu. Hash MD5 korpusu żądania pocztowego zakodowany w Base64 i połączony z kluczem API.

Gdy podpis pojawia się w ciele żądania, aby go zweryfikować, musisz wyodrębnić znak z ciała odpowiedzi, wygenerować skrót z ciała i klucza API i dopasować go do parametru znaku.

Przykład w PHP:

Aby otrzymać dane JSON wysyłane przez post do przewodnika WebHook:


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

Powiedzmy, że otrzymaliśmy hook Web z danymi w Ten szyk
Najpierw musimy wyodrębnić znak z tablicy:


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

Teraz wygenerujmy znak za pomocą naszego klucza płatności API:


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

Na koniec możemy sprawdzić, czy znak, który wygenerowaliśmy za pomocą naszego klucza płatności API, jest to znak, który przyszedł do Webhook.


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

W tym momencie możesz być pewien, że Webhook pochodzi z Cryptomus i że poprawnie otrzymałeś wszystkie dane

Istnieje różnica przy kodowaniu szeregu danych w PHP i innych językach. PHP ucieka odcinków, a niektóre inne języki nie. Dlatego możesz napotkać niedopasowanie znaku. Musisz uniknąć cięć z rozładowaniem odwrotnym, aby działał poprawnie.

W 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"}
KOPIUJ

W 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
KOPIUJ