Tokenization Entegrasyonu

iyzico tokenization modelinde iyzico ile Öde yöntemiyle entegrasyon gerçekleştirebilirsiniz:

iyzico ile Öde (Pay with iyzico)

"iyzico ile Öde", kullanıcıların çevrimiçi alışverişlerini hızlı, kolay ve güvenli bir şekilde tamamlamalarını sağlayan bir dijital ödeme yöntemidir. iyzico tarafından sunulan bu hizmet sayesinde kullanıcılar, kart bilgilerini her alışverişte yeniden girmeye gerek kalmadan ödeme işlemini gerçekleştirebilirler. Ayrıca, iyzico'nun sunduğu taksitlendirme gibi ek avantajlardan da faydalanmaya devam edebilirler.

Bu ödeme yöntemi, hem kullanıcılar hem de işletmeler için güvenli bir ödeme altyapısı sunarak alışveriş deneyimini iyileştirmeyi hedefler.

"iyzico ile Öde" ödeme yöntemini başlatarak son kullanıcıyı iyzico hesabına login olması için yönlendirebilirsiniz.

Anahtar Tanımlar

• Member : iyzico ile Öde hizmeti kapsamında, platforma kayıt olan son kullanıcılar "member" olarak adlandırılır. Member'lar, iyzico’nun sunduğu dijital cüzdan ve ödeme çözümlerinden faydalanabilir, güvenli ve hızlı bir şekilde ödeme yapabilirler.

• Ödeme Tipi : Tokenization kapsamında kullanılabilecek iki ödeme tipi bulunmaktadır: Bakiye ve Kart ödemesi.

  • Bakiye Ödemesi: Kullanıcının iyzico cüzdanında bulunan mevcut bakiyesi ile gerçekleştirdiği ödemelerdir.

  • Kart Ödemesi: Kullanıcının daha önce kaydettiği veya yeni eklediği kredi/banka kartı ile gerçekleştirdiği ödemelerdir.

• Session: Member'ın üye işyerimiz aracılığıyla aynı ödeme tipinde yaptığı ve yapacağı ödeme sürecini ifade eder. Session, unique bir değer olan session token ile ifade edilir.

Entegrasyon Öncesi Hazırlıklar

• Üye işyerimizin bu servisi kullanabilmesi için IP adresilerini iyzico'ya whitelist ettirmesi gerekmektedir.

• Üye işyerimizin bu servisi kullanabilmesi için hesap ayarlarının düzenlenmesi gerekmektedir.

Entegrasyon Adımları

1. Servislere iletilecek istekler iyzico kimlik doğrulama yapısı ile iletilmelidir.
2. Üye işyeri, member'ın session'ını başlatmak için "iyzico ile Öde (PWI)" servisleri kullanılır. iyzico ile Öde (PWI) ile gerçekleşen başarılı ödemeye istinaden session bilgisi oluşur.
3. iyzico ile Öde (PWI) ile gerçekleştirilen ödemeye ait oluşan session ve member bilgileri için "Ödeme ve Session Sorgulama" servisi kullanılmaktadır. Session token ve member identifier üye iş yerimiz tarafından saklanmalıdır. Bu değerler access token almak ve ödeme geçirmek için ileride gerekli olacaktır. Oluşturulan sessionToken sınırlı bir süre ile oluşturulur. Bu süre üye iş yerlerine göre değişiklik gösterebilir.
4. Session token ve member bilgisi ile accessToken alabilmek için "Access Token Alma" servisi kullanılır. Kullanıcın son ödeme bilgisini almak ve tokenize edilmiş bilgiler ile ödeme alabilmesi için accessToken alınmalıdır. accessToken kısa süreli bir token'dır.
5. Session token ve member bilgisi ile member'a ait son ödeme bilgisini alabilmek için "Son Ödeme Bilgisi Alma" servisi kullanılır. accessToken bu aşamada gerekli olan bilgidir.
6. Üye iş yerinin tokenize edilen son ödeme yöntemini kontrol ederek ödeme alabilmesi için "Single API" üzerinden ödeme yöntemini seçerek ödeme isteğini iletmesi gerekir.

Her iyzico ile Öde oluşturma işlemi, mevcut session'ı sonlandırarak yeni bir session başlatır. Session süresince ödeme yöntemi değiştirilemez; ödeme yöntemi değiştirebilmek için iyzico ile Öde oluşturulmak zorundadır. Bu işlem, yeni bir session oluşturur ve ödeme süreci bu yeni session üzerinden devam eder.

Örnek Uygulama

Kimlik Doğrulama

Detayları için kimlik doğrulama sayfasını ziyaret edebilirsiniz.

iyzico ile Öde (PWI) Ödemesi ve Session Oluşturma

Aşağıda örnek olarak iyzico ile Öde (PWI) üzerinden yapılan initialize işlemi için request ve response verisi paylaşılmıştır. Member'ın ödeme işlemi gerçekleştirebilmesi için ve session bilgisi oluşabilmesi için iyzico ile Öde (PWI) servisi initialize edilmelidir.

Örnek İstek

