Webhook Events Reference

Complete reference of all webhook event types and payload structures.

Complete reference of all webhook events sent by Paysera Checkout.

Event Types

Event	Type	Description
order.paid	order	Order has been fully paid
order.pending_payment	order	Order awaiting payment
payment_link.completed	payment_link	Payment completed via this link
payment_link.expired	payment_link	Payment link expired
payment_link.canceled	payment_link	Payment link was canceled

Timestamps and Amounts

• All timestamps are Unix epoch (seconds since 1970-01-01)
• All amounts are in minor currency units (e.g., cents)

Webhook Payload Structure

Common Structure

{
  "event": {
    "name": "order.paid",
    "type": "order",
    "timestamp": 1736433570
  },
  "order": {
    "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "projectId": "01990618-2c90-7103-9169-752bdaac7a52",
    "status": "paid",
    "amount": 2500,
    "currency": "EUR",
    "reference": "ORDER-12345",
    "amountPaid": 2500,
    "balanceDue": 0,
    "createdAt": 1736433270,
    "updatedAt": 1736433570
  },
  "paymentLink": {
    "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "status": "completed"
  }
}

Event Details

order.paid

Sent when an order has been fully paid (amount paid equals order total).

{
  "event": {
    "name": "order.paid",
    "type": "order",
    "timestamp": 1736433570
  },
  "order": {
    "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "projectId": "01990618-2c90-7103-9169-752bdaac7a52",
    "status": "paid",
    "amount": 2500,
    "currency": "EUR",
    "reference": "ORDER-12345",
    "amountPaid": 2500,
    "balanceDue": 0,
    "createdAt": 1736433270,
    "updatedAt": 1736433570
  },
  "paymentLink": {
    "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "status": "completed"
  }
}

Actions to take:

• Update order status to paid
• Send confirmation email
• Trigger fulfillment

order.pending_payment

Sent when an order is awaiting payment.

{
  "event": {
    "name": "order.pending_payment",
    "type": "order",
    "timestamp": 1736433270
  },
  "order": {
    "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "projectId": "01990618-2c90-7103-9169-752bdaac7a52",
    "status": "pending_payment",
    "amount": 2500,
    "currency": "EUR",
    "reference": "ORDER-12345",
    "amountPaid": 0,
    "balanceDue": 2500,
    "createdAt": 1736433270,
    "updatedAt": 1736433270
  }
}

Actions to take:

• Update order status to awaiting payment
• Send payment instructions if needed

payment_link.completed

Sent when a payment link is used successfully to complete a payment.

{
  "event": {
    "name": "payment_link.completed",
    "type": "payment_link",
    "timestamp": 1736433570
  },
  "order": {
    "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "projectId": "01990618-2c90-7103-9169-752bdaac7a52",
    "status": "paid",
    "amount": 2500,
    "currency": "EUR",
    "reference": "ORDER-12345",
    "amountPaid": 2500,
    "balanceDue": 0,
    "createdAt": 1736433270,
    "updatedAt": 1736433570
  },
  "paymentLink": {
    "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "status": "completed"
  }
}

Actions to take:

• Log payment link completion
• Associate payment method with order if needed

payment_link.expired

Sent when a payment link expires without completion.

{
  "event": {
    "name": "payment_link.expired",
    "type": "payment_link",
    "timestamp": 1736436870
  },
  "order": {
    "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "projectId": "01990618-2c90-7103-9169-752bdaac7a52",
    "status": "pending_payment",
    "amount": 2500,
    "currency": "EUR",
    "reference": "ORDER-12345",
    "amountPaid": 0,
    "balanceDue": 2500,
    "createdAt": 1736433270,
    "updatedAt": 1736433270
  },
  "paymentLink": {
    "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "status": "expired"
  }
}

Actions to take:

• Optionally send reminder email with new payment link
• Consider creating a new payment link

note

Payment link expired status is quasi-terminal. It can transition to completed if a payment settles during the bank flow after expiration.

payment_link.canceled

Sent when a payment link is canceled.

{
  "event": {
    "name": "payment_link.canceled",
    "type": "payment_link",
    "timestamp": 1736433570
  },
  "order": {
    "id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "projectId": "01990618-2c90-7103-9169-752bdaac7a52",
    "status": "pending_payment",
    "amount": 2500,
    "currency": "EUR",
    "reference": "ORDER-12345",
    "amountPaid": 0,
    "balanceDue": 2500,
    "createdAt": 1736433270,
    "updatedAt": 1736433270
  },
  "paymentLink": {
    "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
    "status": "canceled"
  }
}

Actions to take:

• Log cancellation
• Create new payment link if payment still needed

Webhook Headers

Header	Description
Content-Type	application/json
X-Paysera-Signature	HMAC-SHA256 signature
X-Paysera-Event	Event name
X-Paysera-Timestamp	Event timestamp
X-Paysera-Delivery-ID	Unique delivery identifier

Complete Handler Example

PHP

<?php

class WebhookHandler
{
    private string $secret;
    private OrderRepository $orders;

    public function handle(): void
    {
        // Get request data
        $payload = file_get_contents('php://input');
        $signature = $_SERVER['HTTP_X_PAYSERA_SIGNATURE'] ?? '';

        // Verify signature
        if (!$this->verifySignature($payload, $signature)) {
            http_response_code(401);
            return;
        }

        // Parse payload
        $data = json_decode($payload, true);
        $eventName = $data['event']['name'];
        $reference = $data['order']['reference'];

        // Handle event
        match ($eventName) {
            'order.paid' => $this->handleOrderPaid($reference, $data),
            'order.pending_payment' => $this->handleOrderPendingPayment($reference, $data),
            'payment_link.completed' => $this->handlePaymentLinkCompleted($reference, $data),
            'payment_link.expired' => $this->handlePaymentLinkExpired($reference, $data),
            'payment_link.canceled' => $this->handlePaymentLinkCanceled($reference, $data),
            default => $this->logUnknownEvent($eventName),
        };

        http_response_code(200);
        echo 'OK';
    }

    private function verifySignature(string $payload, string $signature): bool
    {
        $expected = hash_hmac('sha256', $payload, $this->secret);
        return hash_equals($expected, $signature);
    }

    private function handleOrderPaid(string $reference, array $data): void
    {
        $this->orders->updateStatus($reference, 'paid');
        // Send confirmation email
        // Trigger fulfillment
    }

    private function handleOrderPendingPayment(string $reference, array $data): void
    {
        $this->orders->updateStatus($reference, 'awaiting_payment');
    }

    private function handlePaymentLinkCompleted(string $reference, array $data): void
    {
        // Log payment link completion
    }

    private function handlePaymentLinkExpired(string $reference, array $data): void
    {
        // Consider creating a new payment link
    }

    private function handlePaymentLinkCanceled(string $reference, array $data): void
    {
        // Log cancellation
    }

    private function logUnknownEvent(string $eventName): void
    {
        error_log("Unknown webhook event: $eventName");
    }
}