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
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ı
Servislere iletilecek istekler iyzico kimlik doğrulama yapısı ile iletilmelidir.
Ü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.
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.
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.
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.
Ü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.
Ö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": "[email protected]",
"gsmNumber": "+9055555555",
"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": "[email protected]",
"memberGsmNumber": "+905555555555",
"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
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": "[email protected]",
"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
{
"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"
}
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.
FUND
iyziEventType
İstek tipini belirtir. Alabileceği değerler:
PWI_TKN_FUND
NON3D
iyziEventType
PWI_TKN_AUTH
3DS
iyziEventType
PWI_TKN_THREEDS_AUTH
Last updated