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":"stronger@implementation.com",
      "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:\"stronger@implementation.com\",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;

Parametre ismi

Tip

Açıklama

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"
}

mdStatus parametresi sadece 3DS işlemlerinde görünecektir. Lütfen mdStatus ile ilgili daha fazla ayrıntıyı buradan kontrol edin.

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

Parametre ismi

Tip

Açıklama

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 de success olmalıdır.
price parametresi tutarları aynı olmalıdır.
Ve son olarak, Eşleştirme parametreleri de aynı olmalıdır.

Sağlanan örnek isteklerin ve yanıtların yalnızca açıklama amaçlı olduğunu ve bunları kendi özel uygulama gereksinimlerinize ve API belgelerinize uyarlamanız gerektiğini lütfen unutmayın.

Last updated 9 months ago