iyzico Ödeme Formu (CheckoutForm)

Bu entegrasyonda kullanılan iyzico Ödeme Formu (CheckoutForm) ödeme yöntemi, temel olarak standart ödeme formu entegrasyonu ile aynı akışa sahiptir. Bu yöntemle yapılan işlemlerdeki temel fark, kullanılan endpoint'in farklı olmasıdır.

iyzico Ödeme Formu (CheckoutForm) entegrasyonunun detayları ve işlem akışına ilişkin teknik bilgiler için lütfen Ödeme Formu sayfasını ziyaret ediniz.

Ödeme Formu ile Ön Provizyon Başlatma

Ödeme Formu (CF) Başlatma

post

Ödeme formu (Checkout Form) oturumu başlatır ve ödeme sayfasını göstermek için checkoutFormContent / paymentPageUrl ve işleme ait token döner.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type değeri.

Example: application/json

Body

localestring · enumOptional

Dil kodu. Varsayılan; tr. Ödeme formunun İngilizce oluşturulması için "en" gönderilmelidir.

Example: trPossible values:

conversationIdstringOptional

İstek/yanıt eşleştirme ID’si. İstekte gönderilen değer, response'da aynen geri döner.

Example: conversationId

pricedecimalRequired

Sepet toplamı.

Example: 6

paidPricedecimalRequired

Tahsil edilecek toplam tutar.

Example: 6

currencystring · enumRequired

Para birimi. Varsayılan; TRY.

Example: TRYPossible values:

basketIdstringOptional

Sepet ID’si.

Example: basketId

paymentGroupstring · enumOptional

Ödeme grubu. Varsayılan; PRODUCT.

Example: PRODUCTPossible values:

callbackUrlstringRequired

Ödeme akışında üye işyerine başarılı ve hatalı sonucu bildirmek üzere alınan URL adresi. Geçerli bir ssl sertifikasına sahip olmalıdır.

Example: https://callback.com/test

enabledInstallmentsinteger[]Optional

Kullanılabilir taksit seçenekleri.

Example: [1,2,3,4,6,9,12]

paymentSourcestringOptional

Bu alan, partner firmalar tarafından iletilen ödeme kaynağı bilgisidir. Eğer bir altyapı sağlayıcısıysanız ve iyzico ile entegrasyon/iş birliğiniz bulunuyorsa bu parametreyi gönderebilirsiniz.

Example: Shopify

Responses

200

Başarılı yanıt (CF başlatıldı)

application/json

statusstring · enumOptional

Gönderilen isteğin sonucu.

Example: successPossible values:

localestringOptional

Yanıt dili.

Example: tr

systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755536500000

conversationIdstringOptional

İstek ile eşleşen ID.

Example: conversationId

tokenstringOptional

Checkout form için oluşturulan tekil değer. Her istek için özel üretilir ve işyerine dönülür. Ödemenin sonucunu öğrenmek için zorunlu bir alandır.

Example: 077aff05-1e9b-44aa-aa11-c268bb8b3826

checkoutFormContentstringOptional

Ödeme formunun HTML içeriği (Base64 kodlu).

