Webhook

Webhook é um tipo de método de feedback para informações de pagamento.
Quando o status da fatura muda, uma solicitação de postagem é enviada para o url_callback especificado ao criar a fatura.

Resposta

Parâmetros de resposta

Nome	Definição
type	Tipo de fatura (carteira / pagamento)
uuid	Uuid do pagamento
order_id	Pedido ID em seu sistema (para identificar o pedido)
amount	A quantidade da fatura
payment_amount	Valor realmente pago pelo cliente
payment_amount_usd	Valor realmente pago pelo cliente em USD
merchant_amount	O valor adicionado ao saldo do comerciante, com todas as comissões subtraídas.
commission	Montante da Comissão Cryptomus
is_final	Se a fatura está finalizada. Quando a fatura é finalizada, é impossível pagar uma fatura (é paga ou expirada)
status	Status do pagamentoOpções disponíveis:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid
from	Endereço da carteira do pagador
wallet_address_uuid	uuid da carteira estática
network	A rede blockchain na qual o pagamento é feito
currency	Moeda da fatura
payer_currency	A moeda que o cliente realmente pagou
payer_amount	O valor do pagamento planejado é definido no momento da criação do pagamento.
payer_amount_exchange_rate	A taxa de câmbio aplicada no momento da execução do pagamento.
transfer_id	Identificador de uma transferência P2P interna dentro do sistema (para pagamentos locais).
additional_data	String de informações adicionais que você forneceu ao criar uma fatura
convert	Informações sobre a moeda para a qual o pagamento serão convertidas automaticamente. A conversão é realizada de pager_currency para USDTO campo convert não existirá se você não tivesse ativado a função de conversão automática para payer_currency (por exemplo, convert btc automático em USDT) Estrutura
txid	Hash de transação no blockchain.O campo txid não existirá se1) O pagamento foi pago por P2P (o pagador retirou fundos de sua conta Cryptomus para o endereço indicado na fatura e o pagamento foi feito sem blockchain, apenas em nosso sistema)2) O pagamento não foi pago3) Algo estava errado com o pagamento ou o cliente cometeu um erro e nós o marcamos como "pago" manualmente
sign	Assinatura

: Definição
Tipo de fatura (carteira / pagamento)
: Definição
Uuid do pagamento
: Definição
Pedido ID em seu sistema (para identificar o pedido)
: Definição
A quantidade da fatura
: Definição
Valor realmente pago pelo cliente
: Definição
Valor realmente pago pelo cliente em USD
: Definição
O valor adicionado ao saldo do comerciante, com todas as comissões subtraídas.
: Definição
Montante da Comissão Cryptomus
: Definição
Se a fatura está finalizada. Quando a fatura é finalizada, é impossível pagar uma fatura (é paga ou expirada)
: Definição
Status do pagamentoOpções disponíveis:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid
: Definição
Endereço da carteira do pagador
: Definição
uuid da carteira estática
: Definição
A rede blockchain na qual o pagamento é feito
: Definição
Moeda da fatura
: Definição
A moeda que o cliente realmente pagou
: Definição
O valor do pagamento planejado é definido no momento da criação do pagamento.
: Definição
A taxa de câmbio aplicada no momento da execução do pagamento.
: Definição
Identificador de uma transferência P2P interna dentro do sistema (para pagamentos locais).
: Definição
String de informações adicionais que você forneceu ao criar uma fatura
: Definição
Informações sobre a moeda para a qual o pagamento serão convertidas automaticamente. A conversão é realizada de pager_currency para USDTO campo convert não existirá se você não tivesse ativado a função de conversão automática para payer_currency (por exemplo, convert btc automático em USDT) Estrutura
: Definição
Hash de transação no blockchain.O campo txid não existirá se1) O pagamento foi pago por P2P (o pagador retirou fundos de sua conta Cryptomus para o endereço indicado na fatura e o pagamento foi feito sem blockchain, apenas em nosso sistema)2) O pagamento não foi pago3) Algo estava errado com o pagamento ou o cliente cometeu um erro e nós o marcamos como "pago" manualmente
: Definição
Assinatura

Estrutura de convert

Nome	Definição
to_currency	O código da moeda para o qual o pagamento será convertido
commission	Taxa de conversão
rate	Taxa de conversão
amount	Valor da conversão em to_currency que foi adicionado ao saldo do comerciante, com todas as comissões subtraídas.Quantidade aqui é igual à taxa de merchant_amount *

: Definição
O código da moeda para o qual o pagamento será convertido
: Definição
Taxa de conversão
: Definição
Taxa de conversão
: Definição
Valor da conversão em to_currency que foi adicionado ao saldo do comerciante, com todas as comissões subtraídas.Quantidade aqui é igual à taxa de merchant_amount *

Exemplo de resposta


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  "payer_amount": "0.00234567",
18  "payer_amount_exchange_rate": "42650.00000000",
19  "transfer_id": "uuid-123-456"
20  "additional_data": null,
21  "convert": {
22    "to_currency": "USDT",
23    "commission": null,
24    "rate": "0.07700000",
25    "amount": "0.22638000"
26  },
27  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
28  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
29}

Cópia

Verificação de webhook

Como, ao receber webhooks, você está lançando produtos ou creditando os saldos de seus usuários, você precisa garantir que está recebendo webhooks da Cryptomus e não de mais ninguém.

Recomendamos que você verifique os dois lados:

Use a lista de permissões de endereço IP e permita que as solicitações usem url_callback apenas do nosso IPS. Enviamos webhooks do IP. 91.227.144.54
Verifique a assinatura em todos os webhook que estão chegando ao seu url_callback, leia mais sobre isso abaixo.

Verificando a assinatura da webhook

Suas chaves da API são secretas e ninguém, exceto você e Cryptomus, devem conhecê -las. Portanto, ao verificar a assinatura, você terá certeza de que o webhook foi enviado por Cryptomus.

Criamos um sinal usando este algoritmo. Hash MD5 do corpo da solicitação de postagem codificada na base64 e combinada com sua chave da API.

À medida que a assinatura vem no corpo da solicitação, para verificá -la, você precisa extrair o sinal do corpo de resposta, gerar um hash do corpo e sua chave da API e combiná -lo com o parâmetro de sinal.

Um exemplo no PHP:

Para receber um JSON Data enviado por postagem ao seu manipulador de webhook:


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

Cópia

Digamos que recebemos webhook com dados em esse variedade
Primeiro, precisamos extrair o sinal da matriz:


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

Cópia

Agora vamos gerar um sinal usando nossa chave de pagamento da API:


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

Cópia

Por fim, podemos verificar se o sinal que geramos com nossa chave de pagamento da API é igual ao sinal que chegou ao webhook.


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

Cópia

Neste ponto, você pode ter certeza de que o webhook era de Cryptomus e que você recebeu todos os dados corretamente

Há uma diferença ao codificar uma matriz de dados no PHP e em outros idiomas. O PHP escapa barras e alguns outros idiomas não. Portanto, você pode encontrar uma incompatibilidade de sinal. Você precisa escapar de barras com barragem para fazê -lo funcionar corretamente.

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

Cópia

em 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

Cópia