Tokenization Integration

With the iyzico tokenization model, you can integrate the Pay with iyzico method:

Pay with iyzico is a digital payment method that allows users to complete their online purchases quickly, easily, and securely. Thanks to this service provided by iyzico, users can make payments without the need to re-enter their card details for each transaction. They can also continue to benefit from additional features such as installment options offered by iyzico.

This payment method aims to improve the shopping experience by providing a secure payment infrastructure for both users and businesses. You can initiate the Pay with iyzico payment method by directing the end user to log in to their iyzico account.

Key Definitions

Member : Users who register on the platform using the Pay with iyzico service are referred to as "members." Members can benefit from iyzico's digital wallet and payment solutions and complete transactions securely and quickly.
Payment Type : There are two payment types that can be used within the scope of tokenization: Balance and Card payments.
- Balance Payment: Payments made using the current balance in the user's iyzico wallet.
- Card Payment: Payments made using a previously saved or newly added credit/debit card.
Session: Represents the process of payments initiated and completed by a member through our merchant using the same payment type. A session is represented by a unique value known as a session token.

Pre-Integration Requirements

The merchant must have their IP addresses whitelisted by iyzico in order to use this service.
The merchant's account settings must be configured appropriately for service activation.

Steps

Requests sent to iyzico services must comply with iyzico’s authentication framework.
To initiate a session for a member, merchants must use the Pay with iyzico (PWI) services. A session is created upon a successful payment made through PWI.
To retrieve the session and member information related to a payment made via PWI, the "Payment and Session Retrive" service is used. The session token and member identifier must be securely stored by the merchant, as they will be required later for obtaining an access token and initiating further payments. The generated session token has a limited validity period, which may vary per merchant.
To obtain an access token using the session token and member information, the "Access Token Retrieval" service must be used. The access token is required to retrieve the user's most recent payment information and to process payments using tokenized data. Note: The access token is short-lived.
To retrieve the member’s most recent payment details, the "Retrieve Last Payment Information" service is used. The access token is required at this stage.
To process a payment using the tokenized last payment method, the merchant must send a payment request via Single API, selecting the desired payment method.

Each Pay with iyzico operation terminates the current session and starts a new one. The payment method cannot be changed within an active session; initiating a new Pay with iyzico operation is required to change the method. This creates a new session, and the payment flow continues through this new session.

Sample Case

Authentication

You can visit the authentication page for details.

Pay with iyzico (PWI) Payment and Session Initialization

Below is an example request and response for an initialize operation performed via Pay with iyzico (PWI). To allow the member to complete the payment and to create a session, the Pay with iyzico service must be initialized.

Request

{
    "paidPrice": 1.0,
    "locale": "tr",
    "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": "[email protected]",
        "gsmNumber": "+9055555555",
        "registrationAddress": "Adres",
        "city": "Istanbul",
        "country": "Turkey",
        "ip": "buyer Ip",
        "zipCode": "34580"
    },
    "shippingAddress": {
        "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34580"
    },
    "billingAddress": {
        "address": "Altunizade Mah. İ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": "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
}

Payment and Session Retrieve

This service returns the details of the payments made by the member within the session, along with session information.

Request

{
    "checkoutFormToken": "{{checkoutToken}}",
    "locale": "tr",
    "conversationId": "conversationId"
}

Response

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749032413350,
    "conversationId": "conversationId",
    "token": "e54b957b-a153-410c-8761-79c9bd4ff44f",
    "callbackUrl": "https://merchant-callback.com",
    "paymentStatus": "SUCCESS",
    "price": 1.00000000,
    "paidPrice": 1.00000000,
    "installment": 1,
    "paymentId": "24259238",
    "memberEmail": "[email protected]",
    "memberGsmNumber": "+905555555555",
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.01750000,
    "iyziCommissionFee": 0E-8,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Advantage",
    "binNumber": "550472",
    "lastFourDigits": "0003",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26268394",
            "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": 0E-8,
            "blockageResolvedDate": "2025-06-05 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "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": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "054626",
    "phase": "AUTH",
    "hostReference": "mock00034iyzihostrfn",
    "signature": "a77fac0a954181b9816bac2d0ba55047d2bfb1934d8efaa6de39b93b91bc9d6c",
    "sessionInfo": {
        "sessionToken": "f403ef2f-fb08-4111-afd6-495811ef6b25",
        "sessionStatus": "ACTIVE",
        "memberIdentifier": "f1409923-57cb-468f-8df2-704ea02075e3",
        "paymentType": "CARD_PAYMENT"
    }
}

Access Token Retrieval

The accessToken required to trigger the payment and retrieve the latest payment details is obtained through this service.

Request

{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "locale": "tr",
    "conversationId": "test"
}

