# Pay With iyzico

The Pay With iyzico method allows you to complete the transaction by directing the end user to the iyzico wallet account offered by iyzico.

This method is ideal for partners who want to integrate quickly and leave the UI to iyzico. This service should be used for API-API Pay With iyzico.

## Initialize Pay with iyzico

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/pwi/init`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |

### **Request** Parameters

<table><thead><tr><th width="219.78515625">Parametre</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Yes</td><td>Final amount (including installment fee) that will be charged to customer’s card</td></tr><tr><td><code>locale</code></td><td>String</td><td>No</td><td>Language (default: tr)</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Yes</td><td>Total amount of basket. The sum of basket items’ amount must be equal to the price of basket.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>No</td><td>Conversation ID to match request and response</td></tr><tr><td><code>paymentGroup</code></td><td>String</td><td>Yes</td><td>Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>Yes</td><td>Merchant callback URL for payment result notification.<br>callBackUrl address should have SSL.</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>Currency (default: TRY). Alternatively, you can set USD, EUR, GBP </td></tr><tr><td><code>basketId</code></td><td>String</td><td>No</td><td>Merchant's basket ID</td></tr><tr><td><code>buyerId</code></td><td>String</td><td>Yes</td><td>ID of buyer.</td></tr><tr><td><code>buyerName</code></td><td>String</td><td>Yes</td><td>Name of buyer</td></tr><tr><td><code>buyerSurname</code></td><td>String</td><td>Yes</td><td>Surname of buyer</td></tr><tr><td><code>identityNumber</code></td><td>String</td><td>Yes</td><td>Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants</td></tr><tr><td><code>email</code></td><td>String</td><td>Yes</td><td>Email of buyer</td></tr><tr><td><code>gsmNumber</code></td><td>String</td><td>No</td><td>GSM number of buyer</td></tr><tr><td><code>registrationAddress</code></td><td>String</td><td>Yes</td><td>Registration address of buyer</td></tr><tr><td><code>city</code></td><td>String</td><td>Yes</td><td>City of buyer</td></tr><tr><td><code>country</code></td><td>String</td><td>Yes</td><td>Country of buyer</td></tr><tr><td><code>IP</code></td><td>String</td><td>No</td><td>IP of buyer</td></tr><tr><td><code>zipCode</code></td><td>String</td><td>Yes</td><td>Zip code of buyer</td></tr><tr><td><code>address(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory</td></tr><tr><td><code>contactName(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>city(shippingAddress)</code></td><td>String</td><td>Yes</td><td>City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>country(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>zipCode(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Zip code of shipping address.</td></tr><tr><td><code>address(billingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of billing address.</td></tr><tr><td><code>contactName(billingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of billing address.</td></tr><tr><td><code>city(billingAddress)</code></td><td>String</td><td>Yes</td><td>City name of billing address.</td></tr><tr><td><code>country(billingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of billing address.</td></tr><tr><td><code>basketItemId</code></td><td>String</td><td>Yes</td><td><p>Basket Item ID.</p><p>It can take a maximum of 500 characters.</p></td></tr><tr><td><code>basketItemPrice</code></td><td>String</td><td>Yes</td><td>Price value for each item. Must be greater than zero.</td></tr><tr><td><code>basketItemName</code></td><td>String</td><td>Yes</td><td>Name of the item in the basket.</td></tr><tr><td><code>basketItemCategory1</code></td><td>String</td><td>Yes</td><td>Category 1 for item in the basket.</td></tr><tr><td><code>basketItemCategory2</code></td><td>String</td><td>No</td><td>Category 2 for item in the basket.</td></tr><tr><td><code>basketItemItemType</code></td><td>String</td><td>Yes</td><td>Item Type. Valid values are PHYSICAL,VIRTUAL</td></tr></tbody></table>

### INIT PWI Request

```json
{
    "paidPrice": 1.0,
    "locale": "en",
    "enabledInstallments": [ 
        1,
        2,
        3,
        6,
        9,
        12
    ],
    "price": 1.0,
    "conversationId": "2224",
    "paymentGroup": "PRODUCT",
    "callbackUrl": "https://merchant-callback.com",
    "currency": "TRY",
    "basketId": "B67832",
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864711",
        "email": "sandboxtest0@gmail.com",
        "gsmNumber": "+9055555555",
        "registrationAddress": "Adres",
        "city": "Istanbul",
        "country": "Turkey",
        "ip": "buyer Ip",
        "zipCode": "34580"
    },
    "shippingAddress": {
        "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34580"
    },
    "billingAddress": {
        "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34580"
    },
    "basketItems": [
        {
            "id": "BI101",
            "price": 1.0,
            "name": "Binocular",
            "category1": "Collectibles",
            "itemType": "PHYSICAL"
        }
    ]
}
```

### **Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749027773192,
    "conversationId": "2224",
    "token": "d9d9fc30-8178-4ca9-8f93-1b150f465da6",
    "signature": "a53e433a982bc9f927aed4e0383d083bd48de9cff343490ba7477f9964cfbfb1",
    "payWithIyzicoPageUrl": "https://sandbox-ode.iyzico.com/sdk?token=d9d9fc30-8178-4ca9-8f93-1b150f465da6&lang=tr",
    "tokenExpireTime": 600,
    "tokenExpireDate": 1749028373178
}
```

{% endtab %}

{% tab title="403" %}

```json
{
    "status": "failure",
    "errorCode": "5062",
    "errorMessage": "Total item price must be equal to price",
    "locale": "en",
    "systemTime": 1750240390554,
    "conversationId": "deviyzico"
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

<table><thead><tr><th>Parameter </th><th valign="middle">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td valign="middle">String</td><td>Service response result. (success / failure)</td></tr><tr><td><code>locale</code></td><td valign="middle">String</td><td>Language (default: tr).</td></tr><tr><td><code>systemTime</code></td><td valign="middle">Long</td><td>Response system unix timestamp value.</td></tr><tr><td><code>conversationId</code></td><td valign="middle">String</td><td>If set, conversation ID to match request and response.</td></tr><tr><td><code>token</code></td><td valign="middle">String</td><td>Unique value created for each pay with iyzico request. This token is also used to access the payment result.</td></tr><tr><td><code>payWithIyzicoPageUrl</code></td><td valign="middle">String</td><td>Unique link of pay with iyzico page. The end user should be directed to this page.</td></tr><tr><td><code>tokenExpireTime</code></td><td valign="middle">Long</td><td>Expiration time of the token and pay with iyzico page.</td></tr><tr><td><code>tokenExpireDate</code></td><td valign="middle">Long</td><td>The date when the token will expire in the Epoch timeframe.</td></tr><tr><td><code>errorCode</code></td><td valign="middle">String</td><td>Error code if service response status is failure.</td></tr><tr><td><code>errorMessage</code></td><td valign="middle">String</td><td>If the operation is erroneous, this is a message detailing the error, with language support according to the locale parameter.</td></tr></tbody></table>


---

# 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/payment-methods/tokenization/tokenization-integration/pay-with-iyzico.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.