Webhooks

Websitenizde veya uygulamanızda bir ödeme denemesi yapıldığında işlem sonucunu notification ile almanız mümkün. iyzico her ödeme eventi için işlemden 15 saniye sonra HTTP üzerinden JSON Payload gönderir. Bu istek, uygulamanızdan 200 cevabı alınmadığı müddetçe 15 dakikada bir 24 saat boyunca tekrarlanır.

iyzico ortamında API üzerinden gelen none-secure ödeme ve 3ds ödeme tamamlama (3ds-auth) isteklerinde anında ve doğrudan sonuç alınır. Örneğin, başarılı bir ödeme isteğinde karttan para çekilir ve dönen cevapta ödeme detaylarının tümü alınır. Bu tür isteklerde anahtar bilgiler zaten mevcut olduğundan webhook kullanımı gerekli değildir ancak yine de webhook ile farklı mekanizmalar harekete geçirilebilir.

iyzico ödeme formu üzerinden alınan ödemelerde, ödeme sonucunu browser üzerinden iletildiğinden kullanıcı/browser veya server dalgalanmaları sebebiyle yakalanamayan ödemeler webhook çözümü ile yakalanabilir. Hesabınız için webhook açıldığında sistem belirttiğiniz url'e token ve ödeme durumunu ayrıca gönderir. Browser üzerinden gelen token bilgisine erişilemediğinde notification ile alınan token bilgisi sisteme işlenebilir. Eğer browser üzerinden gönderilen token yakalanıp işlendiyse, notification dikkate alınmayabilir. Ödeme formunda başarısız işlemlerin hata mesajları(3ds hariç ödemeler hariç) yönlendirmme yapılmadan, ödemme formu üzerinde gösterilir. Bu hatalı işlemlerden ilki için notifikasyon gönderilir ve payload içinde ödeme durumu başarısızdır. Kullanıcı aynı form üzerinde tekrar deneyip başarılı ödeme yaparsa bu bilgi de notifikasyon olarak gönderilmektedir.

Webhook çözümü ayrıca analiz, uyarı ve raporlama gibi servislerinizi harekete geçirmek için kullanılabilir.

API AUTH ve 3DS AUTH İÇİN GÖNDERİLEN İSTEK

Üye işyerinin belirlediği adrese gönderilecek istek parametreleri aşağıdadır.

Parametre ismi Tip Açıklama
iyziEventTime long Notification oluşturulma zamanının unix timestamp değeridir.
iyziEventType string İstek tipini belirtir. Alabileceği değerler API_AUTH, THREE_DS_AUTH, BKM_AUTH
iyziReferenceCode string İstek için üretilen unique iyzico referans kodu
paymentId long İlgili ödemenin paymentId bilgisi
paymentConversationId string İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
status string Ödeme durumu. Alabileceği değerler: SUCCESS, FAILED

ÖDEME FORMU VE BANKA TRANSFERİ İÇİN GÖNDERİLEN İSTEK

Üye işyerinin belirlediği adrese gönderilecek istek parametreleri aşağıdadır.

Parametre ismi Tip Açıklama
iyziEventTime long Notification oluşturulma zamanının unix timestamp değeridir.
iyziEventType string İstek tipini belirtir. Alabileceği değerler API_AUTH, THREE_DS_AUTH, BKM_AUTH
iyziReferenceCode string İstek için üretilen unique iyzico referans kodu
token string Ödeme formu için üretilmiş ve ödeme detaylarını içeren token değeri
status string Ödeme durumu. Alabileceği değerler: SUCCESS, FAILED

NOTİFİKASYON VALİDASYONU

İsteğin iyzico üzerinden geldiğini valide etmek için header içinde gönderilen "X-IYZ-SIGNATURE" değeri kullanılabilir.

X-IYZ-SIGNATURE değeri aşağıdaki parametrelerin verilen sırada string olarak birleştirilip hashlenmesi sonucu elde edilir.

API AUTH ve 3DS AUTH İÇİN VALİDASYON

Sahip olduğunuz Secret Key, notifikasyon ile gönderilen eventType ve paymentId bilgileri string olarak birleştirilerek Sha1 ile hashlenir. Alınan sonucun base 64 econde çıktısı X-IYZ-SIGNATURE değerine eşit olmalıdır.

Sıralama Parametre Açıklama
1 secretKey Üye işyerinin sahip olduğu güvenlik anahtarı
2 iyziEventType İstek tipini belirtir. Alabileceği değerler API_AUTH, THREE_DS_AUTH, BKM_AUTH
3 paymentId İlgili ödemenin paymentId bilgisi
final String stringToBeHashed = new StringBuilder("secretKey")
                .append(request.getIyziEventType())
                .append(request.getPaymentId())
                .toString();


Oluşturulan string base 64 encode olarak formatlanır.
String hash = Base64.encodeBase64String(DigestUtils.sha1(stringToBeHashed));

ÖDEME FORMU VE BANKA TRANSFERİ İÇİN VALİDASYON

Sahip olduğunuz Secret Key, notifikasyon ile gönderilen eventType ve token bilgileri string olarak birleştirilerek Sha1 ile hashlenir. Alınan sonucun base 64 econde çıktısı X-IYZ-SIGNATURE değerine eşit olmalıdır.

Sıralama Parametre Açıklama
1 secretKey Üye işyerinin sahip olduğu güvenlik anahtarı
2 iyziEventType İstek tipini belirtir. Alabileceği değerler API_AUTH, THREE_DS_AUTH, BKM_AUTH
3 token İlgili ödeme için üretilmiş token bilgisi
final String stringToBeHashed = new StringBuilder("secretKey")
                .append(request.getIyziEventType())
                .append(request.getToken())
                .toString();


Oluşturulan string base 64 encode olarak formatlanır.
String hash = Base64.encodeBase64String(DigestUtils.sha1(stringToBeHashed));

Webhook aktifleştirilmesi

Notifikasyon almak için iyzico panelinde sol menüden Ayarlar -> Üye İşyeri Ayarları'na girilir. İşyeri Bildirimleri kısmında İşyeri Bildirimleri Url alanına notifikasyon almak istediğiniz URL girilir. Ödeme bildirimleri gönderme tuşu aktif edilir.