> For the complete documentation index, see [llms.txt](https://docs.iyzico.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iyzico.com/en/getting-started/preliminaries/api-reference-beta/payment-methods/pay-with-iyzico.md).

# Pay with iyzico

## Pay with iyzico (PWI) — Initialize

> Starts a PWI session; returns the token and page URL for redirection.

```json
{"openapi":"3.0.3","info":{"title":"Pay with iyzico (PWI)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/pay-with-iyzico/initialize":{"post":{"summary":"Pay with iyzico (PWI) — Initialize","description":"Starts a PWI session; returns the token and page URL for redirection.","tags":["Pay with iyzico"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (PWI initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiInitializeResponse"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; starts with IYZWSv2 and is a signed hash in Base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"}}},"schemas":{"PwiInitializeRequest":{"type":"object","required":["price","basketId","callbackUrl","currency","paidPrice","buyer","billingAddress","shippingAddress","basketItems"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"conversationId":{"type":"string","description":"Request/response correlation ID."},"price":{"type":"decimal","description":"Basket total amount."},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","enum":["PRODUCT","LISTING","SUBSCRIPTION"],"description":"Payment group."},"callbackUrl":{"type":"string","description":"URL to redirect after the transaction."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"],"description":"Currency. Default; TRY."},"paidPrice":{"type":"decimal","description":"Amount to be collected."},"paymentChannel":{"type":"string","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"],"description":"Payment channel."},"enabledInstallments":{"type":"array","items":{"type":"integer","enum":[1,2,3,6,9,12]},"description":"Installment options to offer."},"buyer":{"$ref":"#/components/schemas/PwiBuyer"},"shippingAddress":{"$ref":"#/components/schemas/PwiAddress","description":"Shipping Address. Required if at least one basket item is PHYSICAL. If all items are VIRTUAL, this is not required."},"billingAddress":{"$ref":"#/components/schemas/PwiAddress"},"basketItems":{"type":"array","description":"Basket items.","minItems":1,"items":{"$ref":"#/components/schemas/PwiBasketItem"}}}},"PwiBuyer":{"type":"object","description":"Buyer information","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country","ip"],"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 (e.g., TR ID)."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"Mobile phone number."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"ip":{"type":"string","description":"IP address."},"zipCode":{"type":"string","description":"Postal code."},"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)."}}},"PwiAddress":{"type":"object","description":"Address information","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Address."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."}}},"PwiBasketItem":{"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 of the service provider. Not used in the standard business model; required only in marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not used in the standard business model; required only in marketplace model."}}},"PwiInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."},"token":{"type":"string","description":"Token generated for Pay with iyzico. Returned per request and required to retrieve the result."},"tokenExpireTime":{"type":"integer","description":"Token validity in seconds; 1800 seconds."},"payWithIyzicoPageUrl":{"type":"string","description":"Payment page URL to redirect to."},"signature":{"type":"string","description":"Response signature (hash)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure indicator."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."}}}}}}
```

## Pay with iyzico (PWI) — Retrieve

> Queries the PWI transaction result by token.

```json
{"openapi":"3.0.3","info":{"title":"Pay with iyzico (PWI)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/auth/ecom/detail":{"post":{"summary":"Pay with iyzico (PWI) — Retrieve","description":"Queries the PWI transaction result by token.","tags":["Pay with iyzico"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiRetrieveRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiPaymentResponse"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; starts with IYZWSv2 and is a signed hash in Base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"}}},"schemas":{"PwiRetrieveRequest":{"type":"object","required":["token"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"conversationId":{"type":"string","description":"Request/response correlation ID."},"token":{"type":"string","description":"Token of the PWI session to be retrieved."}}},"PwiPaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en).","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Fraud status of the payment.\n- 1: Approved\n- 0: In review\n- -1: Rejected\n","enum":[1,0,-1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission/deferral rate (informational). For example, if price=100 and paidPrice=110, the rate is 10%."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission/deferral amount (informational). For example, if price=100 and paidPrice=110, the amount is 10."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","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 four 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":"Transaction items for basket lines.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Payment line ID; must be stored by the merchant (used for refund/capture/void and communication)."},"itemId":{"type":"string","description":"Item ID provided by the merchant."},"price":{"type":"decimal","description":"Amount of the basket item on the merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount distributed to this line; must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Line status:\n- 0: In fraud check\n- -1: Rejected after fraud check\n- 1: Approved (in marketplace: waiting for merchant approval)\n- 2: Approved (marketplace approved)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for this line (if applicable per agreement)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution date (yyyy-MM-dd HH:mm:ss), e.g., 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico fee at line level."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount at line level."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission/deferral rate at line level."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission/deferral amount at line level."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant after fees/commissions/blockages."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount distributed to this line; must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico fee at line level."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after conversion."},"currency":{"type":"string","description":"Currency."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Bank-provided host reference for the payment."},"signature":{"type":"string","description":"Signature value for verification."},"token":{"type":"string","description":"Token associated with the transaction (returned by the retrieval)."},"callbackUrl":{"type":"string","description":"Callback URL sent at initialization."},"paymentStatus":{"type":"string","description":"Payment status.","enum":["SUCCESS","FAILURE"]},"memberEmail":{"type":"string","description":"Email of the member who paid via PWI."},"memberGsmNumber":{"type":"string","description":"GSM number of the member who paid via PWI."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure indicator."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.