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
POST https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/checkout/auth
Headers
Content-Type
application/json
Authorization
Authorization
access-token
{{accessToken}}
Request Parameters
conversationId
String
No
Conversation ID to match request and response.
locale
String
No
Language (default: tr)
paymentType
String
Yes
Indicates the payment type. For balance payments, it should be sent as "FUND".
paidPrice
Decimal
Yes
Final amount (including installment fee) that will be charged to customer’s card.
price
Decimal
Yes
Total amount of basket. The sum of basket items’ amount must be equal to the price of basket.
callbackUrl
String
Yes
Merchant callback URL for payment result notification. callBackUrl address should have SSL.
paymentGroup
String
No
Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION.
currency
String
Yes
Currency (default: TRY). Alternatively, you can set USD, EUR, GBP .
basketId
String
No
Merchant's basket ID.
buyerId
String
Yes
ID of buyer.
buyerName
String
Yes
Name of buyer.
buyerSurname
String
Yes
Surname of buyer.
identityNumber
String
Yes
Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants.
email
String
Yes
Email of buyer.
gsmNumber
String
No
GSM Number of buyer.
registrationAddress
String
Yes
Registration address of buyer.
city
String
Yes
City of buyer.
country
String
Yes
Country of buyer.
IP
String
No
IP of buyer.
zipCode
String
Yes
Zip code of buyer.
address(shippingAddress)
String
Yes
Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory
contactName(shippingAddress)
String
Yes
Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.
city(shippingAddress)
String
Yes
City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.
country(shippingAddress)
String
Yes
Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.
zipCode(shippingAddress)
String
Yes
Zip code of shipping address.
address(billingAddress)
String
Yes
Address details of billing address.
contactName(billingAddress)
String
Yes
Contact name of billing address.
city(billingAddress)
String
Yes
City name of billing address.
country(billingAddress)
String
Yes
Country name of billing address.
basketItemId
String
Yes
Basket Item ID. It can take a maximum of 500 characters.
basketItemPrice
String
Yes
Price value for each item. Must be greater than zero.
basketItemName
String
Yes
Name of the item in the basket.
basketItemCategory1
String
Yes
Category 1 for item in the basket.
basketItemCategory2
String
No
Category 2 for item in the basket.
basketItemItemType
String
Yes
Item Type. Valid values are PHYSICAL,VIRTUAL
sessionToken
String
Yes
This is the session key information that the Member pays in the same payment type.
memberIdentifier
String
Yes
Member unique key information. This key is used for member information in payment transactions.
Request
{
"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": "[email protected]",
"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
{
"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"
}Response Parameters
status
String
Service response result (success / failure).
locale
String
Language. Default: TR Can take TR and EN values.
systemTime
Long
Response system timestamp value.
conversationId
String
If set, conversation ID to match request and response.
checkoutToken
String
The token value of the checkoutform used in the checkout process.
paymentStatus
String
Payment response result (SUCCESS, FAILURE).
price
Decimal
Total amount of basket.
paidPrice
Decimal
Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system.
installment
Integer
Ödemenin taksit bilgisi, tek çekim için 1 döner. Geçerli değerler: 1, 2, 3, 6, 9, 12
paymentId
String
ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests).
merchantCommissionRate
Decimal
Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10).
merchantCommissionRateAmount
Decimal
Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10).
iyziCommissionRateAmount
Decimal
iyzico commission rate amount for payment transaction.
iyziCommissionFee
Decimal
iyzico commission fee for payment transaction.
basketId
String
Merchant's basket ID.
errorCode
String
Error code if service response status is failure.
errorMessage
String
Error message if service response status is failure.
errorGroup
String
Error group if service response status is failure.
currency
String
The currency in which payment is received.
itemId (ItemTransactions)
String
Item ID of each item in basket.
transactionStatus (ItemTransactions)
Integer
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.
paymentTransactionId (ItemTransactions)
String
Ö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.
price (ItemTransactions)
Decimal
Item price of each item in basket.
paidPrice (ItemTransactions)
Decimal
Captured amount from card based on each item. Merchants should keep paidPrice in their system.
merchantCommissionRate (ItemTransactions)
Decimal
The ratio of the maturity/commission rate applied by the merchant, broken down by segment.
merchantCommissionRateAmount (ItemTransactions)
Decimal
Amount of the maturity/commission amount applied by the merchant, broken down on a breakdown basis.
iyziCommissionRateAmount (ItemTransactions)
Decimal
iyzico commission rate amount for payment transaction.
iyziCommissionFee (ItemTransactions)
Decimal
iyzico commission fee for payment transaction.
blockageRate (ItemTransactions)
Decimal
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.
blockageRateAmountMerchant (ItemTransactions)
Decimal
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.
blockageResolvedDate (ItemTransactions)
String
Date of unblocking by transaction. yyyy-MM-dd HH:mm:ss format, for example 2015-10-19 14:36:52.
merchantPayoutAmount (ItemTransactions)
Decimal
Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
paidPrice(convertedPayout)
Decimal
Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.
iyziCommissionRateAmount (convertedPayout)
Decimal
Converted iyzico commission rate amount based on each item.
iyziCommissionFee (convertedPayout)
Decimal
Converted iyzico commission fee based on each item.
blockageRateAmountMerchant (convertedPayout)
Decimal
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.
merchantPayoutAmount (convertedPayout)
Decimal
Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions).
iyziConversationRate (convertedPayout)
Decimal
iyzico conversation rate.
iyziConversationRateAmount (convertedPayout)
Decimal
For this breakdown, the amount to be sent to the merchant after deducting iyzico transaction fee, commission amount and blockages.
currency (convertedPayout)
String
Currency for payout conversion.
authCode
String
uniq value produced by iyzico.
phase
String
Payment phase information. Takes the value AUTH.
signature
String
The signature value that can be used for signature verification.
cardType
String
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.
cardAssociation
String
Returns only for card payments. If the payment card is a local card, the organization to which the card belongs. Valid values: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY
cardFamily
String
Returns only for card payments. If the payment card is a local card, the family to which the card belongs. Valid values: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
binNumber
String
First 6 digit of card.
lastFourDigits
String
Last 4 digits of the payment card.
sessionToken
String
This is the session key information of the payment transaction made by the Member in the same payment type.
Last updated