Webhook do Tylt Prime
Visão Geral
A Tylt oferece um mecanismo de webhook para que os comerciantes recebam atualizações em tempo real sobre o status de suas instâncias de pagamento — seja para Pay-In (entrada) ou Pay-Out (saída).
Os comerciantes podem especificar uma callBackUrl em suas requisições de API, e a Tylt enviará notificações para essa URL sempre que houver uma mudança de status na transação.
Configuração do Webhook
Implemente um Endpoint de Callback: O comerciante deve configurar um endpoint HTTP POST capaz de receber payloads em JSON. Este endpoint deve ser capaz de processar os dados recebidos e verificar sua autenticidade utilizando validação de assinatura HMAC-SHA256.
Inserir a URL de Callback: Ao utilizar os endpoints de API para criar uma instância de Pay-In ou Pay-Out, insira sua URL de webhook no campo
callBackUrl. A Tylt enviará atualizações para essa URL sempre que o status da transação mudar.Atualizações de Status: O ciclo de vida de uma instância de pagamento é acompanhado por meio do campo
eventId. Abaixo está a lista dos possíveis valores deeventIde seus significados:
eventId
Description
1
A instância e a transação foram criadas. Aguardando o usuário aceitar a cotação.
2
Cotação aceita. Aguardando o usuário inserir o número do CPF.
3
QR Code PIX gerado. Aguardando o usuário realizar o pagamento.
4
Pagamento reconhecido e transação liquidada.
9
Trade expired as action or payment was not completed prior to the deadline or disputed payment was expired due to non payment.
Instance Information
A resposta relacionada à informação de uma instância contém dois objetos principais:
1. Objeto Trade
Este objeto contém todas as informações sobre o cliente que está comprando ou vendendo USDT da contraparte. Ele inclui campos como:
Detalhes do ciclo de vida da transação (por exemplo,
eventId, prazos, descrição)Detalhes sobre moeda fiduciária e criptomoeda (nome da moeda, símbolo, valor, etc.)
Informações do método de pagamento (por exemplo, PIX)
2. Objeto Transaction
Este objeto contém todas as informações sobre os débitos ou créditos financeiros realizados na conta do comerciante.
É relevante para que os comerciantes acompanhem o crédito ou débito ao consumidor em relação à transação.
O objeto transaction só é preenchido quando o eventId é 4, representando a conclusão da transação.
Validação do Callback
Garantir Integridade e Autenticidade
A Tylt assina cada payload de callback utilizando HMAC-SHA256, com a chave secreta da API do comerciante.
Essa assinatura é enviada no cabeçalho HTTP:
X-TLP-SIGNATURE.
Confirmar Recebimento do Callback
Ao receber o callback, o comerciante deve responder com o código de status HTTP 200 e o texto simples "ok" no corpo da resposta.
Essa resposta confirma o recebimento bem-sucedido do callback.
Se a confirmação não for recebida, o webhook não será reenviado automaticamente.
O comerciante pode reenviar manualmente os webhooks a partir do painel Tylt.
Validação do Callback
O comerciante deve validar a assinatura HMAC presente no cabeçalho X-TLP-SIGNATURE para garantir que o callback é realmente da Tylt e não foi alterado.
A assinatura HMAC é gerada usando os dados brutos do POST e a MERCHANT_API_SECRET como chave compartilhada.
Example Web-hook Handling Code
const express = require('express');
const crypto = require('crypto');
const app = express();
const PORT = 3000;
const apiSecretKey = 'YOUR_TLP_API_SECRET_KEY'; // Replace with your actual API secret key
// Middleware to parse incoming JSON requests
app.use(express.json());
// Callback endpoint
app.post('/callback', (req, res) => {
const data = req.body;
// Calculate HMAC signature
const tlpSignature = req.headers['x-tlp-signature'];
const calculatedHmac = crypto
.createHmac('sha256', apiSecretKey)
.update(JSON.stringify(data)) // Use raw body string for HMAC calculation
.digest('hex');
if (calculatedHmac === tlpSignature) {
// Signature is valid
if (data.accounts.transactionType === 'pay-in') {
console.log('Received pay-in callback:', data);
// Process pay-in data here
}
// Return HTTP Response 200 with content "ok"
res.status(200).send('ok');
} else {
// Invalid HMAC signature
res.status(400).send('Invalid HMAC signature');
}
});
// Start the server
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}`);
});
Mais uma vez, observe que estes trechos de código servem apenas como exemplos e podem exigir modificações com base na sua implementação e framework específicos.
Exemplo de Respostas de Webhook
{
"data": {
"trade": {
"event": {
"id": 1,
"deadline": "2025-02-12T05:27:37Z",
"description": "Trade Initiated. Payment Link Generated. Quote displayed."
},
"createdAt": "2025-02-12T05:24:37Z",
"updatedAt": "2025-02-12T05:24:37Z",
"fiatCurrency": {
"name": "Brazilian Real",
"symbol": "BRL"
},
"priceDetails": {
"price": null,
"amount": null,
"paymentAmount": 500
},
"paymentMethod": {
"details": null
},
"cryptoCurrency": {
"name": "Tether",
"symbol": "USDT"
}
},
"transaction": {
"amount": null,
"status": null,
"isFinal": null,
"orderId": null,
"createdAt": null,
"isCredited": null,
"updatedAt": null,
"merchantOrderId": "b73b73b-87wtbc-q36gbc-331n3"
},
"accounts": {
"transactionType": "pay-in",
"amountPaidInLocalCurrency": 500,
"localCurrency": "BRL",
"conversionRate": null,
"amountPaidInCryptoCurrency": null,
"cryptoCurrencySymbol": "USDT",
"MDR_Rate": 1.1,
"merchantAccountCredited": null,
"merchantAccountDebited": null
},
"user": {}
}
}Last updated