Response

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749027862133,
    "conversationId": "test",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiItIiwic2NvcGUiOlsidGhpcmRQYXJ0eVNlc3Npb24iXSwic2Vzc2lvblRva2VuIjoiZDUzZWRiNzItNTNmMy00NmY0LTk5NWQtNDM1NzBhOTdiZDg4IiwiZXhwIjoxNzQ5MDI4MjIyLCJhdXRob3JpdGllcyI6WyJwd2lfdHBfc2Vzc2lvbl9jYXJkX2F1dGgiLCJwd2lfdHBfc2Vzc2lvbl9pbml0M2RzX2F1dGgiLCJwd2lfdHBfc2Vzc2lvbl9sYXN0X3BheW1lbnRfcmV0cmlldmUiLCJwd2lfdHBfc2Vzc2lvbl9mdW5kX2F1dGgiXSwianRpIjoiMTUwODdmNTgtZGE4Yy00OTFhLWFjN2QtYmYyODI2ODNmMGRlIiwiY2xpZW50X2lkIjoidGhpcmRQYXJ0eVNlc3Npb25DbGllbnQifQ.YC5McE1SdXrPeCpljrMU1X3kzc3FV7I8DoZ5G0qcS30"
}

Last Payment Detail Info

This service returns the details of the member’s most recent payment. It must be called using the accessToken obtained from the Access Token Retrieval service.

Request

{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "locale": "tr",
    "conversationId": "conversationId"
}

Response

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1749032543970,
    "conversationId": "conversationId",
    "card": {
        "cardHolderName": "John Doe",
        "cardAssociation": "MASTER_CARD",
        "cardFamily": "Advantage",
        "binNumber": "55047200",
        "lastFourDigits": "0003",
        "cardBankName": "HSBC",
        "cardType": "CREDIT_CARD",
        "expireMonth": "05",
        "expireYear": "2026",
        "expired": false,
        "willExpireSoon": false
    },
    "paymentType": "CARD_PAYMENT",
    "sessionToken": "f403ef2f-fb08-4111-afd6-495811ef6b25",
    "token": "e54b957b-a153-410c-8761-79c9bd4ff44f",
    "paymentId": 24259238
}

Payment Types

Payment Types in Response

Parametre

Description

Payment Types in Request

If the last payment was made using the wallet balance, the paymentType is returned as "FUND".

FUND

This indicates that the payment was made via balance.

In this case, "FUND"must be sent as the paymentType in the next payment request.

If the last payment was made using a card, the paymentType is returned as "CARD_PAYMENT".

CARD_PAYMENT

This indicates that the payment was made via card.

For 2D transactions, "NON3D" should be sent. For 3DS transactions, "3DS" should be sent.

Auth

The last used payment type is utilized to determine how the next payment should be processed. In the sample implementation, since the paymentType is returned as "CARD_PAYMENT", a card payment example is provided.

Request

{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "conversationId": "conversationId",
    "locale": "tr",
    "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. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34580"
    },
    "billingAddress": {
        "address": "Altunizade Mah. İ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": "tr",
    "systemTime": 1749027890082,
    "conversationId": "conversationId",
    "sessionToken": "d53edb72-53f3-46f4-995d-43570a97bd88",
    "paymentId": 24258864,
    "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtODc2NzgxNDM2MDk1ODAxMGl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTg5MDA0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jaGVja291dGZvcm0vY2FsbGJhY2szZHMvc3VjY2Vzcy8yNyI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJmYWlsdXJlVXJsIiB2YWx1ZT0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L2l5emlwb3MvY2hlY2tvdXRmb3JtL2NhbGxiYWNrM2RzL2ZhaWx1cmUvMjciPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iY29uZmlybWF0aW9uVXJsIiB2YWx1ZT0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svY29uZmlybTNkcyI+CiAgICA8aW5wdXQgdHlwZT0iaGlkZGVuIiBuYW1lPSJQYVJlcSIgdmFsdWU9IjE4ZThlZGVhLTY2ZjgtNDg4NS05OTNkLWIyYTQ5MzFlNTY0MCI+CjwvZm9ybT4KPHNjcmlwdCB0eXBlPSJ0ZXh0L2phdmFzY3JpcHQiPgogICAgZG9jdW1lbnQuZ2V0RWxlbWVudEJ5SWQoIml5emljby0zZHMtZm9ybSIpLnN1Ym1pdCgpOwo8L3NjcmlwdD4KPC9ib2R5Pgo8L2h0bWw+",
    "checkoutToken": "1479d5ba-d52d-4fae-8f1c-9d9c75991f2a",
    "signature": "40c72c0d631861c7f1454baffc8f141e7947699dbe22c14ca40f75bdf775fae6"
}

In transactions where the paymentType is sent as "3DS" and 3D Secure authentication is required, the response will include the threeDSHtmlContent field. This field provides the HTML content required to initiate the 3D Secure verification step, encoded in Base64 format. To ensure the authentication process proceeds correctly:

The threeDSHtmlContent must be decoded from Base64.
The decoded HTML content must be displayed to the user in a web page (e.g., via an iframe or directly embedded HTML). This step is mandatory to redirect the user to their bank’s 3D Secure verification screen.

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. In such cases, the threeDSHtmlContent field may be returned in the response schema.

Webhook

After tokenization wallet payments, the eventType parameter included in the webhook notifications sent by iyzico to the merchant’s webhookUrl will vary depending on the type of payment. These webhook notifications can be categorized based on this parameter. For more details, please visit our webhook documentation page.

Ödeme Tipi

Parametre

Açıklama

FUND

iyziEventType

Indicates the type of request. Possible values are:

PWI_TKN_FUND

NON3D

iyziEventType

PWI_TKN_AUTH

3DS

iyziEventType

PWI_TKN_THREEDS_AUTH

PreviousTokenization NextPay With iyzico

Last updated 6 hours ago