Webhook teknik ayrıntılar

Finekstra, işyerine tanımlı URL’ye sunucudan sunucuya HTTPS POST ile ödeme olayları iletir. Gövde JSON’dur; her finansal işlemde gövdedeki değerler ve gizli anahtarla hash doğrulaması yapılır.

Olay türleri (örnek)

Kod tabanında kullanılan bazı event değerleri:

Olay	Ne zaman
`payment.approved`	Tahsilat onaylandı
`payment.pending_capture`	Ön provizyon onaylandı, tahsilat bekleniyor
`payment.declined`	Banka reddi
`payment.failed`	Teknik veya genel başarısızlık
`payment.fraud_declined`	Risk kuralları
`payment.captured`	Tahsilat tamamlandı
`payment.capture_failed`	Tahsilat başarısız
`payment.refund`	İade işlemi
`payment.void`	İptal işlemi

Not: Liste zaman içinde genişleyebilir.

Gövde alanları (özet)

Payload örneği şu alanları içerir: event, transaction_id, merchant_id, status, amount, principal_amount, buyer_cost_amount, currency, reference_no, bank_id, fraud_flag, transaction_type, isteğe bağlı original_transaction_id, reversal_state, vb.

İmza

İmza, payload'ın hash alanı eklenmeden önce yalnızca aşağıdaki alanlarla hesaplanır:

event

transaction_id

merchant_id

status

amount

currency

transaction_type

Alan sırası yukarıdaki sırayla sabittir.

Canonical string, | ayırıcı ile şu formatta üretilir:
{event}|{transaction_id}|{merchant_id}|{status}|{amount}|{currency}|{transaction_type}

Paylaşılan sır ile HMAC-SHA256 hesaplanır (sign_payload).

Hesaplanan değer:

Header'da: X-Webhook-Signature

Gövdede: hash alanı

İstemci tarafı doğrulamada, yine aynı alanlar + aynı sıra ile HMAC üretip karşılaştırmalıdır.

Python doğrulama örneği

Üretim ortamında webhook secret’ını işyeri panelinden veya operasyon ekibinden alın.

Yinelenen bildirimler

Ağ tekrarlarında aynı olay iki kez gelebilir. İşlem kimliği ve olay türü ile idempotent işleyiş uygulayın.

Webhook teknik ayrıntılar

Olay türleri (örnek)#

Gövde alanları (özet)#

İmza#

Python doğrulama örneği#

Yinelenen bildirimler#

Olay türleri (örnek)

Gövde alanları (özet)

İmza

Python doğrulama örneği

Yinelenen bildirimler