Webhook
X-Iyz-Signature ve X-Iyz-Signature-V2 artık desteklenmeyecektir. Kullanıcılarımızın sistemlerini X-Iyz-Signature-V3 ile uyumlu hale getirmelerini bekliyoruz.
iyzico, işlem tamamlandığında uygulamanızı bilgilendirmek için webhook kullanır. (Başarılı, Başarısız) Ödeme girişimi yapıldığında HTTP POST bildirimi ile işlem sonucunu almak mümkündür. İlk bildirim, ilk ödeme girişiminden 10-15 saniye sonra gönderilecektir. Bu bir JSON Yükü ve sunucudan sunucuya HTTP isteğidir. iyzico, sunucunuz "2xx" durumu ile yanıt verene kadar her 15 dakikada bir bildirim göndermeye devam edecek ve 3 defa tekrar edecektir.
iyzico'da webhook kullanımına yönelik opsiyonel olabilecek tüm ödeme metotları doğrudan sonuçlanmaktadır. Örneğin, başarılı bir ödeme talebinde, en son yanıt tüm ödeme ayrıntılarını içerir. Bununla birlikte, istenirse farklı mekanizmaları tetiklemek için webhook yine de kullanılabilir.
Header'da "X-IYZ-SIGNATURE-V3" değerinin gönderilebilmesi için, hesabınız üzerinde webhook signature özelliğinin aktif olması gerekmektedir. Bu özelliğin aktif edilmesi için, [email protected] adresi ile iletişime geçebilirsiniz.
Webhook nasıl etkinleştirilir?
iyzico Merchant Panel'e giriş yaptıktan sonra "Ayarlar > Firma Ayarları" adımında "İşyeri Bildirimleri" başlığından yapabilirsiniz. (HTTPS URL gereklidir)

Webhook Formları
Webhook istekleri 3 farklı formatta olabilir.
Direct Format
HPP(Hosted Payment Page) Format
Abonelik
Direkt Format
Aşağıdaki webhook formatı, NON-3DS ve 3DS ödeme taleplerinde görünür.
paymentConversationId
string
İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
merchantId
string
Merchant'ın iyzico tarafından atanmış ID numarası.
paymentId
string
İlgili ödemenin paymentId bilgisi
status
string
Ödeme durumu. Alabileceği değerler: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_CONTACTLESS
iyziReferenceCode
string
İstek için üretilen unique iyzico referans kodu
iyziEventType
string
İstek tipini belirtir. Alabileceği değerler:
PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND
iyziEventTime
long
Notification oluşturulma zamanının unix timestamp değeridir.
iyziPaymentId
long
Ödemeye ait ilgili paymentId.
HPP Format
Yukarıdakine benzer şekilde, bir sonraki webhook formatı, iyzico ile Öde, Ödeme Formu ve Tokenize Cüzdan Ödemesi olan barındırılan sayfa çözümlerinde görünür.
paymentConversationId
string
İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
merchantId
string
Merchant'ın iyzico tarafından atanmış ID numarası.
token
string
Ödeme formu için üretilmiş ve ödeme detaylarını içeren token değeri
status
string
Ödeme durumu. Alabileceği değerler: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_BANK_TRANSFER, INIT_CREDIT, PENDING_CREDIT, INIT_CONTACTLESS
iyziReferenceCode
string
İstek için üretilen unique iyzico referans kodu
iyziEventType
string
İstek tipini belirtir. Alabileceği değerler: CHECKOUT_FORM_AUTH, BANK_TRANSFER_AUTH, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND, CREDIT_PAYMENT_AUTH, CREDIT_PAYMENT_PENDING,CREDIT_PAYMENT_INIT,
PWI_TKN_FUND,
PWI_TKN_AUTH,
PWI_TKN_THREEDS_AUTH
iyziEventTime
long
Notification oluşturulma zamanının unix timestamp değeridir.
iyziPaymentId
long
Ödemeye ait ilgili paymentId.
Abonelik Bildirimleri
Abonelik özelliğinde, abonelik başlatıldıktan sonra, yalnızca ilk işlem için değil, plan kapsamında düzenli olarak tahsil edilecek ödemeler için de webhook bildirimi alabilirsiniz.
Tekrarlayanan ödemelerin durumunu, iyzico kontrol paneline giriş yaptıktan sonra "Ayarlar > Firma Ayarları > İşyeri Bildirimleri" sekmesinde bulunan abonelik bildirim alanına tanımlayacağınız bir URL ile öğrenebilirsiniz.

