# CheckoutForm

## Checkout Form (CF) Initialize

> Starts a Checkout Form session and returns \`checkoutFormContent\` / \`paymentPageUrl\` and a \`token\` to render the payment page.

```json
{"openapi":"3.0.3","info":{"title":"Checkout Form (CF)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/initialize/auth/ecom":{"post":{"summary":"Checkout Form (CF) Initialize","description":"Starts a Checkout Form session and returns `checkoutFormContent` / `paymentPageUrl` and a `token` to render the payment page.","tags":["CheckoutForm"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (CF initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFInitializeResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with **IYZWSv2** and is a signed hash generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"CFInitializeRequest":{"type":"object","required":["price","paidPrice","currency","callbackUrl","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`. Send `en` to render the form in English.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned unchanged in the response."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Total amount to be charged."},"currency":{"type":"string","description":"Currency. Default is `TRY`.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default is `PRODUCT`.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"callbackUrl":{"type":"string","description":"Merchant URL that iyzico calls to deliver both success and failure results. Must have a valid SSL certificate."},"enabledInstallments":{"type":"array","description":"Available installment options.","items":{"type":"integer"}},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/BuyerCF"},"shippingAddress":{"description":"Shipping address. Required if at least one basket item is `PHYSICAL`. If all items are `VIRTUAL`, it is not required.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Basket items.","items":{"$ref":"#/components/schemas/BasketItem"}}}},"BuyerCF":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Mobile phone number."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD hh:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD hh:mm:ss)."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model. Required only for the marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model. Required only for the marketplace model."}}},"CFInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."},"token":{"type":"string","description":"Unique token generated for the checkout form. Mandatory to retrieve the payment result."},"checkoutFormContent":{"type":"string","description":"HTML content of the payment form (Base64-encoded)."},"paymentPageUrl":{"type":"string","description":"URL of iyzico’s hosted payment page (Common Payment Page)."},"signature":{"type":"string","description":"Signature value that can be used for integrity verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."}}}}}}
```

## Checkout Form (CF) Retrieve

> After the CF payment form is completed, queries the result using the \`token\`.

```json
{"openapi":"3.0.3","info":{"title":"Checkout Form (CF)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/auth/ecom/detail":{"post":{"summary":"Checkout Form (CF) Retrieve","description":"After the CF payment form is completed, queries the result using the `token`.","tags":["CheckoutForm"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFRetrieveRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFRetrieveResponse"}}}},"400":{"description":"Failed response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with **IYZWSv2** and is a signed hash generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"CFRetrieveRequest":{"type":"object","required":["token"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned unchanged in the response."},"token":{"type":"string","description":"Token returned in the CF initialize response."}}},"CFRetrieveResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Number of installments."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is **1**; for **0**, wait for notification.\n - **1**: Approved\n - **0**: In review\n - **-1**: Rejected\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate. For example, if price=100 and paidPrice=110, the rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount. Example; 10 when price=100 and paidPrice=110. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico processing commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico processing fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Line items corresponding to basket items.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID for the payment line item. Must be stored by the merchant. Used for refund/capture/void and when communicating with iyzico (ideally stored together with `itemId`)."},"itemId":{"type":"string","description":"Merchant-provided ID of the item in the basket."},"price":{"type":"decimal","description":"Item amount on the merchant’s side."},"paidPrice":{"type":"decimal","description":"Collected amount distributed per line item. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment line item.\n- **0**: In fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (in Marketplace, 1 means “Awaiting Merchant Approval”)\n- **2**: Approved (Marketplace approval granted)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for this line item. According to the iyzico–merchant agreement, a per-transaction blockage may be applied to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant. If the blockage exceeds the merchant amount, it is reflected to the sub-merchant as well."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution datetime for this line item. Format **yyyy-MM-dd HH:mm:ss** (e.g., 2015-10-19 14:36:52)."},"iyziCommissionFee":{"type":"decimal","description":"Portion of iyzico processing fee distributed to this line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"Portion of iyzico processing commission distributed to this line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate distributed to this line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount distributed to this line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant for this line item after fees/commissions and blockages."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount per line item (must be stored)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico processing fee distributed to this line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico processing commission distributed to this line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage reflected to the merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/commissions and blockages."},"iyziConversionRate":{"type":"decimal","description":"Conversion rate."},"iyziConversionRateAmount":{"type":"decimal","description":"Amount resulting from the conversion rate."}}}}},"currency":{"type":"string","description":"Currency of the payment."}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Bank-provided host reference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for integrity verification."},"token":{"type":"string","description":"Checkout Form token value."},"callbackUrl":{"type":"string","description":"Callback URL."},"paymentStatus":{"type":"string","description":"Result of the payment."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."}}}}}}
```