Webhook
Webhook es un tipo de método de retroalimentación para la información de pago.
Cuando cambia el estado de la factura, se envía una solicitud de publicación al URL_CALLBack especificada al crear la factura.
Cuando cambia el estado de la factura, se envía una solicitud de publicación al URL_CALLBack especificada al crear la factura.
Respuesta
Parámetros de respuesta
| Nombre | Definición |
|---|---|
| type | Tipo de factura (billetera / pago) |
| uuid | uuid del pago |
| order_id | ID de pedido en su sistema (para identificar el pedido) |
| amount | La cantidad de la factura |
| payment_amount | Monto realmente pagado por el cliente |
| payment_amount_usd | Monto realmente pagado por el cliente en USD |
| merchant_amount | La cantidad se agregó al saldo del comerciante, con todas las comisiones restadas. |
| commission | Cantidad de la Comisión Cryptomus |
| is_final | Si la factura está finalizada. Cuando se finaliza la factura, es imposible pagar una factura (se paga o vence) |
| status | Estado de pagoOpciones Disponibles:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid |
| from | Dirección de la billetera del pagador |
| wallet_address_uuid | uuid de la billetera estática |
| network | La red blockchain en la que se realiza el pago |
| currency | Moneda de factura |
| payer_currency | La moneda que el cliente realmente pagó |
| additional_data | Cadena de información adicional que proporcionó al crear una factura |
| convert | La información sobre la moneda a la que el pago se convertirá automáticamente. La conversión se realiza desde payer_currency a USDTEl campo convert no existirá si no ha habilitado la función de conversión automática para payer_currency (por ejemplo, Auto Convert BTC a USDT) Estructura |
| txid | Hash de transacción en la cadena de bloques.El campo txid no existirá si1) P2P pagó el pago (el pagador retiró los fondos de su cuenta de Cryptomus a la dirección indicada en la factura y el pago se realizó sin blockchain, solo en nuestro sistema)2) El pago no fue pagado3) Algo estaba mal con el pago o el cliente cometió un error y lo marcamos como "pagado" manualmente |
| sign | Firma |
Definición
Tipo de factura (billetera / pago)Definición
uuid del pagoDefinición
ID de pedido en su sistema (para identificar el pedido)Definición
La cantidad de la facturaDefinición
Monto realmente pagado por el clienteDefinición
Monto realmente pagado por el cliente en USDDefinición
La cantidad se agregó al saldo del comerciante, con todas las comisiones restadas.Definición
Cantidad de la Comisión CryptomusDefinición
Si la factura está finalizada. Cuando se finaliza la factura, es imposible pagar una factura (se paga o vence)Definición
Estado de pagoOpciones Disponibles:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paidDefinición
Dirección de la billetera del pagadorDefinición
uuid de la billetera estáticaDefinición
La red blockchain en la que se realiza el pagoDefinición
Moneda de facturaDefinición
La moneda que el cliente realmente pagóDefinición
Cadena de información adicional que proporcionó al crear una facturaDefinición
La información sobre la moneda a la que el pago se convertirá automáticamente. La conversión se realiza desde payer_currency a USDTEl campo convert no existirá si no ha habilitado la función de conversión automática para payer_currency (por ejemplo, Auto Convert BTC a USDT) EstructuraDefinición
Hash de transacción en la cadena de bloques.El campo txid no existirá si1) P2P pagó el pago (el pagador retiró los fondos de su cuenta de Cryptomus a la dirección indicada en la factura y el pago se realizó sin blockchain, solo en nuestro sistema)2) El pago no fue pagado3) Algo estaba mal con el pago o el cliente cometió un error y lo marcamos como "pagado" manualmenteDefinición
Firma
Estructura de convert
| Nombre | Definición |
|---|---|
| to_currency | El código de moneda al que se convertirá el pago |
| commission | Tarifa de conversión |
| rate | Tasa de conversión |
| amount | Cantidad de conversión to_currency que se agregó al saldo del comerciante, con todas las comisiones restadas.la cantidad aquí es igual a comerciante_amunt * tasa |
Definición
El código de moneda al que se convertirá el pagoDefinición
Tarifa de conversiónDefinición
Tasa de conversiónDefinición
Cantidad de conversión to_currency que se agregó al saldo del comerciante, con todas las comisiones restadas.la cantidad aquí es igual a comerciante_amunt * tasa
Ejemplo de respuesta
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}Verificación de webhook
Dado que al recibir webhooks está lanzando productos o acreditar los saldos de sus usuarios, debe asegurarse de recibir webhooks de Cryptomus y no de nadie más.
Le recomendamos que lo revise en ambos sentidos:
- Use la lista blanca de la dirección IP y permita las solicitudes de URL_CALLBack solo desde nuestro IPS. Enviamos webhooks desde IP. 91.227.144.54
- Verifique la firma en cada webhook que llegue a su URL_Callback, lea más sobre esto a continuación.
Verificación de la firma de webhook
Tus claves API son secretas y nadie excepto tú y Cryptomus deberían conocerlas. Entonces, al verificar la firma, estará seguro de que el webhook fue enviado por Cryptomus.
Creamos un letrero usando este algoritmo. MD5 hash del cuerpo de la solicitud posterior codificada en Base64 y combinado con su clave API.
A medida que la firma viene en el cuerpo de la solicitud, para verificarla, debe extraer el signo del cuerpo de respuesta, generar un hash del cuerpo y su clave API y combinarlo con el parámetro de signo.
Un ejemplo en PHP:
Para recibir un datos JSON enviados por publicación a su controlador webhook:
1$data = file_get_contents('php://input');
2$data = json_decode($data, true);Digamos que recibimos webhook con datos en este formación
Primero, necesitamos extraer el letrero de la matriz:
1$sign = $data['sign'];
2unset($data['sign']);Ahora generemos un signo usando nuestra clave de pago de API:
1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);Finalmente, podemos verificar si el letrero que generamos con nuestra clave de pago API es igual a la señal que llegó a Webhook.
1if (!hash_equals($hash, $sign)) {
2 return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8 return new InvalidHashException();
9}En este punto, puede estar seguro de que el webhook era de Cryptomus y que recibió todos los datos correctamente
Hay una diferencia al codificar una variedad de datos en PHP y otros idiomas. PHP escapa de corte y otros idiomas no. Por lo tanto, puede encontrar una falta de coincidencia. Tienes que escapar de las cortes con barra invertida para que funcione correctamente.
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"}En 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