CF Örnek Entegrasyon
Bu dokümanda, Redirect Form ile CF'nin kapsamlı entegrasyon adımlarını derinlemesine inceleyeceğiz ve hızlı, kolay ve güvenli bir entegrasyon için örnek istekler, yanıtlar ve en iyi uygulamalar sağlayacağız.
Ön Gereksinimler
Devam etmeden önce, lütfen aşağıdaki ön koşullara sahip olduğunuzdan emin olunuz.
Sandbox Hesabı
API ve Güvenlik Anahtarı
API çağrılarını yönetmek için bir yazılım aracı; Postman, Insonmina, Github clients
Genel Bakış
CF'nin uygulanması, birbirini izleyen iki POST
isteğinin birbiri ardına düzenlenmesini gerektirir.
Kısacası;
İlk olarak, bir CF Başlatma
POST
isteğini göstereceğiz.Ardından, CF Sorgulama
POST
isteği ile tamamlayacağız.
Adımlar
Adım 1 - CF Başlatma
CF uygulaması, CF Başlatma POST
isteği ile başlar.
Bu adım, bir POST
isteği göndermeyi içerir ve istek yapısı; locale, conversationId, price, basketId, paymentGroup, callbackUrl, currency, paidPrice, enabledInstallments, buyer details, shipping address, billing address ve basketItems gibi çeşitli parametreler içerir.
Aşağıdaki nesne, örnek bir CF Başlatma istek gövdesidir.
Örnek CF Başlatma İsteği;
{
"locale":"en",
"conversationId":"sampleConversationId",
"price":"5.2",
"basketId":"B67832",
"paymentGroup":"PRODUCT",
"buyer":{
"id":"BY789",
"name":"Higher",
"surname":"Faster",
"identityNumber":"74300864791",
"email":"[email protected]",
"gsmNumber":"+905555434332",
"registrationAddress":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
"city":"Istanbul",
"country":"Turkey",
"ip":"85.34.78.112"
},
"shippingAddress":{
"address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
"contactName":"Jane Doe",
"city":"Istanbul",
"country":"Turkey"
},
"billingAddress":{
"address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
"contactName":"Jane Doe",
"city":"Istanbul",
"country":"Turkey"
},
"basketItems":[
{
"id":"BI101",
"price":"5.2",
"name":"Binocular",
"category1":"Category 1",
"itemType":"PHYSICAL"
}
],
"callbackUrl":"YOUR_CALLBACKURL",
"currency":"TRY",
"paidPrice":"5.2",
"paymentSource":"zooz",
"enabledInstallments":[
2,3
]
}
Yukarıdaki isteği tetikledikten sonra, çoğunlukla izleyeceğiniz 3 (üç) senaryo vardır. Yanıt paymentPageUrl
adlı bir değişken içerir.
Örnek CF Başlatma Yanıtı;
{
"status": "success",
"locale": "en",
"systemTime": 1687112732811,
"conversationId": "sampleConversationId",
"token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
"checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"a5b67652-c24a-4347-b61e-6c957bf30f1b\",price:5.20,locale:\"en\",baseUrl:\"https://sandbox-api.iyzipay.com\", merchantGatewayBaseUrl:\"https://sandbox-merchantgw.iyzipay.com\", registerCardEnabled:true,bkmEnabled:true,bankTransferEnabled:true,bankTransferTimeLimit:{\"value\":5,\"type\":\"day\"},bankTransferRedirectUrl:\"YOUR_CALLBACKURL\",bankTransferCustomUIProps:{},campaignEnabled:false,campaignMarketingUiDisplay:null,paymentSourceName:\"zooz\",plusInstallmentResponseList:null,payWithIyzicoSingleTab:true,payWithIyzicoOneTab:false,mixPaymentEnabled:true,creditCardEnabled:true,bankTransferAccounts:[{\"iban\":\"TR020006200035600006294884\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Garanti Bankası\",\"bankId\":62,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/62.svg\"},{\"iban\":\"TR080006400000111351092786\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"İş Bankası\",\"bankId\":64,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/64.svg\"},{\"iban\":\"TR340004600786888000080896\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Akbank\",\"bankId\":46,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/46.svg\"},{\"iban\":\"TR910006701000000096073759\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Yapı Kredi Bankası\",\"bankId\":67,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/67.svg\"},{\"iban\":\"TR760001001187768823545001\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Ziraat Bankası\",\"bankId\":10,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/10.svg\"}],userCards:[],fundEnabled:true,memberCheckoutOtpData:{},force3Ds:false,isSandbox:true,storeNewCardEnabled:true,paymentWithNewCardEnabled:true,enabledApmTypes:[\"SOFORT\",\"IDEAL\",\"QIWI\",\"GIROPAY\"],payWithIyzicoUsed:false,payWithIyzicoEnabled:true,payWithIyzicoCustomUI:{},buyerName:\"Higher\",buyerSurname:\"Faster\",merchantInfo:\"\",merchantName:\"Sandbox Merchant Name - 3389550\",cancelUrl:\"\",buyerProtectionEnabled:false,hide3DS:false,gsmNumber:\"+905555434332\",email:\"[email protected]\",checkConsumerDetail:{},subscriptionPaymentEnabled:false,ucsEnabled:false,fingerprintEnabled:false,payWithIyzicoFirstTab:false,creditEnabled:true,payWithIyzicoLead:false,goBackUrl:\"\",metadata : {},createTag:function(){var iyziJSTag = document.createElement('script');iyziJSTag.setAttribute('src','https://sandbox-static.iyzipay.com/checkoutform/v2/bundle.js?v=1687112732810');document.head.appendChild(iyziJSTag);}};iyziInit.createTag();}</script>",
"tokenExpireTime": 1800,
"paymentPageUrl": "https://sandbox-cpp.iyzipay.com?token=a5b67652-c24a-4347-b61e-6c957bf30f1b&lang=en",
"payWithIyzicoPageUrl": "https://sandbox-ode.iyzico.com/?token=a5b67652-c24a-4347-b61e-6c957bf30f1b&lang=en"
}
Adım 2 - Token + URL
Burada token ve paymentPageUrl, ödeme yolculuğunun geri kalanı için temel düğümlerdir.
Bu adımda, önceki adımda aldığınız yanıttan token ve paymentPageUrl'yi çıkarmanız gerekir. Token daha sonra doğrulama için kaydedilmelidir ve kullanıcıyı ödeme sayfasına yönlendirmek için paymentPageUrl kullanılır.
token; Satıcıların, ödeme yolculuğunun en sonunda ödemeyle yüzleşmek ve doğrulamak için
token
parametresini kaydetmesi beklenir.paymentPageUrl; ödeme sayfasının kısaca göründüğü yer.
paymentPageUrl
'ye yönlendirme, son kullanıcılar için ödeme işlemlerini güvenli bir şekilde gerçekleştirmek için bir arayüz sağlar.
Tarayıcıda paymentPageUrl Arayüz Örneği;

