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.

Parametre

Type

Açıklama

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.

Parametre

Type

Açıklama

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

Parametre

Tip

Açıklama

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.

Direkt format için Hashing Örneği

// 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');

Sıralama

Parametre

Açıklama

secretKey

Sahip olduğunuz secretKey

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

paymentId

İlgili ödemenin paymentId bilgisi

paymentConversationId

İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası

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.

HPP format için Hashing Örneği

// 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');

Sıralama

Paremetre

Açıklama

secretKey

Sahip olduğunuz secretKey.

iyziEventType

PWI_TKN_FUND,

PWI_TKN_AUTH,

PWI_TKN_THREEDS_AUTH

iyziPaymentId

Ödemeye ait ilgili paymentId.

token

Ödeme formu için üretilmiş ve ödeme detaylarını içeren token değeri

paymentConversationId

İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası

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 26 days ago