Example: <script type="text/javascript">if (typeof iyziInit == 'undefined') {var iyziInit = {currency...

paymentPageUrlstringOptional

iyzico Ortak Ödeme Sayfası için dönen URL adresi.

Example: https://sandbox-api.iyzipay.com/checkoutform/...

signaturestringOptional

İmza doğrulaması için kullanılabilecek signature değeri.

Example: 4baf094819adc7015f615058d4ec2abf472c99476bcffddcda0ed18edf3f5351

400

Hatalı istek / doğrulama hatası

application/json

post/payment/iyzipos/checkoutform/initialize/preauth/ecom

POST https://api.iyzipay.com/payment/iyzipos/checkoutform/initialize/preauth/ecom
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "conversationId",
  "price": 6.0,
  "paidPrice": 6.0,
  "currency": "TRY",
  "basketId": "basketId",
  "paymentGroup": "PRODUCT",
  "callbackUrl": "https://callback.com/test",
  "enabledInstallments": [1,2,3,4,6,9,12],
  "paymentSource": "Test",
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "11111111111",
    "email": "sandboxtest@email.com",
    "gsmNumber": "+905350000000",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "85.34.78.112"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "billingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "basketItems": [
    {"id": "BI101", "price": 1.0, "name": "Binocular", "category1": "Collectibles", "category2": "Accessories", "itemType": "PHYSICAL"},
    {"id": "BI102", "price": 2.0, "name": "Game code", "category1": "Game", "category2": "Online Game Items", "itemType": "VIRTUAL"},
    {"id": "BI103", "price": 3.0, "name": "Usb", "category1": "Electronics", "category2": "Usb / Cable", "itemType": "PHYSICAL"}
  ]
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755536500000,
  "conversationId": "conversationId",
  "token": "077aff05-1e9b-44aa-aa11-c268bb8b3826",
  "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"c6a48036-327e-4808-89d0-d9049b123538\",price:6.00,pwiPrice:6.00,shippingDiscountAmount:null,locale:\"tr\",baseUrl:\"https://sandbox-api.iyzipay.com\", merchantGatewayBaseUrl:\"https://sandbox-merchantgw.iyzipay.com\", consumerGatewayBaseUrl:\"https://sandbox-consumerapigw.iyzipay.com\", registerCardEnabled:false,bkmEnabled:true,bankTransferEnabled:true,bankTransferTimeLimit:{\"value\":5,\"type\":\"day\"},bankTransferRedirectUrl:\"https://callback.com/test\",bankTransferCustomUIProps:{},campaignEnabled:false,campaignMarketingUiDisplay:{},campaignMarketingUiDisplayV2:{\"mobile\":{\"cardTabContent\":\"https://sandbox-static.iyzipay.com/marketing-display/campaign_M_C_v_1754637545492.png\",\"gsmCheckContent\":\"https://sandbox-static.iyzipay.com/marketing-display/campaign_M_G_v_1754637545949.png\",\"pwiTabContent\":\"https://sandbox-static.iyzipay.com/marketing-display/campaign_M_P_v_1754637545797.png\"},\"desktop\":{\"cardTabContent\":\"https://sandbox-static.iyzipay.com/marketing-display/campaign_D_C_v_1754637546014.png\",\"gsmCheckContent\":\"https://sandbox-static.iyzipay.com/marketing-display/campaign_D_G_v_1754637546164.png\",\"pwiTabContent\":\"https://sandbox-static.iyzipay.com/marketing-display/campaign_D_P_v_1754637546098.png\"}},paymentSourceName:\"\",plusInstallmentResponseList:null,payWithIyzicoSingleTab:false,payWithIyzicoSingleTabV2:false,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:\"John\",buyerSurname:\"Doe\",merchantInfo:\"\",merchantName:\"Sandbox Merchant Name - 3404590\",cancelUrl:\"\",buyerProtectionEnabled:true,hide3DS:false,gsmNumber:\"\",email:\"sandboxtest@email.com\",checkConsumerDetail:{},subscriptionPaymentEnabled:false,disabledCardStorageInfoCheckbox:false,ucsEnabled:true,fingerprintEnabled:false,payWithIyzicoFirstTab:false,creditEnabled:false,payWithIyzicoLead:false,zeroAuth:false,goBackUrl:\"\",customMerchantName:\"\",useCurrencySymbol:false,quickPwiEnabled:false,quickPwiNewCardEnabled:false,onlyQuickPwiView:false,consumerCardList:[],isForeignNumber:false,agreementCheckedByDefault:true,metadata : {},createTag:function(){var iyziJSTag = document.createElement('script');iyziJSTag.setAttribute('src','https://cdnsandbox.iyzipay.com/checkoutform/v2/bundle.js?v=1850323636123');document.head.appendChild(iyziJSTag);}};iyziInit.createTag();}</script><script type=\"text/javascript\">if (typeof iyziUcsInit == 'undefined') {var iyziUcsInit = {\"baseUrl\":\"https://sandbox-api.iyzipay.com\", \"ucsToken\":\"1cf43ef6-30ce-402a-a487-1be3f5c8702b\",\"scriptType\":\"BUYER_PROTECTION_CONSENT\",\"buyerProtectedMerchant\":true,\"maskedGsmNumber\":\"\",\"gsmNumber\":\"\",\"merchantName\":\"Sandbox Merchant Name - 3404590\", createTag: function () {var iyziUcsJSTag = document.createElement('script'); iyziUcsJSTag.setAttribute('src', 'https://sandbox-static.iyzipay.com/checkoutform/v2/bundle.js?v=1755539435707'); document.head.appendChild(iyziUcsJSTag);}};if (typeof iyziInit == 'undefined') { iyziUcsInit.createTag(); }}</script>",
  "paymentPageUrl": "https://sandbox-cpp.iyzipay.com?token=c6a48036-327e-4808-89d0-d9049b123538&lang=tr",
  "signature": "66e57d8376c4a15cbee9c8e82c6eb9f47a64bb47c80958c1198847a0049aa5df"
}

Başarılı şekilde ödeme oluşturulduğunda, iyzico API’si tarafından başarılı bir yanıt (response) döner. Dönen checkoutFormContent alanı içerisinde <script> etiketi ile oluşturulmuş ödeme formu yer alır. Bu içerik HTML sayfasında doğrudan render edilerek kullanıcıya gösterilmelidir. Kullanıcı ödeme işlemini tamamladıktan sonra, ilk istek sırasında belirtilen callbackUrl adresine otomatik olarak yönlendirilir ve token değeri post edilir.

Örnek Kodlar

PHP

NodeJS

Python

Ödeme Formu Sonucu Sorgulama

Ödeme Formu (CF) sorgulama

post

CF ödeme formu tamamlandıktan sonra, token ile sonuçları sorgular.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type değeri.

Example: application/json

Body

localestring · enumOptional

Dil kodu. Varsayılan; tr

Example: trPossible values:

conversationIdstringOptional