Adım 3 - Yönlendirme
Yönlendirme aşaması, genel olarak CF Başlatma ve CF Sorgulama adımlarını birbirine bağlar.
iyzico, CF ödeme sayfasındaki son kullanıcı etkileşimini takip ederek sayfayı otomatik olarak "callbackUrl" parametresinde verilen adrese yönlendirecektir. Yönlendirme POST'u şunları içerir;
token
String
Her ödeme formu isteği için oluşturulan benzersiz değer. Bu belirteç, ödeme sonucuna erişmek için kullanılır.
Adım 4 - CF Sorgulama
CF Sorgulama, PWI zincirinin son adımıdır. Temel olarak, bir önceki adımda bir ödemeyi henüz kabul ettik. Şimdi bu adımda işlemi yasallaştırma zamanı.
Aşağıdaki örnek, örnek bir CF Sorgulama istek yapısıdır.
Örnek CF Sorgulama İsteği;
{
"locale": "en",
"token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
"conversationId": "sampleConversationId"
}
Yukarıdaki isteği tetikledikten sonra, çoğunlukla izleyeceğiniz 2 (iki) senaryo vardır. Yanıt PaymentStatus
değişkeninde SUCCESS
parametresini içerir.
Örnek CF Sorgulama Yanıtı;
{
"status": "success",
"locale": "en",
"systemTime": 1687113618054,
"conversationId": "sampleConversationId",
"price": 5.20000000,
"paidPrice": 5.20000000,
"installment": 1,
"paymentId": "19831123",
"fraudStatus": 1,
"merchantCommissionRate": 0E-8,
"merchantCommissionRateAmount": 0E-8,
"iyziCommissionRateAmount": 0.20800000,
"iyziCommissionFee": 0.25000000,
"cardType": "CREDIT_CARD",
"cardAssociation": "TROY",
"cardFamily": "Cardfinans",
"binNumber": "979203",
"lastFourDigits": "0000",
"basketId": "B67832",
"currency": "TRY",
"itemTransactions": [
{
"itemId": "BI101",
"paymentTransactionId": "21097896",
"transactionStatus": 2,
"price": 5.20000000,
"paidPrice": 5.20000000,
"merchantCommissionRate": 0E-8,
"merchantCommissionRateAmount": 0E-8,
"iyziCommissionRateAmount": 0.20800000,
"iyziCommissionFee": 0.25000000,
"blockageRate": 0E-8,
"blockageRateAmountMerchant": 0E-8,
"blockageRateAmountSubMerchant": 0E-8,
"blockageResolvedDate": "2023-06-26 00:00:00",
"subMerchantPrice": 0E-8,
"subMerchantPayoutRate": 0E-8,
"subMerchantPayoutAmount": 0E-8,
"merchantPayoutAmount": 4.74200000,
"convertedPayout": {
"paidPrice": 5.20000000,
"iyziCommissionRateAmount": 0.20800000,
"iyziCommissionFee": 0.25000000,
"blockageRateAmountMerchant": 0E-8,
"blockageRateAmountSubMerchant": 0E-8,
"subMerchantPayoutAmount": 0E-8,
"merchantPayoutAmount": 4.74200000,
"iyziConversionRate": 0E-8,
"iyziConversionRateAmount": 0E-8,
"currency": "TRY"
}
}
],
"authCode": "104530",
"phase": "AUTH",
"mdStatus": 1,
"hostReference": "mock00037iyzihostrfn",
"token": "3ee2d355-da4d-47ce-bd3d-13d8c1854128",
"callbackUrl": "YOUR_CALLBACKURL",
"paymentStatus": "SUCCESS"
}
Adım 5 - Webhook
Webhook, uygulama düzenimizin en önemli konusudur.
Gerçek zamanlı ödeme bildirimleri almak, genel CF deneyiminden yararlanırken, bildirimlerin güvenilir kaynaklardan gelmesini sağlayarak hassas verilere herhangi bir olası kurcalamayı veya yetkisiz erişimi önler.
Her ödeme olayı, webhook tetikler;
15 saniye
içinde gelir.Sunucunuz
200
yanıtı verene kadar devam eder.Her
10 dakikada
bir tekrarlanır.En fazla
3 kez
tekrarlanır.
Örnek CF Webhook
iyziEventTime
long
Notification oluşturulma zamanının unix timestamp değeridir.
iyziEventType
string
İstek tipini belirtir. Alabileceği değerler CHECKOUTFORM_AUTH, API_AUTH, THREE_DS_AUTH, BALANCE, BKM_AUTH
iyziReferenceCode
string
İstek için üretilen unique iyzico referans kodu
paymentId
long
İlgili ödemenin paymentId bilgisi
paymentConversationId
string
İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
status
string
Ödeme durumu. Alabileceği değerler: SUCCESS, FAILURE, CALLBACK_THREEDS
Yanıt, status
değişkeninde success
parametresini içerir.
Onaylama
Ödeme işlemlerinin başarılı bir şekilde sonuçlandırılması için bazı değişkenlerin korelasyonu önemli rol oynar;
paymentId
status
price
İsteğe bağlı olarak diğer Eşleştirme parametreleri
CF Sorgulama yanıtı ve Webhook bildirimi birbirini doğrulamalıdır.
CF Sorgulama'dan alınan yanıtı ve Webhook bildiriminde alınan verileri çapraz doğrulamak çok önemlidir. İşlemin gerçekliğini ve doğruluğunu sağlamak için ödeme paymentId, status, price ve diğer ilgili parametreleri eşleştiriniz.
CF Sorgulama yanıtındaki ödeme kimliği, Webhook'tan ödeme kimliğine eşit olmalıdır.
Her iki
status
parametresi desuccess
olmalıdır.price
parametresi tutarları aynı olmalıdır.Ve son olarak, Eşleştirme parametreleri de aynı olmalıdır.
Last updated