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.

Even if the value sent in the paymentType field is "NON3D", due to iyzico’s dynamic 3DS structure, the transaction may still be processed as 3DS if required, and the threeDSHtmlContent field may be returned in the response schema.

Card Payment Service

POST 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

Parameter
Type
Mandatory
Description

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"
}

threeDSHtmlContent is an HTML-formatted form returned by iyzico to initiate the 3D Secure authentication flow for card payments. This content is used to redirect the user to the 3D authentication screen of their card-issuing bank. In this case, the user must be redirected to the 3D authentication process.

3DS Response

Parameter
Type
Description

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

Parametre İsmi
Tip
Açıklama

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