{
    "paidPrice": 1.0,
    "locale": "tr",
    "enabledInstallments": [ 
        1,
        2,
        3,
        6,
        9,
        12
    ],
    "price": 1.0,
    "conversationId": "2224",
    "paymentGroup": "PRODUCT",
    "callbackUrl": "https://merchant-callback.com",
    "currency": "TRY",
    "basketId": "B67832",
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864711",
        "email": "[e-mail]",
        "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 Response

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749027773192,
    "conversationId": "2224",
    "token": "d9d9fc30-8178-4ca9-8f93-1b150f465da6",
    "signature": "a53e433a982bc9f927aed4e0383d083bd48de9cff343490ba7477f9964cfbfb1",
    "payWithIyzicoPageUrl": "https://sandbox-ode.iyzico.com/sdk?token=d9d9fc30-8178-4ca9-8f93-1b150f465da6&lang=tr",
    "tokenExpireTime": 600,
    "tokenExpireDate": 1749028373178
}

Ödeme ve Session Sorgulama Servisi

Member'ın session kapsamında yaptığı ödemelerin detayını ve session bilgilerini döner.

Örnek İstek

{
    "checkoutFormToken": "{{checkoutToken}}",
    "locale": "tr",
    "conversationId": "conversationId"
}

Örnek Yanıt

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749032413350,
    "conversationId": "conversationId",
    "token": "e54b957b-a153-410c-8761-79c9bd4ff44f",
    "callbackUrl": "https://merchant-callback.com",
    "paymentStatus": "SUCCESS",
    "price": 1.00000000,
    "paidPrice": 1.00000000,
    "installment": 1,
    "paymentId": "24259238",
    "memberEmail": "[e-mail]",
    "memberGsmNumber": "[phone]",
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.01750000,
    "iyziCommissionFee": 0E-8,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Advantage",
    "binNumber": "550472",
    "lastFourDigits": "0003",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26268394",
            "transactionStatus": 2,
            "price": 1.00000000,
            "paidPrice": 1.00000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.01750000,
            "iyziCommissionFee": 0E-8,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2025-06-05 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 0.98250000,
            "convertedPayout": {
                "paidPrice": 1.00000000,
                "iyziCommissionRateAmount": 0.01750000,
                "iyziCommissionFee": 0E-8,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.98250000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "054626",
    "phase": "AUTH",
    "hostReference": "mock00034iyzihostrfn",
    "signature": "a77fac0a954181b9816bac2d0ba55047d2bfb1934d8efaa6de39b93b91bc9d6c",
    "sessionInfo": {
        "sessionToken": "f403ef2f-fb08-4111-afd6-495811ef6b25",
        "sessionStatus": "ACTIVE",
        "memberIdentifier": "f1409923-57cb-468f-8df2-704ea02075e3",
        "paymentType": "CARD_PAYMENT"
    }
}

Access Token Alma Servisi

Ödeme tetiklenebilmesi ve son ödeme bilgilerinin alınabilmesi için gerekli accessToken bilgisi bu servis ile sorgulanır.

Örnek İstek

{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "locale": "tr",
    "conversationId": "test"
}

Örnek Yanıt

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749027862133,
    "conversationId": "test",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiItIiwic2NvcGUiOlsidGhpcmRQYXJ0eVNlc3Npb24iXSwic2Vzc2lvblRva2VuIjoiZDUzZWRiNzItNTNmMy00NmY0LTk5NWQtNDM1NzBhOTdiZDg4IiwiZXhwIjoxNzQ5MDI4MjIyLCJhdXRob3JpdGllcyI6WyJwd2lfdHBfc2Vzc2lvbl9jYXJkX2F1dGgiLCJwd2lfdHBfc2Vzc2lvbl9pbml0M2RzX2F1dGgiLCJwd2lfdHBfc2Vzc2lvbl9sYXN0X3BheW1lbnRfcmV0cmlldmUiLCJwd2lfdHBfc2Vzc2lvbl9mdW5kX2F1dGgiXSwianRpIjoiMTUwODdmNTgtZGE4Yy00OTFhLWFjN2QtYmYyODI2ODNmMGRlIiwiY2xpZW50X2lkIjoidGhpcmRQYXJ0eVNlc3Npb25DbGllbnQifQ.YC5McE1SdXrPeCpljrMU1X3kzc3FV7I8DoZ5G0qcS30"
}

Son Ödeme ve Session Detayını Sorgulama Servisi

Member'a ait son ödeme bilgisinin detaylarının dönüldüğü servistir. Access Token Alma servisinden elde edilen accessToken ile gelinmelidir.

Örnek Sorgulama İsteği

{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "locale": "tr",
    "conversationId": "conversationId"
}

