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 de eventId e 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": {}
    }
}

Considerações Importantes

  • Segurança: Sempre verifique o cabeçalho X-TLP-SIGNATURE para garantir que o callback se origina da Tylt.

  • Resposta: Sempre retorne uma resposta HTTP 200 com o texto "ok" no corpo para confirmar o recebimento bem-sucedido do webhook.

  • Reenvio Manual: Em caso de callbacks não recebidos, utilize o painel da tylt.money para reenviar manualmente o webhook.

Last updated