POS API / Events

Webhooks

Receive real-time notifications when POS order events occur.

How Webhooks Work

When you create an order with a callback_url, Quickei sends an HTTP POST request to that URL whenever the order status changes. The payload is JSON-encoded and includes a signature header for verification.

POST Your callback_url | Content-Type: application/json

Signature Verification

Every webhook includes an X-Quickei-Signature header containing an HMAC-SHA256 signature of the request body, signed with your client_secret.

// Header
X-Quickei-Signature: sha256=HMAC_SHA256(payload, client_secret)

Events

Event	Trigger
`pos.order.paid`	Customer completed payment
`pos.order.expired`	Order expired before payment
`pos.order.cancelled`	Order cancelled by merchant
`pos.order.refunded`	Payment refunded to customer

Example Payload

{
  "event": "pos.order.paid",
  "timestamp": "2024-01-15T14:02:30+00:00",
  "data": {
    "order_id": "POS-20240115-A1B2C3",
    "amount": 25.00,
    "currency": "EUR",
    "status": "PAID",
    "reference": "INV-2024-001",
    "terminal_id": "terminal-01",
    "trx_id": "TRX-98765",
    "paid_at": "2024-01-15T14:02:30+00:00"
  }
}

PHP Verification Example

// Verify webhook signature
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_QUICKEI_SIGNATURE'];

$expected = 'sha256=' . hash_hmac(
    'sha256',
    $payload,
    $client_secret
);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
// Process the event...

Best practice: Always verify the signature before processing webhook events. Return a 200 status code quickly to acknowledge receipt — do heavy processing asynchronously.

Terminals Payment Page