İstek/yanıt eşleştirme ID’si. İstekte gönderilen değer, response'da aynen geri döner.

Example: 8152109759

tokenstringRequired

CF initialize yanıtından dönen token.

Example: 077aff05-1e9b-44aa-aa11-c268bb8b3826

Responses

200

Başarılı yanıt (ödeme tamamlandı)

application/json

statusstring · enumOptional

Yapılan isteğin sonucu.

Example: successPossible values:

localestringOptional

Yanıt dili.

Example: tr

systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755536577419

conversationIdstringOptional

İstek ile eşleşen ID.

Example: 8152109759

pricedecimalOptional

Sepet toplam tutarı.

Example: 6

paidPricedecimalOptional

Tahsil edilen toplam tutar.

Example: 6

installmentintegerOptional

Taksit sayısı.

Example: 1

paymentIdstringOptional

Ödeme ID’si.

Example: 24478123

fraudStatusinteger · enumOptional

Fraud filtrelerine göre ödeme durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.

1: Onaylandı
0: İncelemede
-1: Reddedildi

Example: 1Possible values:

merchantCommissionRatedecimalOptional

Üye işyerinin uyguladığı vade/komisyon oranı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon oranı %10’dur. Bilgi amaçlıdır.

Example: 0

merchantCommissionRateAmountdecimalOptional

Üye işyerinin uyguladığı vade/komisyon tutarı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon tutarı 10’dur. Bilgi amaçlıdır.

Example: 0

iyziCommissionRateAmountdecimalOptional

Ödemeye ait iyzico işlem komisyon tutarı.

Example: 0.2094

iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25

cardTypestring · enumOptional

Kart tipi.

Example: CREDIT_CARDPossible values:

cardAssociationstring · enumOptional

Kart markası.

Example: MASTER_CARDPossible values:

cardFamilystring · enumOptional

Kart ailesi.

Example: AxessPossible values:

binNumberstringOptional

BIN (ilk 8 hane).

Example: 552608

lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006

basketIdstringOptional

Sepet ID.

Example: basketId

currencystring · enumOptional

Para birimi.

Example: TRYPossible values:

authCodestringOptional

Bankadan dönen authCode değeri.

Example: 930115

phasestringOptional

Ödeme Fazı.

Example: PRE_AUTH

hostReferencestringOptional

Ödemeye ilişkin banka tarafından verilen hostReference değeri.

Example: mock00007iyzihostrfn

signaturestringOptional

İmza doğrulaması için kullanılabilecek signature değeri.

Example: 1960256fa0406e6ca0e02a71a9d0b3bd72c2aad4e2677cd315975a4dc8ecfaa5

tokenstringOptional

CheckoutForm Token Değeri.

Example: 077aff05-1e9b-44aa-aa11-c268bb8b3826

callbackUrlstringOptional

Dönüş URL’si.

Example: https://callback.com/test

paymentStatusstringOptional

Ödeme sonucu.

Example: SUCCESS

400

Başarısız yanıt

application/json

post/payment/iyzipos/checkoutform/auth/ecom/detail

POST https://api.iyzipay.com/payment/iyzipos/checkoutform/auth/ecom/detail
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "8152109759",
  "token": "077aff05-1e9b-44aa-aa11-c268bb8b3826"
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755536577419,
  "conversationId": "8152109759",
  "price": 6,
  "paidPrice": 6,
  "installment": 1,
  "paymentId": "24478123",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.2094,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552608",
  "lastFourDigits": "0006",
  "basketId": "basketId",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "26475993",
      "transactionStatus": 2,
      "price": 1,
      "paidPrice": 1,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.0349,
      "iyziCommissionFee": 0.04166667,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-07-20 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.92343333,
      "convertedPayout": {
        "paidPrice": 1,
        "iyziCommissionRateAmount": 0.0349,
        "iyziCommissionFee": 0.04166667,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.92343333,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI103",
      "paymentTransactionId": "26475995",
      "transactionStatus": 2,
      "price": 3,
      "paidPrice": 3,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.1047,
      "iyziCommissionFee": 0.125,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-07-20 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 2.7703,
      "convertedPayout": {
        "paidPrice": 3,
        "iyziCommissionRateAmount": 0.1047,
        "iyziCommissionFee": 0.125,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 2.7703,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI102",
      "paymentTransactionId": "26475994",
      "transactionStatus": 2,
      "price": 2,
      "paidPrice": 2,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.0698,
      "iyziCommissionFee": 0.08333333,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-07-20 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 1.84686667,
      "convertedPayout": {
        "paidPrice": 2,
        "iyziCommissionRateAmount": 0.0698,
        "iyziCommissionFee": 0.08333333,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 1.84686667,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "930115",
  "phase": "PRE_AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "1960256fa0406e6ca0e02a71a9d0b3bd72c2aad4e2677cd315975a4dc8ecfaa5",
  "token": "077aff05-1e9b-44aa-aa11-c268bb8b3826",
  "callbackUrl": "https://callback.com/test",
  "paymentStatus": "SUCCESS"
}

Örnek Kodlar

Last updated 9 months ago