Payment Webhooks

Payments change state asynchronously: a 3-D Secure challenge completes minutes after the redirect, a capture settles, an authorization expires overnight, a chargeback arrives weeks later. Webhooks push every one of these lifecycle changes to your server so you never have to poll GET /payments/:id in a loop — and so your order state can never silently drift from the payment state.

Payment events

Fifteen event types cover the full payment lifecycle; the nine payment link lifecycle events are listed separately below, and the promissory-note events separately:

A single payment typically produces several events over its life — for example payment.authorized → payment.captured → months later payment.disputed.

Payment link events

Payment Links produce nine lifecycle events: payment.link.created, payment.link.updated, payment.link.paused, payment.link.resumed, payment.link.deactivated, payment.link.expired, payment.link.completed, payment.link.taken_down, payment.link.takedown_reverted.

Payments taken through a link produce the payment events above; source: "PAYMENT_LINK", paymentLinkId, paymentLinkCode and paymentLinkAttemptId are added to their data. Still fulfil the order on payment.captured — payment.link.completed is not a second money signal. Payload and fields: Payment Link Webhooks.

Promissory-note events

A payment taken with Promissory Notes produces payment.captured when the notes are issued; the money is collected at maturity, directly from the debtor into your provider account. The outcome of each note at maturity is a separate event:

These events are sent once per note and status, do not change the payment's status (status stays CAPTURED) and carry the note's fields in data.promissoryNote: serialNumber, sequence, amountMinor, dueDate, status, occurredAt. Note statuses are read from the provider at regular intervals; the events are not real time. In the panel these events are in the Senetle Ödeme (Promissory Notes) group. Payload and read frequency: Promissory Notes — Webhooks.

Delivery payload

Every delivery is an HTTP POST to your endpoint with a JSON body of this shape:

{
  "id": "6a1f0c9e-2b3d-5e4f-8a7b-1c2d3e4f5a6b",
  "type": "payment.captured",
  "sourceService": "payment-service",
  "organizationId": "org_…",
  "productCode": "PAYMENT_GATEWAY",
  "environment": "LIVE",
  "eventVersion": 1,
  "schemaVersion": "v1",
  "createdAt": "2026-07-06T12:00:02.000Z",
  "data": {
    "intentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "merchantId": "m_…",
    "orderId": "ORD-84722",
    "currency": "TRY",
    "status": "CAPTURED",
    "capturedAmountMinor": "10050"
  }
}

data always carries intentId, merchantId, orderId, currency and status, plus the event-specific fields listed in the table above. Amount fields inside data are minor-unit strings and show the charged amount: for an installment payment they include the installment fee the system added to the amount (basket total) in your request.

In the main payment events and the payment.split.* events of a split payment, data also carries splitPaymentId. intentId is present only in the main payment events of a Checkout Form split payment, where it is the order's payment record; for a split payment started from the API the main payment's id is splitPaymentId → Split Payments › Events.

Delivery headers:

The v2 signature is an HMAC of the raw body: HMAC-SHA256(secret, eventId + "." + timestamp + "." + rawBody) — no parsing, no re-serialisation. The header carries one or two v2= items; the second one is present only during the 24-hour secret-rotation grace window. Verification code and details: Webhook setup.

Delivery model

Deliveries follow the platform-wide webhook contract (details in Webhook setup):

• Signed — every delivery carries the x-lunixi-signature header computed with your endpoint's webhook secret. Verify it before trusting the body; reject deliveries that fail verification.
• Retried — if your endpoint does not answer with a 2xx, delivery is retried with backoff. Design your handler to be fast: acknowledge first, process asynchronously.
• At-least-once — retries mean you may see the same event more than once. Make handlers idempotent: key your processing on the event id (or the (paymentId, event) pair) and ignore duplicates.
• Unordered — do not assume events arrive in the order they occurred. Drive your logic from the payment's current status (confirm with GET /payments/:id if in doubt), not from event arrival order.

Handling an event

Webhook vs the 3-D Secure callback

If you use the 3-D Secure flow, the buyer's browser is also POSTed back to your callback URL when the challenge finishes — an HMAC-signed form POST carrying _signature and _timestamp fields.

These two channels have different jobs:

Errors & operational notes

Next steps

• Webhook setup — endpoints, secrets, signature verification in code
• Listing Payments — the pull-based complement for reconciliation
• Chargebacks — what to do after payment.disputed
• Card — 3D Secure — the flow that produces the merchant callback