PWI-Initialize

After making the request mentioned below, you will receive the payWithIyzicoPageUrl value, which is a unique page where your customers will be directed to Pay with iyzico. Your customers will be automatically redirected to the callBackUrl you specified in the Pay-with-iyzico init request after completing the payment process.

You can display the generated link as a button, link, or div on your payment page. The token received with the link can be stored at this stage or when it is posted to callBackUrl if the customer continues the payment process. Please note that the generated link and token values are valid for 30 minutes. If no payment is received during this period, the token will expire.

callBackUrl address should have SSL.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

Pay with iyzico (PWI) — Initialize

post

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

Header parameters

AuthorizationstringRequired

Authorization header; starts with IYZWSv2 and is a signed hash in Base64.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequiredExample: application/json

Body

application/json

localestring · enumOptional

Language code. Default; tr

Example: enPossible values:

conversationIdstringOptional

Request/response correlation ID.

Example: conversationID

pricedecimalRequired

Basket total amount.

Example: 10

basketIdstringRequired

Basket ID.

Example: basketID

paymentGroupstring · enumOptional

Payment group.

Example: PRODUCTPossible values:

callbackUrlstringRequired

URL to redirect after the transaction.

Example: callbackUrl

currencystring · enumRequired

Currency. Default; TRY.

Example: TRYPossible values:

paidPricedecimalRequired

Amount to be collected.

Example: 10

paymentChannelstring · enumOptional

Payment channel.

Example: WEBPossible values:

Responses

200

Successful response (PWI initialized)

application/json

statusstring · enumOptional

Outcome of the request.

Example: successPossible values:

localestring · enumOptional

Response language.

Example: enPossible values:

systemTimeintegerOptional

Timestamp (epoch ms).

Example: 1755252275214

conversationIdstringOptional

Correlation ID of the request.

Example: conversationID

tokenstringOptional

Token generated for Pay with iyzico. Returned per request and required to retrieve the result.

Example: 54481021-e605-407e-93d7-776ef481c4d7

tokenExpireTimeintegerOptional

Token validity in seconds; 1800 seconds.

Example: 1800

payWithIyzicoPageUrlstringOptional

Payment page URL to redirect to.

Example: https://sandbox-ode.iyzico.com/?token=54481021-e605-407e-93d7-776ef481c4d7&lang=tr

signaturestringOptional

Response signature (hash).

Example: a35338903267271c38465924d7d1903b2e10870bebaef1a00923be864e475818

400

Bad request / validation error

application/json

post

/payment/pay-with-iyzico/initialize

HTTPcURL

POST https://api.iyzipay.com/payment/pay-with-iyzico/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "conversationID",
  "price": 10.0,
  "basketId": "basketID",
  "paymentGroup": "PRODUCT",
  "callbackUrl": "callbackUrl",
  "currency": "TRY",
  "paidPrice": 10.0,
  "paymentChannel": "WEB",
  "enabledInstallments": [1,2,3,6,9,12],
  "buyer": {
    "id": "buyerID",
    "name": "buyerName",
    "surname": "buyerSurname",
    "identityNumber": "11111111111",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "Istanbul",
    "country": "Turkey",
    "ip": "85.34.78.112",
    "zipCode": "34732",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "contactName": "Contact Name",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34742"
  },
  "billingAddress": {
    "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
    "contactName": "Contact Name",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34700"
  },
  "basketItems": [
    {
      "id": "ItemID",
      "price": 10.0,
      "name": "product Name",
      "category1": "Category Name",
      "itemType": "PHYSICAL"
    }
  ]
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755252275214,
  "conversationId": "conversationID",
  "token": "54481021-e605-407e-93d7-776ef481c4d7",
  "tokenExpireTime": 1800,
  "payWithIyzicoPageUrl": "https://sandbox-ode.iyzico.com/?token=54481021-e605-407e-93d7-776ef481c4d7&lang=tr",
  "signature": "a35338903267271c38465924d7d1903b2e10870bebaef1a00923be864e475818"
}

Sample Codes

PHP

Java

.Net

Postman