Webhooks

Webhooks are how Paymee tells your server the authoritative outcome of a payment. Always fulfil orders from a webhook, not from the browser redirect.

Paymee POSTs a JSON body to the webhook_url you set on the session (or your account default), signed with the X-Paymee-Signature header.

Events

Event	When	Act on it?
session.succeeded	The payment completed. Session is now SUCCEEDED (terminal).	Yes — fulfil the order.
session.failed	A payment attempt was declined. Carries can_retry; the session is only dead once it reaches FAILED (terminal).	When can_retry is false.
session.expired	The payment session hit its ~24 h TTL without completing → now EXPIRED (terminal). The order will never be paid.	Yes — release the order.
checkout.session.expired	One hosted-page link hit its short TTL (~30 min). The payment session itself is unaffected and may still be paid.	No — informational.

“session” vs “checkout session” — they’re different objects

session.expired and checkout.session.expired look alike but fire on different objects, with different TTLs and different consequences:

• session.expired → the payment. This is the PaymentSession you created with POST /gateway/sessions/. It has a long TTL (~24 h) and the full status lifecycle. On expiry it becomes EXPIRED, a terminal state — the order can never be paid. Act on it: release stock, mark the order abandoned.
• checkout.session.expired → one hosted-page link. The link you redirect each buyer to is a separate, short-lived object (~30 min); a single payment session can hand out several. When a link goes stale it is closed and any attempt on it is marked abandoned, but the payment session stays open and keeps its own ~24 h clock. Don’t end the order on it — it just means the buyer walked away from that link.

Because the link’s ~30-minute clock is far shorter than the session’s ~24 h, a buyer who opens checkout and disappears typically triggers checkout.session.expired first, then session.expired hours later — so an abandoned payment can produce both. Drive fulfilment off the session.* events (the authoritative payment lifecycle); treat checkout.session.expired as a UX/analytics signal. Most integrations subscribe to session.succeeded, session.failed, and session.expired and ignore checkout.session.expired entirely.

Recovering an abandoned payment

Both expiry events are a cue to re-engage the buyer — usually by emailing or SMSing them a fresh link. You don’t need a separate “create link” endpoint: recovery is just another call to POST /sessions/, which is idempotent on merchant_reference.

• After checkout.session.expired (the link lapsed, the payment is still alive) — call POST /sessions/ again with the same merchant_reference. You get the same payment session back with a fresh checkout_url: the link is re-minted automatically when the previous one has expired. Send that URL to the buyer.
• After session.expired (the whole payment is terminal) — replaying the same merchant_reference returns the session without a checkout_url (there’s nothing left to pay). To recover, create a new payment with a new merchant_reference — that mints a brand-new session and link. Send that.

A checkout_url carries the short (~30 min) link TTL, so send it promptly; if the buyer clicks after it lapses, just call POST /sessions/ again to mint another.

Payload

Every delivery has the same envelope; data carries the session, and some events add fields.

{
  "id": "evt_9f2c…",
  "event": "session.succeeded",
  "created_at": "2026-06-27T10:24:00Z",
  "data": {
    "id": "ps_3Nk8x2c9aQ...",
    "order_number": "PM-014A2C",
    "merchant_reference": "order-0001",
    "order_id": "",
    "amount": "10.500",
    "currency": "TND",
    "description": "",
    "status": "SUCCEEDED",
    "buyer": {
      "first_name": "Aymen",
      "last_name": "Ben Salah",
      "email": "aymen@example.com",
      "phone": ""
    },
    "items": [],
    "metadata": {},
    "paid_at": "2026-06-27T10:24:00Z",
    "payment": {
      "method": "card",
      "card_brand": "VISA",
      "card_last_four": "1119",
      "card_country": "TN",
      "fee_amount": "0.300",
      "net_amount": "10.200"
    }
  }
}

• session.succeeded adds paid_at and a payment block.
• session.failed adds last_failure_code, last_failure_message, attempts_count, and can_retry.

Verify the signature

Every request includes these headers:

Header	Purpose
X-Paymee-Signature	t=<timestamp>,v1=<hex> — the HMAC to verify.
X-Paymee-Webhook-Id	Stable event id, identical across retries — use it to deduplicate.
X-Paymee-Event	The event type (e.g. session.succeeded).

The signature is computed as:

signed_payload = "<timestamp>.<raw_request_body>"
expected       = HMAC_SHA256(signed_payload, your_webhook_secret)   // whsec_…

Compare expected to the v1= value using a constant-time comparison.

Caution

Verify against the raw request body bytes, before any JSON re-serialization. Re-encoding the parsed JSON will change the bytes and break the signature.

Python

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    # header looks like: "t=1719481440,v1=abcdef..."
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp, sig = parts["t"], parts["v1"]
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Node.js

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const signed = Buffer.concat([
    Buffer.from(`${parts.t}.`),
    Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody),
  ]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1),
  );
}

PHP

<?php
function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(",", "&", $header), $parts); // t=..., v1=...
    $signed = $parts["t"] . "." . $rawBody;
    $expected = hash_hmac("sha256", $signed, $secret);
    return hash_equals($expected, $parts["v1"]);
}

Responding & retries

1. Return 2xx quickly. Acknowledge within a few seconds, then do heavy work asynchronously. Deliveries time out after 10 seconds; a non-2xx, a timeout, or a connection error is treated as a failed delivery.

2. Make your handler idempotent. Deliveries are at-least-once — a retry (or an occasional duplicate) can arrive even after you already processed the event. Deduplicate on X-Paymee-Webhook-Id (it is stable across retries): record processed ids and make fulfilment safe to run twice, so a repeat delivery never double-ships an order or double-credits a balance.

3. Retries. Failed deliveries are retried up to three times, after approximately 1 minute, 2 hours, and 24 hours.

Idempotency is required, not optional

Because Paymee retries on any non-2xx/timeout and may redeliver, your endpoint will occasionally receive the same event more than once. Treat X-Paymee-Webhook-Id as the idempotency key and guard every side effect behind it — this is the single most important rule for a correct webhook handler.

You can inspect delivery history for a session via GET /gateway/sessions/{id}/webhooks/, or across the account via GET /gateway/webhooks/.

Manually resending

If all automatic retries are exhausted (or your endpoint was misconfigured at the time), you can resend a delivery from your Paymee dashboard — open Settings → Developers, find the event in the webhook logs, and choose Resend. A resend re-signs the payload with your current webhook secret and reuses the same X-Paymee-Webhook-Id, so an idempotent handler treats it as the same event.

Coming from Paymee v1/v2?

The legacy check_sum = md5(token + payment_status + API_Token) is replaced by the HMAC-SHA256 X-Paymee-Signature above, using a dedicated whsec_… secret (separate from your API key).