Örnek Sorgulama Yanıtı

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749032543970,
    "conversationId": "conversationId",
    "card": {
        "cardHolderName": "John Doe",
        "cardAssociation": "MASTER_CARD",
        "cardFamily": "Advantage",
        "binNumber": "55047200",
        "lastFourDigits": "0003",
        "cardBankName": "HSBC",
        "cardType": "CREDIT_CARD",
        "expireMonth": "05",
        "expireYear": "2026",
        "expired": false,
        "willExpireSoon": false
    },
    "paymentType": "CARD_PAYMENT",
    "sessionToken": "f403ef2f-fb08-4111-afd6-495811ef6b25",
    "token": "e54b957b-a153-410c-8761-79c9bd4ff44f",
    "paymentId": 24259238
}

Ödeme Tipleri

Dönebilecek Ödeme Tipleri	Parametre	Açıklama	Gönderilebilecek Ödeme Tipleri
Son ödeme bakiye ile yapıldığında, paymentType "FUND" dönmektedir.	FUND	Bakiye ile Ödeme Yapıldığı Anlamına Gelir.	Bu durumda sonraki ödeme isteğinde paymentType "FUND" gönderilmelidir.
Son ödeme Kart ile yapıldığında, paymentType "CARD_PAYMENT" olarak dönmektedir.	CARD_PAYMENT	Kart ile ödeme yapıldığı anlamına gelir.	2D İşlem için, "NON3D" olarak gönderilmelidir. 3DS İşlem için, "3DS" gönderilmelidir.

Ödeme Servisi

Kullanılan son ödeme tipine göre, ödeme gerçekleştirilmesi için kullanılmaktadır. Örnek uygulamada paymentType "CARD_PAYMENT" olarak döndüğü için, kart ödemesi örneği paylaşılmaktadır.

Örnek İstek

{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "conversationId": "conversationId",
    "locale": "tr",
    "paymentType": "3DS",
    "paidPrice": 1.0,
    "price": 1.0,
    "callbackUrl": "callbackUrl",
    "paymentGroup": "PRODUCT",
    "currency": "TRY",
    "basketId": "B67832",
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864111",
        "email": "[e-mail]",
        "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": 1749027890082,
    "conversationId": "conversationId",
    "sessionToken": "d53edb72-53f3-46f4-995d-43570a97bd88",
    "paymentId": 24258864,
    "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtODc2NzgxNDM2MDk1ODAxMGl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTg5MDA0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jaGVja291dGZvcm0vY2FsbGJhY2szZHMvc3VjY2Vzcy8yNyI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJmYWlsdXJlVXJsIiB2YWx1ZT0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L2l5emlwb3MvY2hlY2tvdXRmb3JtL2NhbGxiYWNrM2RzL2ZhaWx1cmUvMjciPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iY29uZmlybWF0aW9uVXJsIiB2YWx1ZT0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svY29uZmlybTNkcyI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJQYVJlcSIgdmFsdWU9IjE4ZThlZGVhLTY2ZjgtNDg4NS05OTNkLWIyYTQ5MzFlNTY0MCI+CjwvZm9ybT4KPHNjcmlwdCB0eXBlPSJ0ZXh0L2phdmFzY3JpcHQiPgogICAgZG9jdW1lbnQuZ2V0RWxlbWVudEJ5SWQoIml5emljby0zZHMtZm9ybSIpLnN1Ym1pdCgpOwo8L3NjcmlwdD4KPC9ib2R5Pgo8L2h0bWw+",
    "checkoutToken": "1479d5ba-d52d-4fae-8f1c-9d9c75991f2a",
    "signature": "40c72c0d631861c7f1454baffc8f141e7947699dbe22c14ca40f75bdf775fae6"
}

paymentType alanı 3DS olarak gönderilen ve 3DS gerçekleşmesi gereken işlemlerde, response içerisinde threeDSHtmlContent alanı yer alır. Bu alan, 3D Secure doğrulama adımını başlatmak için gerekli olan HTML içeriğini base64 encode edilmiş şekilde sunar.

Doğrulama sürecinin doğru bir şekilde ilerleyebilmesi için:

1. threeDSHtmlContent verisi base64 formatında decode edilmelidir.

2. Decode edilen HTML içeriği, bir web sayfasında (örneğin iframe ya da direkt HTML olarak) kullanıcıya gösterilmelidir.

Bu adım, kullanıcıyı bankanın 3DS doğrulama ekranına yönlendirmek için zorunludur.

paymentType alanında gönderilen değer, NON3D olsa dahi iyzico dinamik 3DS yapısı gereği o işlem 3DS olarak geçmesi gerekiyorsa, dönen response şemasında threeDSHtmlContent verisi dönebilir.

Webhook

Tokenization cüzdan ödemeleri sonrasında iyzico tarafından üye işyerinin webhookUrl adresine gidecek bildirimlerde yer alacak eventType parametresi ödeme tipine göre değişmekte olup, aşağıdaki değerleri alacaktır. Gönderilen webhook bildirimleri, bu parametreler üzerinden ayrıştırılabilir. Detayları için webhook sayfamızı ziyaret edebilirsiniz.

Ödeme Tipi	Parametre	Açıklama
FUND	iyziEventType	İstek tipini belirtir. Alabileceği değerler: PWI_TKN_FUND
NON3D	iyziEventType	PWI_TKN_AUTH
3DS	iyziEventType	PWI_TKN_THREEDS_AUTH