Başarılı ve başarısız işlemlere dair örnek abonelik bildirimleri aşağıdaki gibidir.
Başarılı
{
"orderReferenceCode": "ae5fcbf8-4fd2-46e5-b199-8f690ae9fae5",
"customerReferenceCode": "ff4052ca-0588-40eb-81a9-848c0c409472",
"subscriptionReferenceCode": "ea0362e2-a1c4-4fda-89f0-3758a5c20a28",
"iyziReferenceCode": "18d7cc48-a64b-4cd3-ae68-71aff1c76ed9",
"iyziEventType": "subscription.order.success",
"iyziEventTime": 1758704403161
}Başarısız
{
"orderReferenceCode": "9ed2d128-b106-464b-8170-84325e75703b",
"customerReferenceCode": "042f0b61-079a-4a38-9454-6564a3c11a5a",
"subscriptionReferenceCode": "b0f6d38f-b2d1-4a72-9bf2-bc9375665f3a",
"iyziReferenceCode": "aac139a9-43db-4f40-82dd-d4e5a77a3d2e",
"iyziEventType": "subscription.order.failure",
"iyziEventTime": 1579612261619
}Abonelik Bildirim Parametreleri
orderReferenceCode
String
İlgili ödeme denemesine ait referans kodu. Başarısız işlemler için retry işleminde kullanılır.
customerReferenceCode
String
Müşteriye ait referans kodu.
subscriptionReferenceCode
String
Abonelik referans kodu.
iyziReferenceCode
String
İstek için üretilen unique iyzico referans kodu.
iyziEventType
String
İstek tipini belirtir. Alabileceği değerler:
"subscription.order.success",
"subscription.order.failure"
iyziEventTime
Long
Notification oluşturulma zamanının unix timestamp değeridir.
Notifikasyon Validasyonu
İsteğin iyzico üzerinden geldiğini valide etmek için header içinde gönderilen X-IYZ-SIGNATURE-V3değeri kullanılabilir ve bu değer yalnızca sahip olduğunuz SECRET KEY ile çözülebilir.
X-Iyz-Signature ve X-Iyz-Signature-V2 artık desteklenmeyecektir. Kullanıcılarımızın sistemlerini X-Iyz-Signature-V3 ile uyumlu hale getirmelerini bekliyoruz.
Direkt Formatın Doğrulanması
SECRET KEY, iyziEventType, paymentId, paymentConversationId, status aşağıda verilen sıraya göre oluşturulmalıdır. Bu dizi HMACSHA256 ile hashlenir ve sonuç HEX ile şifrelenir. Son değer, başlıktaki X-IYZ-SIGNATURE-V3 ile eşleşmelidir.
// HMAC için Key oluşturulur
const key = secretKey + iyziEventType + paymentId + paymentConversationId + status;
// HMAC SHA256 ile signature üretilir
const hmac256 = crypto.createHmac('sha256', secretKey)
.update(key)
.digest('hex');1
secretKey
Sahip olduğunuz secretKey
2
iyziEventType
İstek tipini belirtir. Alabileceği değerler:
PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND
3
paymentId
İlgili ödemenin paymentId bilgisi
4
paymentConversationId
İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
5
status
Ödeme durumu. Alabileceği değerler: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_CONTACTLESS
HPP Format
SECRET KEY, iyziEventType, iyziPaymentId, token, paymentConversationId, status aşağıda verilen sıraya göre oluşturulmalıdır. Bu dizi HMACSHA256 ile hashlenir ve sonuç HEX ile şifrelenir. Son değer, başlıktaki X-IYZ-SIGNATURE-V3 ile eşleşmelidir.
// HMAC için Key oluşturulur
const key = secretKey + iyziEventType + iyziPaymentId + token + paymentConversationId + status;
// HMAC SHA256 ile signature üretilir
const hmac256 = crypto.createHmac('sha256', secretKey)
.update(key)
.digest('hex');1
secretKey
Sahip olduğunuz secretKey.
2
iyziEventType
İstek tipini belirtir. Alabileceği değerler: CHECKOUT_FORM_AUTH, BANK_TRANSFER_AUTH, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND, CREDIT_PAYMENT_AUTH, CREDIT_PAYMENT_PENDING,CREDIT_PAYMENT_INIT,
PWI_TKN_FUND,
PWI_TKN_AUTH,
PWI_TKN_THREEDS_AUTH
3
iyziPaymentId
Ödemeye ait ilgili paymentId.
4
token
Ödeme formu için üretilmiş ve ödeme detaylarını içeren token değeri
5
paymentConversationId
İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
6
status
Ödeme durumu. Alabileceği değerler: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_BANK_TRANSFER, INIT_CREDIT, PENDING_CREDIT, INIT_CONTACTLESS
Abonelik Bildirimlerinin Doğrulanması
SECRET KEY, merchantId, eventType, subscriptionReferenceCode, orderReferenceCode ve customerReferenceCode aşağıda verilen sıraya göre oluşturulmalıdır. Bu dizi HMACSHA256 ile hashlenir ve sonuç HEX ile şifrelenir. Son değer, başlıktaki X-IYZ-SIGNATURE-V3 ile eşleşmelidir.
// HMAC için Key (message) oluşturulur
const key = merchantId
+ secretKey
+ eventType
+ subscriptionReferenceCode
+ orderReferenceCode
+ customerReferenceCode;
// HMAC SHA256 ile hex formatında signature üretilir
const hmac256 = crypto.createHmac('sha256', secretKey)
.update(key)
.digest('hex');
<?php
$merchantId = "merchantId";
$secretKey = "secretKey";
$eventType = "eventType_from_webhook_payload";
$subscriptionReferenceCode = "subscriptionReferenceCode_from_webhook_payload";
$orderReferenceCode = "orderReferenceCode_from_webhook_payload";
$customerReferenceCode = "customerReferenceCode_from_webhook_payload";
// message = merchantId + secretKey + eventType + subReferenceCode + orderReferenceCode + customerReferenceCode
$message = $merchantId
. $secretKey
. $eventType
. $subscriptionReferenceCode
. $orderReferenceCode
. $customerReferenceCode;
// HMAC-SHA256 raw → hex
$hmac256Signature = bin2hex(hash_hmac('sha256', $message, $secretKey, true));
$signature_v3 = "signature_v3_from_webhook_header";
if ($hmac256Signature == $signature_v3) {
echo "İmza doğrulaması başarılı.";
} else {
echo "İmza doğrulaması başarısız.";
}
?>import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
public class WebhookSignatureCheck {
public static void main(String[] args) throws Exception {
String merchantId = "merchantId";
String secretKey = "secretKey";
String eventType = "eventType_from_webhook_payload";
String subscriptionReferenceCode = "subscriptionReferenceCode_from_webhook_payload";
String orderReferenceCode = "orderReferenceCode_from_webhook_payload";
String customerReferenceCode = "customerReferenceCode_from_webhook_payload";
// message = merchantId + secretKey + eventType + subscriptionReferenceCode + orderReferenceCode + customerReferenceCode
String message = merchantId
+ secretKey
+ eventType
+ subscriptionReferenceCode
+ orderReferenceCode
+ customerReferenceCode;
// HMAC-SHA256 raw → hex
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256_HMAC.init(secret_key);
byte[] hashBytes = sha256_HMAC.doFinal(message.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder();
for (byte b : hashBytes) {
sb.append(String.format("%02x", b));
}
String hmac256Signature = sb.toString();
String signature_v3 = "signature_v3_from_webhook_header";
if (hmac256Signature.equals(signature_v3)) {
System.out.println("İmza doğrulaması başarılı.");
} else {
System.out.println("İmza doğrulaması başarısız.");
}
}
}
const crypto = require("crypto");
const merchantId = "merchantId";
const secretKey = "secretKey";
const eventType = "eventType_from_webhook_payload";
const subscriptionReferenceCode = "subscriptionReferenceCode_from_webhook_payload";
const orderReferenceCode = "orderReferenceCode_from_webhook_payload";
const customerReferenceCode = "customerReferenceCode_from_webhook_payload";
// message = merchantId + secretKey + eventType + subscriptionReferenceCode + orderReferenceCode + customerReferenceCode
const message = merchantId
+ secretKey
+ eventType
+ subscriptionReferenceCode
+ orderReferenceCode
+ customerReferenceCode;
// HMAC-SHA256 raw → hex
const hmac256Signature = crypto.createHmac("sha256", secretKey)
.update(message)
.digest("hex");
const signature_v3 = "signature_v3_from_webhook_header";
if (hmac256Signature === signature_v3) {
console.log("İmza doğrulaması başarılı.");
} else {
console.log("İmza doğrulaması başarısız.");
}
Last updated
