# Tokenization Integration

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

[**Pay with iyzico**](https://docs.iyzico.com/en/payment-methods/tokenization/tokenization-integration/pay-with-iyzico)

\
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

* [ ] &#x20;**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.
* [ ] &#x20;**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

1. Requests sent to iyzico services must comply with iyzico’s authentication framework.
2. To initiate a session for a member, merchants must use the [Pay with iyzico (PWI)](https://docs.iyzico.com/en/payment-methods/tokenization/tokenization-integration/pay-with-iyzico) services. A session is created upon a successful payment made through PWI.
3. For payments made via Pay with iyzico (PWI), session and member information can be retrieved using the “[Payment and Session Retrieval](https://docs.iyzico.com/en/payment-methods/tokenization/tokenization-integration/retrieve-payment-detail-and-session-info)” service. The session token and member identifier must be stored by the merchant. These values are required for obtaining an access token and for performing subsequent payment operations.
4. To obtain an access token using the session token and member information, the **"**[**Access Token Retrieval**](https://docs.iyzico.com/en/payment-methods/tokenization/tokenization-integration/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.
5. To retrieve the member’s most recent payment details, the **"**[**Retrieve Last Payment Information**](https://docs.iyzico.com/en/payment-methods/tokenization/tokenization-integration/last-payment-detail-info)**"** service is used. The access token is required at this stage.
6. To process a payment using the tokenized last payment method, the merchant must send a payment request via [**Single API**](https://docs.iyzico.com/en/payment-methods/tokenization/tokenization-integration/initialize-payment-with-session), selecting the desired payment method.

{% hint style="info" %}
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.
{% endhint %}

### Sample Case

### Authentication

You can visit the [authentication](https://docs.iyzico.com/en/getting-started/preliminaries/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

```javascript
{
    "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": "sandboxtest0@gmail.com",
        "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

```json
{
    "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

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

#### Response

```json
{
    "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": "sandboxtest@gmail.com",
    "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

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

#### Response

```json
{
    "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

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

#### Response

```json
{
    "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

<table><thead><tr><th width="186.734375">Payment Types in Response</th><th width="166.5595703125">Parametre</th><th width="256.44921875">Description</th><th width="146.2894287109375">Payment Types in Request</th></tr></thead><tbody><tr><td>If the last payment was made using the wallet balance, the <code>paymentType</code> is returned as <code>"FUND"</code>.<br></td><td>FUND</td><td>This indicates that the payment was made via balance.</td><td>In this case, <code>"FUND"</code>must be sent as the <code>paymentType</code> in the next payment request.</td></tr><tr><td>If the last payment was made using a card, the <code>paymentType</code> is returned as <code>"CARD_PAYMENT"</code>.<br></td><td>CARD_PAYMENT</td><td>This indicates that the payment was made via card.</td><td>For 2D transactions, <code>"NON3D"</code> should be sent.<br>For 3DS transactions, <code>"3DS"</code> should be sent.</td></tr></tbody></table>

#### 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

```json
{
    "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": "sandboxtest@gmail.com",
        "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

```json
{
    "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"
}
```

{% hint style="info" %}
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.
  {% endhint %}

{% hint style="info" %}
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.
{% endhint %}

### 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 | <p>Indicates the type of request. Possible values are:</p><p>PWI\_TKN\_FUND<br></p> |
| NON3D      | iyziEventType | PWI\_TKN\_AUTH                                                                      |
| 3DS        | iyziEventType | PWI\_TKN\_THREEDS\_AUTH                                                             |