# Balance Payment

This service is used to perform API-to-API balance payments.\
If the `paymentType` value returned from the **Retrieve Last Payment Information** service is `"FUND"`, this service should be used.

## Fund Payment

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

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |
| access-token  | `{{accessToken}}`  |

### **Request Parameters**

<table><thead><tr><th width="219.78515625">Parameter</th><th>Type</th><th>Mandatory</th><th width="193.8878173828125">Açıklama</th></tr></thead><tbody><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>locale</code></td><td>String</td><td>No</td><td>Language (default: tr)</td></tr><tr><td><code>paymentType</code></td><td>String</td><td>Yes</td><td>Indicates the payment type. For balance payments, it should be sent as <code>"FUND"</code>.</td></tr><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>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>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>paymentGroup</code></td><td>String</td><td>No</td><td>Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION.</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>Basket Item ID. It can take a maximum of 500 characters.</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><tr><td><code>sessionToken</code></td><td>String</td><td>Yes</td><td>This is the session key information that the Member pays in the same payment type.</td></tr><tr><td><code>memberIdentifier</code></td><td>String</td><td>Yes</td><td>Member unique key information. This key is used for member information in payment transactions.</td></tr></tbody></table>

### Request

```javascript
{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "conversationId": "conversationId",
    "locale": "en",
    "paymentType": "FUND",
    "paidPrice": 1.0,
    "price": 1.0,
    "callbackUrl": "callbackUrl",
    "paymentGroup": "PRODUCT",
    "currency": "TRY",
    "basketId": "B67832",
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864111",
        "email": "sandboxtest0@gmail.com",
        "gsmNumber": "+905555555555",
        "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": "en",
    "systemTime": 1748553300302,
    "conversationId": "conversationId",
    "sessionToken": "16f60166-74ba-4e5c-ac52-31b5762652d4",
    "paymentId": 24233528,
    "paymentStatus": "SUCCESS",
    "checkoutToken": "7ce32610-9851-4b16-939a-5d4beae75475",
    "price": 1.00000000,
    "paidPrice": 1.00000000,
    "installment": 1,
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.01750000,
    "iyziCommissionFee": 0E-8,
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26241258",
            "transactionStatus": 2,
            "price": 1.00000000,
            "paidPrice": 1.00000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.01750000,
            "iyziCommissionFee": 0E-8,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2025-05-31 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.98250000,
            "convertedPayout": {
                "paidPrice": 1.00000000,
                "iyziCommissionRateAmount": 0.01750000,
                "iyziCommissionFee": 0E-8,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.98250000,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "phase": "AUTH",
    "signature": "096cf80a59d611f1702803b91bc073300e9a57a5ab47e4a839e598fc13af3d5b"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "260018",
    "errorMessage": "Session payment type is not matched.",
    "locale": "en",
    "systemTime": 1751956747198
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

<table><thead><tr><th>Parametre İsmi</th><th width="103.33333333333331">Tip</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Service response result (success / failure).</td></tr><tr><td><code>locale</code></td><td>String</td><td>Language. Default: TR<br>Can take TR and EN values.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>Response system timestamp value.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>If set, conversation ID to match request and response.</td></tr><tr><td><code>checkoutToken</code></td><td>String</td><td>The token value of the checkoutform used in the checkout process.</td></tr><tr><td><code>paymentStatus</code></td><td>String</td><td>Payment response result (SUCCESS, FAILURE).</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Total amount of basket.</td></tr><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system.</td></tr><tr><td><code>installment</code></td><td>Integer</td><td><p>The installment information of the payment.<br>Returns <strong>1</strong> for single-payment transactions.<br></p><p>Valid values: <strong>1, 2, 3, 6, 9, 12</strong>.</p></td></tr><tr><td><code>fraudStatus</code></td><td>Integer</td><td><p>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 <strong>1</strong>; for <strong>0</strong>, wait for notification.<br></p><ul><li><strong>1</strong>: Approved</li><li><strong>0</strong>: In review</li><li><strong>-1</strong>: Rejected</li></ul></td></tr><tr><td><code>paymentId</code></td><td>String</td><td>ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests).</td></tr><tr><td><code>merchantCommissionRate</code></td><td>Decimal</td><td>Merchant commission rate (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate = 10).</td></tr><tr><td><code>merchantCommissionRateAmount</code></td><td>Decimal</td><td>Merchant commission rate amount (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate amount = 10).</td></tr><tr><td><code>iyziCommissionRateAmount</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>basketId</code></td><td>String</td><td>Merchant's basket ID.</td></tr><tr><td><code>errorCode</code></td><td>String</td><td>Error code if service response status is failure.</td></tr><tr><td><code>errorMessage</code></td><td>String</td><td>Error message if service response status is failure.</td></tr><tr><td><code>errorGroup</code></td><td>String</td><td>Error group if service response status is failure.</td></tr><tr><td><code>currency</code></td><td>String</td><td>The currency in which payment is received.</td></tr><tr><td><code>itemId (ItemTransactions)</code></td><td>String</td><td>Item ID of each item in basket.</td></tr><tr><td><code>transactionStatus (ItemTransactions)</code></td><td>Integer</td><td>The status of the payment breakdown. Returns 0 if the payment is under fraud check, in which case the fraudStatus is also 0. -1 if the payment is rejected after the fraud check. In the marketplace model, this value returns 1 until the product is approved. If the product is approved in the marketplace model, this value is 2. Valid values: 0, -1, 1, 2.</td></tr><tr><td><code>paymentTransactionId (ItemTransactions)</code></td><td>String</td><td>Ödeme kırılımına ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödeme kırılımının iadesi, onayı, onay geri çekmesi ve iyzico ile iletişimde kullanılır. Tercihen itemId ile ilişkili bir şekilde tutulmalıdır.</td></tr><tr><td><code>price (ItemTransactions)</code></td><td>Decimal</td><td>Item price of each item in basket.</td></tr><tr><td><code>paidPrice (ItemTransactions)</code></td><td>Decimal</td><td>Captured amount from card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>merchantCommissionRate (ItemTransactions)</code></td><td>Decimal</td><td>The ratio of the maturity/commission rate applied by the merchant, broken down by segment.</td></tr><tr><td><code>merchantCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>Amount of the maturity/commission amount applied by the merchant, broken down on a breakdown basis.</td></tr><tr><td><code>iyziCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>blockageRate (ItemTransactions)</code></td><td>Decimal</td><td>Merchant blockage rate on a breakdown basis. iyzico may apply transaction-based blockage to the merchant according to the iyzico - merchant agreement. This blockage is to prevent merchant fraud risk, the money is kept at iyzico during the blockage period and sent to the merchant after this period.</td></tr><tr><td><code>blockageRateAmountMerchant (ItemTransactions)</code></td><td>Decimal</td><td>The amount of the merchant blockage amount reflected to the merchant on a breakdown basis. The blockage amount is reflected to the merchant as much as possible. If the blockage amount is greater than the merchant amount, then it is also reflected to the sub-merchant.</td></tr><tr><td><code>blockageResolvedDate (ItemTransactions)</code></td><td>String</td><td>Date of unblocking by transaction. yyyy-MM-dd HH:mm:ss format, for example 2015-10-19 14:36:52.</td></tr><tr><td><code>merchantPayoutAmount (ItemTransactions)</code></td><td>Decimal</td><td>Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)</td></tr><tr><td><code>paidPrice(convertedPayout)</code></td><td>Decimal</td><td>Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>iyziCommissionRateAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission rate amount based on each item.</td></tr><tr><td><code>iyziCommissionFee (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission fee based on each item.</td></tr><tr><td><code>blockageRateAmountMerchant (convertedPayout)</code></td><td>Decimal</td><td>The amount of the merchant blockage amount reflected to the merchant on a breakdown basis. The blockage amount is reflected to the merchant as much as possible. If the blockage amount is greater than the merchant amount, then it is also reflected to the sub-merchant.</td></tr><tr><td><code>merchantPayoutAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions).</td></tr><tr><td><code>iyziConversationRate (convertedPayout)</code></td><td>Decimal</td><td>iyzico conversation rate.</td></tr><tr><td><code>iyziConversationRateAmount (convertedPayout)</code></td><td>Decimal</td><td>For this breakdown, the amount to be sent to the merchant after deducting iyzico transaction fee, commission amount and blockages.</td></tr><tr><td><code>currency (convertedPayout)</code></td><td>String</td><td>Currency for payout conversion.</td></tr><tr><td><code>authCode</code></td><td>String</td><td>uniq value produced by iyzico.</td></tr><tr><td><code>phase</code></td><td>String</td><td>Payment phase information. Takes the value AUTH.</td></tr><tr><td><code>signature</code></td><td>String</td><td>The signature value that can be used for signature verification.</td></tr><tr><td><code>cardType</code></td><td>String</td><td>Returns only for card payments. If the payment card is a local card, it returns the card type information. It takes the values DEBIT_CARD and CREDIT_CARD.</td></tr><tr><td><code>cardAssociation</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the organization to which the card belongs. Valid values: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY</td></tr><tr><td><code>cardFamily</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the family to which the card belongs. Valid values: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage</td></tr><tr><td><code>binNumber</code></td><td>String</td><td>First 6 digit of card.</td></tr><tr><td><code>lastFourDigits</code></td><td>String</td><td>Last 4 digits of the payment card.</td></tr><tr><td><code>sessionToken</code></td><td>String</td><td>This is the session key information of the payment transaction made by the Member in the same payment type.</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/initialize-payment-with-session/balance-payment.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.