# Ön Provizyon Entegrasyonu {% hint style="warning" %} **Ö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. {% endhint %} {% hint style="info" %} Ön provizyon işlemlerinde iptal ve iade işlemleri bankalara göre değişkenlik göstermektedir. {% endhint %} > Entegrasyon ve operasyonel talepleriniz için adresiyle veya hesap yöneticinizle iletişime geçebilirsiniz. ## Anahtar Tanımlar ve Entegrasyon Adımları ### [1. **Provizyon Başlatma (preAuth)**](#provizyon-baslatma-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)](#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 işlemi, provizyon tutarının maksimum %10 üzerinde yapılabilir. * 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)**](#odeme-bilgilerine-erisim) * **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**](#webhook) Ödeme sonucunu server-server bildirim olarak aldığınız adımdır. Detaylı bilgi için [webhook](https://docs.iyzico.com/ek-servisler/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": "sandboxtest@gmail.com",
        "gsmNumber": "+905555555555",
        "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 ```json { "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 ```json { "locale": "tr", "conversationId": "123456789", "paymentId": "24266451", "paidPrice": 1.0, "ip": "85.34.78.112", "currency": "TRY" } ``` #### Örnek Yanıt ```json { "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](https://docs.iyzico.com/odeme-metotlari/on-provizyon/broken-reference) ulaşabilirsiniz. #### Örnek İstek ```json { "locale": "tr", "conversationId": "123456789", "paymentConversationId": "conversationId", "paymentID":"24475824", "ip": "buyer Ip" } ``` #### Örnek Yanıt ```json { "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
ParametreTipAçıklama
paymentConversationIdstringİlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
merchantIdstringMerchant'ın iyzico tarafından atanmış ID numarası.
paymentIdstringİlgili ödemenin, ödeme numarası bilgisi
statusstringÖdeme durumu. Alabileceği değerler: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS
iyziReferenceCodestringİstek için üretilen unique iyzico referans kodu
iyziEventTypestringİstek tipini belirtir. Alabileceği değerler:
API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK,
CHECKOUTFORM_AUTH
iyziEventTimeNotification oluşturulma zamanının unix timestamp değeridir.
iyziPaymentIdÖdemeye ait ilgili paymentId.