Card Payment
This service is used to perform card payments via the tokenization payment method.
If the paymentType returned from the Retrieve Last Payment Information service is "CARD_PAYMENT", this payment service should be triggered.
Card Payment Service
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
sessionToken
String
Yes
This is the session key information of the payment transaction made by the Member in the same payment type.
memberIdentifier
String
Yes
Member unique key information. This key is used for member information in payment transactions.
conversationId
String
No
A value that you can send during the request and receive at the end can be used to match request/response. The most common use case is the merchant's order number.
locale
String
No
Language (default: tr)
paymentType
String
Yes
Indicates the type of payment to be performed. For card payments, it should be sent as either "3DS" or "NON3D".
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
No
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
3DS Request Body
{
"sessionToken": "{{sessionToken}}",
"memberIdentifier": "{{memberIdentifier}}",
"conversationId": "conversationId",
"locale": "en",
"paymentType": "3DS",
"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"
}
]
}Örnek 3DS Yanıtı
{
"status": "success",
"locale": "EN",
"systemTime": 1751972806160,
"conversationId": "conversationId",
"sessionToken": "84fcbaec-ab42-4043-bfcb-1baba563d9a5",
"paymentId": 24447594,
"threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrMTM0LTU3NDkzMjA2NjE0MjE5OTdpeXppb3JkIj4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImJpbiIgdmFsdWU9IjQ2MDM0NSI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJzdWNjZXNzVXJsIiB2YWx1ZT0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L2l5emlwb3MvY2hlY2tvdXRmb3JtL2NhbGxiYWNrM2RzL3N1Y2Nlc3MvNSI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJmYWlsdXJlVXJsIiB2YWx1ZT0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L2l5emlwb3MvY2hlY2tvdXRmb3JtL2NhbGxiYWNrM2RzL2ZhaWx1cmUvNSI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJjb25maXJtYXRpb25VcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvbW9jay9jb25maXJtM2RzIj4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9IlBhUmVxIiB2YWx1ZT0iNDlmN2Q5YjctMDRjYi00OTBhLThkZWEtZjNlODBlYjg5N2NiIj4KPC9mb3JtPgo8c2NyaXB0IHR5cGU9InRleHQvamF2YXNjcmlwdCI+CiAgICBkb2N1bWVudC5nZXRFbGVtZW50QnlJZCgiaXl6aWNvLTNkcy1mb3JtIikuc3VibWl0KCk7Cjwvc2NyaXB0Pgo8L2JvZHk+CjwvaHRtbD4=",
"checkoutToken": "b868c1de-9633-4e61-91d8-71bf74754134",
"signature": "97aeba0e26d67fbcb6ec1381704e36d44f1f2e8c0ae3b0ac7fe8239a508052f2"
}3DS Response
status
String
Returns the result of the request. It can return either the value "success" or "failure".
locale
String
The request is sent, the response is returned in the language.
systemTime
Long
Unix time value at the time of the request.
conversationId
String
The value sent during the request is transmitted back exactly as it was.
sessionToken
String
This is the session key information that the Member pays in the same payment type.
paymentId
Long
The uniq payment number generated by iyzico.
paymentStatus
String
Payment status information. It can take "success" and "failure"
threeDSHtmlContent
String
3D verification screen in HTML format.
checkoutFormToken
String
The checkoutform token value of the transaction.
signature
String
It is the signature value that can be signature verified.
NON3D Request Body
{
"sessionToken": "{{sessionToken}}",
"memberIdentifier": "{{memberIdentifier}}",
"conversationId": "conversationId",
"locale": "en",
"paymentType": "NON3D",
"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"
}
]
}NON3D Response
{
"status": "success",
"locale": "en",
"systemTime": 1751974361992,
"conversationId": "conversationId",
"sessionToken": "84fcbaec-ab42-4043-bfcb-1baba563d9a5",
"paymentId": 24447819,
"paymentStatus": "SUCCESS",
"callbackUrl": "callbackUrl",
"checkoutToken": "0ef89199-f3fe-44f8-a362-a2e88be6503e",
"price": 1.00000000,
"paidPrice": 1.00,
"installment": 1,
"fraudStatus": 1,
"merchantCommissionRate": 0E-8,
"merchantCommissionRateAmount": 0E-8,
"iyziCommissionRateAmount": 0.01750000,
"iyziCommissionFee": 0E-8,
"cardAssociation": "VISA",
"cardFamily": "Denizbank CC",
"cardType": "CREDIT_CARD",
"binNumber": "460345",
"lastFourDigits": "0000",
"currency": "TRY",
"itemTransactions": [
{
"itemId": "BI101",
"paymentTransactionId": "26445926",
"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-07-09 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"
}
}
],
"authCode": "317070",
"phase": "AUTH",
"hostReference": "mock00003iyzihostrfn",
"signature": "fbcf1fdb5ef4008f04bf57df383bebb6249d34600bfefff86769be1c5ec13b59"
}NON3D Response Parameter
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.
sessionToken
String
This is the session key information of the payment transaction made by the Member in the same payment type.
paymentStatus
String
Payment response result (SUCCESS, FAILURE).
checkoutToken
String
The token value of the checkoutform used in the checkout process.
paymentId
String
ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests).
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
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.
callbackUrl
String
Merchant callback URL for payment result notification. callBackUrl address should have SSL.
Last updated