Ön Provizyon Entegrasyonu

Önemli: BKM kurallarına göre 25 gün içerisinde provizyon kapama işlemlerinin gerçekleştirilmesi gerekmektedir. Bu süre zarfında finansallaştırılmayan işlemlerde, otomatik olarak bloke kaldırılmaktadır.

Ön provizyon süreleri, marjlı kapama limitleri ve işlem kuralları bankadan bankaya değişebilir.

Debit kartlarla ön provizyon işlemi yapılmamaktadır.

Ön provizyon işlemlerinde iptal ve iade işlemleri bankalara göre değişkenlik göstermektedir.

Entegrasyon ve operasyonel talepleriniz için [email protected] adresiyle veya hesap yöneticinizle iletişime geçebilirsiniz.

Anahtar Tanımlar ve Entegrasyon Adımları

1. Provizyon Başlatma (preAuth)

• Tanım: Ön provizyon işlemi, karttan belirli bir tutarın bloke edilmesi işlemidir. Henüz para işyerinin hesabına geçmez, sadece kart sahibinin limitinden düşer.

• Amaç:

  • Kart limitinin müsait olup olmadığını kontrol etmek.

  • İşlemin ileride netleşecek kesin tutarı için güvence almak (ör. otel, araç kiralama, rezervasyon vb.)

• Özellikler:

  • İşlem “yetki alma (authorization)” statüsünde kalır, satışa dönüşmez.

  • Kart sahibi ekstresinde “provizyon” veya “bekleyen işlem” olarak görünür.

• Örnek Senaryolar:

  • Otel check-in sırasında depozito almak.

  • Araç kiralama firmasında güvence bedeli.

  • Şarj işlemi için uygulanacak bloke.

• Teknik Detay:

  • iyzico API’de preAuth servisi kullanılır.

  • Başarılı yanıt → status: success ,paymentId ve "phase": "PRE_AUTH" olarak döner.

  • Sonraki adımda bu paymentId kullanılacaktır.

2. Provizyon Kapama (postAuth)

• Tanım: Daha önce alınan preAuth işleminin, kısmen veya tamamen tahsil edilmesi işlemidir. Karttan bloke edilen tutar bu aşamada tahsil edilmektedir.

• Amaç:

  • Kesinleşen tutarın tahsil edilmesi

  • Müşteri kart ekstresine işlem kalıcı olarak yansır

• Özellikler:

  • Kapama, preAuth tutarından aynı, daha düşük veya bazı durumlarda daha yüksek bir tutarla yapılabilir. Buna marjlı kapama denir.

  • Bazı issuer bankalar, tutarın değişmesine izin vermez.

  • Kapama yapılmazsa → provizyon belirli süre sonra otomatik düşer ve para iş yerine geçmez.

• Örnek Senaryolar:

  • Otele girişte bloke edilen 3.000 TL, çıkışta 2.500 TL olarak tahsil edilir.

  • Araç kiralamada hasar çıkmadığı için bloke edilen 5.000 TL’nin sadece 3.000 TL’si tahsil edilir.

• Teknik Detay:

  • iyzico API’de postAuth servisi çağrılır → paymentId parametresi zorunludur.

  • Kapama yapılacak tutar gönderilir → paidPrice.

  • Başarılı yanıt → status: success.

3. Ödeme Bilgilerine Erişim (Opsiyonel)

• Tanım: Ön provizyon işlemlerine ait detaylara veya güncel durumuna erişmek için kullanılan sorgu servisidir.

• Amaç:

  • PreAuth işleminin durumunu görmek

  • İşlem tutarını ve işlem tarihini kontrol etmek

• Teknik Detay:

  • iyzico API’de retrieve payment result servisi kullanılır.

• paymentId veya paymentConversationId gönderilerek sorgulama yapılır.

• Dönen yanıt:

  • phase → "POST_AUTH", "PRE_AUTH"

• Örnek Kullanım:

  • Müşteri “kartımdaki blokaj hala duruyor mu?” diye soruyor → sorgu yapılır.

  • PreAuth işlem kapandı mı, yoksa hala beklemede mi → API’den kontrol edilir.

4. Webhook

Ödeme sonucunu server-server bildirim olarak aldığınız adımdır. Detaylı bilgi için webhook sayfasını ziyaret edebilirsiniz.

Örnek Uygulama

Provizyon Başlatma (preAuth)

Örnek İstek (NON3D)

