# 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."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iyzico.com/en/getting-started/preliminaries/api-reference-beta/payment-methods/checkoutform.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.