Handle Taliup Payment Webhooks in Your PHP Application

After a payment is captured, Taliup sends a POST request to the webhook_url you provided when creating the checkout session. The request contains a JSON body describing the payment outcome and an X-Taliup-Signature header you must verify before acting on the event. This guide walks you through setting up a reliable, secure webhook receiver.

Always verify the X-Taliup-Signature header before reading or processing any webhook data. Processing unverified payloads exposes your application to spoofed events and fraudulent order fulfilment.

Set webhook_url when creating the checkout session

Pass your HTTPS webhook endpoint as webhook_url in the createCheckoutUrl() payload. Taliup will POST the payment event to this URL after a payment is captured.

$response = $client->hostedPayments()->createCheckoutUrl([
    'amount'      => 49.99,
    'currency'    => 'CAD',
    'reference'   => 'ORDER-10029',
    'redirect_url' => 'https://yoursite.com/payment/success',
    'cancel_url'  => 'https://yoursite.com/payment/cancel',
    'webhook_url' => 'https://yoursite.com/webhooks/taliup', // <-- your endpoint
]);

Create a webhook endpoint

Create a dedicated PHP file at the URL you registered as webhook_url. The endpoint must be publicly reachable over HTTPS.During local development you can expose your local server using a tunnelling tool such as ngrok:

ngrok http 8000
# Use the printed https://xxxx.ngrok.io URL as your webhook_url

Make your TALIUP_MERCHANT_SECRET_KEY available to the script via an environment variable — never hard-code secrets in source files.

Read the raw body and signature header

You must read the raw request body with file_get_contents('php://input') before any other input parsing. Reading from $_POST or calling json_decode() first will alter the body and invalidate the signature.

<?php

require __DIR__ . '/vendor/autoload.php';

use Taliup\Sdk\Exceptions\ApiException;
use Taliup\Sdk\Webhook;

$secret    = (string) getenv('TALIUP_MERCHANT_SECRET_KEY');
$payload   = (string) file_get_contents('php://input'); // raw body — read first
$signature = $_SERVER['HTTP_X_TALIUP_SIGNATURE'] ?? '';

Verify the signature with Webhook::constructEvent()

Pass the raw payload, signature header, and your secret key to Webhook::constructEvent(). If verification succeeds it returns the decoded event as an associative array. If the signature does not match it throws an ApiException with status code 401.

try {
    $event = Webhook::constructEvent($payload, $signature, $secret);
} catch (ApiException $e) {
    // Signature invalid — reject the request
    http_response_code(401);
    exit($e->getMessage());
}

If you only need a boolean result and prefer to handle the failure yourself, you can use Webhook::verify() instead:

$isValid = Webhook::verify($payload, $signature, $secret); // returns bool

if (! $isValid) {
    http_response_code(401);
    exit('Invalid signature.');
}

$event = json_decode($payload, true);

constructEvent() is the recommended approach because it both verifies and decodes the payload atomically, reducing the risk of accidentally processing an unverified event.

Process the event

After successful verification, read the approved flag (or status field) and update your system accordingly. Use the reference field to look up the corresponding order in your database.

The reference value is the order ID you passed when creating the checkout session. Keying your lookup on reference is more reliable than matching on transaction_id, which is generated by Taliup.

$reference = $event['reference'] ?? null;
$approved  = $event['approved']  ?? false;

if ($approved) {
    // Mark the order as paid in your database
    error_log("Payment approved for order: {$reference}");
    // e.g. Orders::markAsPaid($reference);
} else {
    // Handle declined or failed payment
    error_log("Payment not approved for order: {$reference}");
    // e.g. Orders::markAsFailed($reference);
}

Return 200 OK

Respond with HTTP 200 to acknowledge receipt. If Taliup does not receive a 200 response it will retry the webhook. Return the acknowledgement as early as possible — after verification and before any slow database or downstream operations if you can.

http_response_code(200);
echo json_encode(['received' => true]);

Complete webhook receiver

The following is a production-ready webhook receiver based on the official SDK example:

<?php

/**
 * Taliup webhook receiver.
 *
 * Deploy this file at your webhook_url.
 * Required environment variable: TALIUP_MERCHANT_SECRET_KEY
 */

require __DIR__ . '/vendor/autoload.php';

use Taliup\Sdk\Exceptions\ApiException;
use Taliup\Sdk\Webhook;

$secret = (string) getenv('TALIUP_MERCHANT_SECRET_KEY');

if ($secret === '') {
    http_response_code(500);
    exit('Missing TALIUP_MERCHANT_SECRET_KEY.');
}

// Read the raw body BEFORE any other input parsing
$payload   = (string) file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TALIUP_SIGNATURE'] ?? '';

// Verify signature and decode payload
try {
    $event = Webhook::constructEvent($payload, $signature, $secret);
} catch (ApiException $e) {
    http_response_code(401);
    exit($e->getMessage());
}

// Extract the fields you need
$reference = $event['reference'] ?? null;
$approved  = $event['approved']  ?? false;

if ($approved) {
    // TODO: mark the order as paid in your system using $reference
    error_log("Payment approved for order: {$reference}");
} else {
    // TODO: handle declined/failed payment
    error_log("Payment not approved for order: {$reference}");
}

// Acknowledge receipt — return 200 so Taliup does not retry
http_response_code(200);
echo json_encode(['received' => true]);

Webhook payload reference

Taliup sends the following JSON body on every payment.captured event:

{
    "event":              "payment.captured",
    "merchant_site_id":   "your_merchant_site_id",
    "transaction_id":     "abc123",
    "amount":             "49.99",
    "currency":           "CAD",
    "status":             "approved",
    "approved":           true,
    "card_type":          "VISA",
    "card_number_masked": "41**********1111",
    "reference":          "ORDER-10029",
    "timestamp":          "2026-05-14T18:00:00+00:00"
}

Field	Type	Description
`event`	string	Event type. Currently `payment.captured`.
`merchant_site_id`	string	Your Merchant Site ID.
`transaction_id`	string	Taliup’s unique transaction identifier.
`amount`	string	Payment amount as a decimal string.
`currency`	string	Three-letter currency code (`CAD` or `USD`).
`status`	string	`approved`, `declined`, or another terminal status.
`approved`	boolean	`true` when the payment was approved, `false` otherwise.
`card_type`	string	Card network (e.g. `VISA`, `MASTERCARD`).
`card_number_masked`	string	Masked card number for display purposes.
`reference`	string	The order reference you passed when creating the session.
`timestamp`	string	ISO 8601 timestamp of the payment event.

Get started

Core concepts

Guides

Handle Taliup Payment Webhooks in Your PHP Application

Complete webhook receiver

Webhook payload reference

​Complete webhook receiver

​Webhook payload reference

Complete webhook receiver

Webhook payload reference