Webhook for Administrators

Tylt provides a webhook mechanism for approved rail partners to receive real-time updates on the status of payment instances for both pay-ins and pay-outs. For the Philippines PHP rail, this webhook page applies to:

Flow	Description
QRPH Pay-In	PHP pay-in transaction where the end user pays in PHP and the merchant receives USDT settlement value.
InstaPay / PESONet Pay-Out	PHP pay-out transaction where USDT value is used to initiate a PHP disbursement.

Tylt sends webhook notifications whenever there is a status change in the transaction lifecycle. The lifecycle is tracked using eventId, which identifies the current state of the payment instance. The existing Tylt webhook page states that callbacks are sent on transaction status changes and that the lifecycle is tracked through eventId.

---

Setting Up the Webhook

The partner must provide Tylt with an HTTP POST endpoint that can receive JSON webhook payloads.

The webhook endpoint should be capable of:

1. Receiving JSON payloads from Tylt.

2. Verifying the authenticity of the webhook using HMAC-SHA256 signature validation.

3. Processing the transaction status update based on the eventId.

4. Returning an HTTP 200 response with ok in the response body.

Tylt signs each webhook payload using HMAC-SHA256 and sends the signature in the X-TLP-SIGNATURE header. The existing webhook page also specifies that the callback endpoint must validate the signature and acknowledge the webhook with HTTP 200 and body "ok".

---

Webhook Header

Header	Description
X-TLP-SIGNATURE	HMAC-SHA256 signature generated using the raw POST data and the partner’s API secret key.

---

Pay-In Lifecycle

For QRPH pay-ins, Tylt sends webhook updates as the pay-in instance moves through the payment lifecycle.

eventId 1 → Instance Created
eventId 2 → Order Created
eventId 3 → Payment Processing
eventId 4 → Payment Completed

Exception or unsuccessful states may include:

eventId 8  → Payment Failed
eventId 9  → Order Cancelled or Expired
eventId 10 → KYC Failed

The partner should use the instanceId, merchantOrderId, and eventDetails.eventId to identify and process the pay-in update.

---

Pay-Out Lifecycle

For InstaPay / PESONet pay-outs, Tylt sends webhook updates as the pay-out instance moves through the payment lifecycle.

eventId 1 → Instance Created
eventId 2 → Order Created
eventId 3 → Payment Processing
eventId 4 → Payment Completed

Exception or unsuccessful states may include:

eventId 8  → Payment Failed
eventId 9  → Order Cancelled or Expired
eventId 10 → KYC Failed

The partner should use the instanceId, merchantOrderId, and eventDetails.eventId to identify and process the pay-out update.

---

Validating Webhooks

Partners should validate the HMAC signature included in the X-TLP-SIGNATURE header to confirm that the webhook was sent by Tylt and that the payload has not been modified.

The HMAC signature is generated using:

HMAC-SHA256(raw POST data, API_SECRET)

The generated signature should be compared with the value received in the X-TLP-SIGNATURE header.

---

Example Webhook Handling Code

const express = require("express");
const crypto = require("crypto");

const app = express();
const PORT = 3000;
const apiSecretKey = "YOUR_TLP_API_SECRET_KEY";

// Middleware to parse incoming JSON requests
app.use(express.json());

// Callback endpoint
app.post("/callback", (req, res) => {
  const data = req.body;

  const tlpSignature = req.headers["x-tlp-signature"];

  const calculatedHmac = crypto
    .createHmac("sha256", apiSecretKey)
    .update(JSON.stringify(data))
    .digest("hex");

  if (calculatedHmac === tlpSignature) {
    console.log("Received Tylt webhook:", data);

    const eventId = data?.data?.eventDetails?.eventId;
    const instanceId = data?.data?.instanceId;
    const merchantOrderId = data?.data?.merchantOrderId;

    console.log("Event ID:", eventId);
    console.log("Instance ID:", instanceId);
    console.log("Merchant Order ID:", merchantOrderId);

    // Process the webhook based on eventId
    // 1  = Instance Created
    // 2  = Order Created
    // 3  = Payment Processing
    // 4  = Payment Completed
    // 8  = Payment Failed
    // 9  = Order Cancelled or Expired
    // 10 = KYC Failed

    return res.status(200).send("ok");
  }

  return res.status(400).send("Invalid HMAC signature");
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

Webhook Acknowledgement

After receiving and validating the webhook, the partner must return:

HTTP 200

with the response body:

ok

If Tylt does not receive this acknowledgement, the webhook will not be retried automatically. Missed callbacks can be resent manually from the Tylt dashboard. (Tylt Documentation)

---

Important Considerations

Area	Requirement
Signature validation	Always verify the X-TLP-SIGNATURE header before processing the webhook.
Response	Always return HTTP 200 with ok in the response body after successful receipt.
Manual retry	If a callback is missed, the webhook can be manually resent from the Tylt dashboard.
Lifecycle handling	Use eventDetails.eventId to determine the current transaction state.
Reconciliation	Store instanceId, merchantOrderId, eventId, fiat amount, crypto amount, rate, and timestamp for reconciliation.

---