Ödeme Webhook'ları

Ödemeler durumlarını asenkron değiştirir: 3-D Secure doğrulaması yönlendirmeden dakikalar sonra tamamlanır, bir capture takasa girer, bir yetkilendirme gece süresi dolar, bir ters ibraz haftalar sonra gelir. Webhook'lar bu yaşam döngüsü değişikliklerinin her birini sunucunuza push eder — böylece GET /payments/:id endpoint'ini döngüde poll etmeniz gerekmez ve sipariş durumunuz ödeme durumundan sessizce kopamaz.

Ödeme eventleri

On beş event tipi ödeme yaşam döngüsünün tamamını kapsar; ödeme linklerinin dokuz yaşam döngüsü event'i aşağıda, senetle ödemenin senet event'leri ayrıca listelenir:

Tek bir ödeme yaşamı boyunca genellikle birden fazla event üretir — örneğin payment.authorized → payment.captured → aylar sonra payment.disputed.

Ödeme linki event'leri

Linkle Ödeme linklerinin yaşam döngüsü dokuz event üretir: 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.

Linkle alınan ödemeler yukarıdaki ödeme event'lerini üretir; bu event'lerin data'sına source: "PAYMENT_LINK", paymentLinkId, paymentLinkCode ve paymentLinkAttemptId alanları eklenir. Siparişi yine payment.captured ile teslim edin — payment.link.completed ikinci bir para sinyali değildir. Payload ve alanlar: Linkle Ödeme Webhook'ları.

Senet event'leri

Senetle Öde ile alınan ödeme, senetler düzenlendiğinde payment.captured üretir; tahsilat ise vadede, borçludan doğrudan sizin sağlayıcı hesabınıza yapılır. Her senedin vadedeki sonucu ayrı bir event'tir:

Bu event'ler senet ve durum başına bir kez gönderilir, ödemenin durumunu değiştirmez (status CAPTURED kalır) ve senedin alanlarını data.promissoryNote içinde taşır: serialNumber, sequence, amountMinor, dueDate, status, occurredAt. Senet durumları sağlayıcıdan düzenli aralıklarla okunur; event anlık değildir. Panelde bu event'ler Senetle Ödeme grubundadır. Payload ve okuma sıklığı: Senetle Öde — Webhook'lar.

Teslimat payload'u

Her teslimat, endpoint'inize şu şekilde bir JSON gövdeyle yapılan HTTP POST'tur:

{
  "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 her zaman intentId, merchantId, orderId, currency ve status taşır; buna yukarıdaki tabloda listelenen event'e özgü alanlar eklenir. data içindeki tutar alanları minor-unit string'dir ve çekilen tutarı gösterir: taksitli ödemede, isteğinizdeki amount'a (sepet toplamı) sistemin eklediği vade farkı dahildir.

Parçalı ödemenin ana ödeme ve payment.split.* event'lerinde data ayrıca splitPaymentId taşır. intentId yalnız Checkout Formu parçalı ödemesinin ana ödeme event'lerinde bulunur ve siparişin ödeme kaydıdır; API ile başlatılan parçalı ödemede ana ödemenin kimliği splitPaymentId'dir → Parçalı Ödeme › Olaylar.

Teslimat header'ları:

v2 imzası ham gövdenin HMAC'idir: HMAC-SHA256(secret, eventId + "." + timestamp + "." + rawBody) — parse yok, yeniden serileştirme yok. Başlık bir veya iki v2= öğesi taşır; ikincisi yalnız secret rotasyonunun 24 saatlik grace penceresinde bulunur. Doğrulama kodu ve detaylar: Webhook kurulumu.

Teslimat modeli

Teslimatlar platform genelindeki webhook sözleşmesine uyar (detaylar Webhook kurulumu sayfasında):

• İmzalı — her teslimat, endpoint'inizin webhook secret'ıyla hesaplanan x-lunixi-signature header'ını taşır. Gövdeye güvenmeden önce imzayı doğrulayın; doğrulamayı geçemeyen teslimatları reddedin.
• Retry'lı — endpoint'iniz 2xx dönmezse teslimat backoff ile tekrar denenir. Handler'ınızı hızlı tasarlayın: önce onaylayın, işlemeyi asenkron yapın.
• At-least-once — retry'lar aynı eventi birden fazla kez görebileceğiniz anlamına gelir. Handler'ları idempotent yapın: işlemeyi event id'sine (ya da (paymentId, event) çiftine) anahtarlayın ve tekrarları yok sayın.
• Sırasız — eventlerin gerçekleşme sırasıyla geleceğini varsaymayın. Mantığınızı event geliş sırasından değil, ödemenin güncel status değerinden yürütün (şüphedeyseniz GET /payments/:id ile teyit edin).

Bir eventi işleme

Webhook ile 3-D Secure callback'inin farkı

3-D Secure akışını kullanıyorsanız, doğrulama bittiğinde alıcının tarayıcısı da callback URL'inize geri POST edilir — _signature ve _timestamp alanlarını taşıyan HMAC-imzalı bir form POST.

Bu iki kanalın görevleri farklıdır:

Hatalar & operasyonel notlar

Sonraki adımlar

• Webhook kurulumu — endpoint'ler, secret'lar, kodda imza doğrulama
• Ödemeleri Listeleme — mutabakat için pull-tabanlı tamamlayıcı
• Ters İbraz — payment.disputed sonrasında ne yapmalı
• Kart — 3D Secure — merchant callback'ini üreten akış