> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-crossramp-fiat-crypto-solutions/eu-open-banking/open-banking-payin-eur-gbp-usdc/webhook-for-tylt-crossramp-pay-in.md). # Webhook for Tylt CrossRamp (Pay-in) #### Overview Tylt provides a webhook mechanism for merchants to receive real-time updates on the status of their payment instance, whether for pay-ins or for pay-outs. Merchants can specify a `callBackUrl` in their API requests, and Tylt will send notifications to this URL whenever there is a status change in the transaction. #### Setting Up the Webhook 1. **Implement a Callback Endpoint:** Merchants must set up an HTTP POST endpoint that can receive JSON payloads. This endpoint should be capable of processing the incoming webhook data and verifying its authenticity using HMAC-SHA256 signature validation. 2. **Insert the Callback URL:** While calling the Create Pay-in or Create Pay-out instance API's , insert your endpoint URL in the `callBackUrl` field. Tylt will send updates to this URL whenever the transaction status changes. 3. **Status Updates:** The life cycle of a payment instance is tracked via `eventId`. Below is the list of possible `eventId` values and their meanings:
eventIdDescription
1Instance Created
2Order Created
3Order Processing
4Payment Processing
5Payment Completed
6Refund Processing
7Payment Refunded
8Payment Failed
9Order Cancelled or Expired
10KYC Failed
11Settlement Initiated
12Settlement Completed
13Hold
1. **Callback Validation:** To ensure the integrity and authenticity of the callback, Tylt signs each callback payload using HMAC-SHA256 with the merchant’s API secret key. This signature is sent in the HTTP header `X-TLP-SIGNATURE`. 2. **Acknowledge the Callback:** Upon receiving the callback, merchants must respond with an HTTP 200 status code and the text `"ok"` in the response body. This acknowledges the successful receipt of the callback. If the acknowledgment is not received, the webhook will not be retried automatically. Merchants can manually resend web-hooks from their Tylt dashboard. #### Validating Callbacks Merchants should validate the HMAC signature included in the `X-TLP-SIGNATURE` header to ensure the callback is from Tylt and has not been tampered with. The HMAC signature is generated using the raw POST data and the `MERCHANT_API_SECRET` as the shared key. #### Example Web-hook Handling Code {% tabs %} {% tab title="JavaScript" %} ```javascript 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.isBuying == 1) { 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}`); }); ``` {% endtab %} {% endtabs %} Again, please note that these code snippets serve as examples and may require modifications based on your specific implementation and framework. **Example of Web-hook Responses** {% tabs %} {% tab title="eventId: 1" %} ```json { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 1, "description": "Instance Created" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "Pending", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "Pending", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId: 2" %} ```json { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 2, "description": "Order Created" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787206071196", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "Pending", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "Pending", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId: 3" %} ```json { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 3, "description": "Order processing" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787206071196", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "Pending", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "Pending", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId: 4" %} ```json { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 4, "description": "Payment processing" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787206071196", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "Pending", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "Pending", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId: 5" %} ```jsonl { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 5, "description": "Payment Completed" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787206071196", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "Pending", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "2026-08-21T00:00:00Z", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId: 12" %} ```jsonl { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 12, "description": "Settlement Pending" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787206071196", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "settlementPending", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "2026-08-21T00:00:00Z", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId:13" %} ```json { "data": { "accounts": { "MDR": 2, "fees": 0.37, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9141, "cryptoCurrency": "USDC", "toReleaseAmount": 5.47 }, "isBuying": 1, "instanceId": "c8439580-1d48-4d47-9a0e-c4a559a35913", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 13, "description": "Completed" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787206071196", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "0xc8e8df85173d52fc93d97acfc42afa99f84a8fa2fd7d9c83865626fca12ccecb", "Status": "completed", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "2026-08-20T06:21:52Z", "settlementType": "T+1" } } } ``` {% endtab %} {% tab title="eventId: 14" %} ```json { "data": { "accounts": { "MDR": 2, "fees": 0.7, "rate": 0.8564, "fiatAmount": 5, "cryptoAmount": 5.84, "fiatCurrency": "EUR", "effectiveRate": 0.9728, "cryptoCurrency": "USDC", "toReleaseAmount": 5.14 }, "isBuying": 1, "instanceId": "9d6b5178-ce35-400a-8dd7-326e01f3d692", "callBackUrl": "https://gaming-demo.web.app/", "eventDetails": { "eventId": 14, "description": "Hold" }, "walletDetails": { "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "network": "BSC" }, "merchantOrderId": "ivytest1787202341649", "autoMerchantApproval": 1, "cryptoSettlementDetails": { "hash": "Pending", "Status": "hold", "Network": "BSC", "address": "0x82e679f09bfd0c28506314dd851e379a083b5094", "transferType": "external", "settlementTime": "2026-08-20T05:11:58Z", "settlementType": "T+1" } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Important Considerations** * **Security:** Always verify the `X-TLP-SIGNATURE` header to ensure the callback originates from Tylt. * **Response:** Always return an HTTP 200 response with `"ok"` in the body to acknowledge successful receipt of the web-hook. * **Manual Retry:** In case of missed callbacks, use the tylt.money dashboard to manually resend the webhook. {% endhint %}