{
    "conversationId": "conversationId",
    "locale": "tr",
    "paidPrice": 1.0,
    "price": 1.0,
    "callbackUrl": "callbackUrl",
    "paymentGroup": "PRODUCT",
    "currency": "TRY",
    "basketId": "B67832",
    "paymentChannel":"WEB",
    "paymentCard":{
      "cardHolderName":"John Doe",
      "cardNumber":"5526080000000006",
      "expireYear":"2030",
      "expireMonth":"12",
      "cvc":"123",
      "registerCard":0
   },
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864111",
        "email": "[email protected]",
        "gsmNumber": "[phone]",
        "registrationAddress": "Adres",
        "city": "Istanbul",
        "country": "Turkey",
        "ip": "buyer Ip",
        "zipCode": "34580"
    },
    "shippingAddress": {
        "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34580"
    },
    "billingAddress": {
        "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34580"
    },
    "basketItems": [
        {
            "id": "BI101",
            "price": 1.0,
            "name": "Binocular",
            "category1": "Collectibles",
            "itemType": "PHYSICAL"
        }
    ]
}

Örnek Yanıt

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749126856155,
    "conversationId": "conversationId",
    "price": 1.0,
    "paidPrice": 1.0,
    "installment": 1,
    "paymentId": "24266451",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0.0,
    "iyziCommissionRateAmount": 0.03490000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Axess",
    "binNumber": "552608",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26275420",
            "transactionStatus": 2,
            "price": 1.0,
            "paidPrice": 1.00000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.03490000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2025-06-13 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.71510000,
            "convertedPayout": {
                "paidPrice": 1.00000000,
                "iyziCommissionRateAmount": 0.03490000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.71510000,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "311738",
    "phase": "PRE_AUTH",
    "hostReference": "mock00007iyzihostrfn",
    "signature": "6c1875b893ff897c82fcb883af2298fdc935bbda9d01740d0a65365c342df870"
}

Provizyon Kapama (postAuth)

Provizyon işleminin finansallaştırılacağı adımdır.

Örnek İstek

{
    "locale": "tr",
    "conversationId": "123456789",
    "paymentId": "24266451",
    "paidPrice": 1.0,
    "ip": "85.34.78.112",
    "currency": "TRY"
}

Örnek Yanıt

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749127073723,
    "conversationId": "123456789",
    "price": 1.00000000,
    "paidPrice": 1.00000000,
    "installment": 1,
    "paymentId": "24266451",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.03490000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Axess",
    "binNumber": "552608",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26275420",
            "transactionStatus": 2,
            "price": 1.00000000,
            "paidPrice": 1.00000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.03490000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2025-06-13 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 0.71510000,
            "convertedPayout": {
                "paidPrice": 1.00000000,
                "iyziCommissionRateAmount": 0.03490000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.71510000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "110529",
    "phase": "POST_AUTH",
    "hostReference": "mock00007iyzihostrfn",
    "signature": "ab8084477fb4a56045391cef2a8c92f85d7fba3f4c6ae00f0eef1f3bacee78da"
}

Ödeme Bilgilerine Erişim

Ödeme işlemine ait, ödeme numarası bilgisi ile işlem detaylarına ulaşabilirsiniz. İlgili servisin detay sayfasına buradan ulaşabilirsiniz.

Örnek İstek

{
    "locale": "tr",
    "conversationId": "123456789",
    "paymentConversationId": "conversationId",
    "paymentID":"24475824",
    "ip": "buyer Ip"
}

Örnek Yanıt

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749127218701,
    "conversationId": "123456789",
    "price": 1.00000000,
    "paidPrice": 1.00000000,
    "installment": 1,
    "paymentId": "24266451",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.03490000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Axess",
    "binNumber": "552608",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26275420",
            "transactionStatus": 2,
            "price": 1.00000000,
            "paidPrice": 1.00000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.03490000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2025-06-13 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 0.71510000,
            "convertedPayout": {
                "paidPrice": 1.00000000,
                "iyziCommissionRateAmount": 0.03490000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.71510000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "110529",
    "phase": "POST_AUTH",
    "hostReference": "mock00007iyzihostrfn",
    "signature": "ab8084477fb4a56045391cef2a8c92f85d7fba3f4c6ae00f0eef1f3bacee78da",
    "paymentStatus": "SUCCESS"
}

Webhook

Gerçek zamanlı ödeme bildirimlerinin alınması, genel olarak 3DS deneyiminden yararlanırken bildirimlerin güvenilir kaynaklardan gelmesini sağlar ve hassas verilere olası müdahaleleri veya yetkisiz erişimi önler.

Her ödeme olayı Webhook’ları tetikler;

• Her 15 saniyede bir

• Sunucunuz 200 yanıtını alana kadar.

• Her 10 dakikada bir

• Maksimum 3 kere

Parametre	Tip	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, ödeme numarası bilgisi
status	string	Ödeme durumu. Alabileceği değerler: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS
iyziReferenceCode	string	İstek için üretilen unique iyzico referans kodu
iyziEventType	string	İstek tipini belirtir. Alabileceği değerler: API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, CHECKOUTFORM_AUTH
iyziEventTime		Notification oluşturulma zamanının unix timestamp değeridir.
iyziPaymentId		Ödemeye ait ilgili paymentId.