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
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.
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. İ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": "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
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. İ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": "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"
}
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.
FUND
iyziEventType
Indicates the type of request. Possible values are:
PWI_TKN_FUND
NON3D
iyziEventType
PWI_TKN_AUTH
3DS
iyziEventType
PWI_TKN_THREEDS_AUTH
Last updated