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