# Welcome

Authentication for iyzico services aligns with Basic Auth principles, while enhancing security through a precise sequence of encryption techniques, including PKI string, Base64, and SHA-1 hashing.

It is our pleasure to extend a warm welcome to you as you explore our Developer Portal!

An experienced developer or embarking on your integration journey, our iyzico Developer Portal, where we are dedicated to democratize online payments, is meticulously crafted to offer you the tools and support needed for a seamless integration experience. 

Our commitment lies in ensuring that your integration with iyzico is efficient and hassle-free, while providing your customers with a smooth payment process. Here's what you can expect from our Developer Portal;

<table data-view="cards"><thead><tr><th data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/WATn3Y2XtSN6gSAkqOv9">/pages/WATn3Y2XtSN6gSAkqOv9</a></td></tr><tr><td><a href="/pages/4xgocZ5GCPCojfk53V6a">/pages/4xgocZ5GCPCojfk53V6a</a></td></tr><tr><td><a href="/pages/s7YKpLzL4dhPpkwXSbiS">/pages/s7YKpLzL4dhPpkwXSbiS</a></td></tr><tr><td><a href="/pages/nutuyLlFGaEYAxlw5IsU">/pages/nutuyLlFGaEYAxlw5IsU</a></td></tr><tr><td><a href="/pages/Fo4KvZi5ix3RCT9pwp65">/pages/Fo4KvZi5ix3RCT9pwp65</a></td></tr><tr><td><a href="/pages/ZgB2OnKATvy5XeTwSIsS">/pages/ZgB2OnKATvy5XeTwSIsS</a></td></tr></tbody></table>

Whether you are developing an e-commerce platform, a mobile application, or a subscription service, iyzico's Developer Portal serves as your gateway to effortlessly incorporating online payments into your business.

Thank you for joining us, and we look forward to supporting you every step of the way.


# Preliminaries

Processing a payment over iyzico services includes sequence of events.

Following pages have designed to accelerate your development stages regardless of programming languages. These resources provide basic level requirements and streamlined functions while enabling you to expedite your integration.

<table data-view="cards"><thead><tr><th data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/mRfXpvwACEQvd6o20m0v">/pages/mRfXpvwACEQvd6o20m0v</a></td></tr><tr><td><a href="/pages/19BoREI5VXROn8YuzMLc">/pages/19BoREI5VXROn8YuzMLc</a></td></tr><tr><td><a href="/pages/G6pZFMmhVn03Go0IRdfk">/pages/G6pZFMmhVn03Go0IRdfk</a></td></tr><tr><td><a href="/pages/FAorsn6KdSHibaSbihaD">/pages/FAorsn6KdSHibaSbihaD</a></td></tr><tr><td><a href="/pages/3n6g1U3iDPaXiwtvQRmj">/pages/3n6g1U3iDPaXiwtvQRmj</a></td></tr><tr><td><a href="/pages/1w1KUzIvbMhkFJ8pjGFH">/pages/1w1KUzIvbMhkFJ8pjGFH</a></td></tr></tbody></table>


# Sandbox

### Introduction

Here in this page, you'll have details of creating a Sandbox account and API credentials.

{% hint style="info" %}
If you already have a Sandbox, then please follow the [**link**](https://sandbox-merchant.iyzipay.com/auth/login) to login your account.
{% endhint %}

### Step-1 : Sign up for a Sandbox

Please refer following link to sign up a Sandbox account;

> [<mark style="color:blue;">https://sandbox-merchant.iyzipay.com/auth/register</mark>](https://sandbox-merchant.iyzipay.com/auth/register)

\
\
A Sandbox account offers you to manage everything from one simple panel. \
Each account comes with unique **merchantId** as well as two pairs of credentials, **API KEY** & **SECRET KEY,** relatively.

<table><thead><tr><th>KEY</th><th>VALUE</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>API Key</strong></td><td>sandbox-...</td><td></td></tr><tr><td><strong>Secret Key</strong></td><td>sandbox-...<br></td><td></td></tr></tbody></table>

{% hint style="info" %}
For the Sandbox, OTP is **123456** statically.
{% endhint %}

### Step-2 : Take Your Credentials

In iyzico services, you will be asked for authentication before making any transaction.\
To find out where;

1. Log in to your [**Sandbox Account**](https://sandbox-merchant.iyzipay.com/auth/login).
2. Follow the path **Settings > Merchant Settings** from the menu on the lef&#x74;**.**
3. Under the **Merchant Settings** page, go for API Keys section. \
   Once you click on **Show detail,** there are the magic begins.

<figure><img src="/files/6eAO7caQd8icc53b6LlE" alt=""><figcaption></figcaption></figure>

### Ready for Postman Collections

By now, you've setup your Sandbox Account and find out API credentials.

* Sandbox Account
* API Credentials

It is time for a closer look at APIs with our <mark style="color:blue;">**Postman Collections**</mark>.


# Authentication

Authorization is a security measure used to control access to iyzico services by users. This process involves authentication steps, and authorization methods typically utilize information such as passwords, keys, or biometric data. iyzico has two different authentication methods.

### [SHA256 Authentication](broken://pages/lEG2YdpeKelMPhGCIAaG)

SHA256 represents the 256-bit version of the Secure Hash Algorithm 2, which is considered a more secure authorization method. SHA256 uses a longer hash digest to provide a higher level of security and is often preferred for applications such as digital signatures, password authentication, and data integrity checks.

<br>


# HMACSHA256 Auth

Authentication for iyzico services aligns with Basic Auth principles, while enhancing security through a precise sequence of encryption techniques, including PKI string, Base64, HMAC and SHA-256 hashing

To access our API securely, authentication is required. Authentication is achieved through the inclusion of an `API Key` and `base64EncodedAuthorization` together in the header of your HTTP requests.

```http
"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"
```

**Example Request Header:**

```http
POST /payment/bin/check HTTP/1.1
Host: sandbox-api.iyzipay.com
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib3gtbDlNZDFHajNJWWNtdTROZGFXeGFTVW9Db1g3REM1UkEmcmFuZG9tS2V5OjEyMzQ1Njc4OSZzaWduYXR1cmU6MDc5ZGY0YjI0MjZmYzdmNDIwOGQ4ZjIyZmJjMDM0OTc5NDAxOWY4Y2UyYjA3MTFkZTc4MDhiNDg3NGY0ZTc5Ng==
Content-Type: application/json
x-iyzi-rnd: 123456789 // x-iyzi-rnd used to be random key from previous SHA1 Authentication
```

## **Overview**

Here's a breakdown of the required components:

* **apiKey**: Your unique API key assigned to your account.
* **secretKey**: Your secret key associated with your account.
* **x-iyzi-rnd**: A randomly generated number by merchants that included in the request header for each API call. (x-iyzi-rnd used to be random key from previous SHA1 Authentication)
* **encryptedData:** The encrypted version of the request payload parameters with HMACSHA256.

Authentication can be divided into three sequential steps:

1. encryptedData
2. base64Encoded
3. Authorization

### 1. **encryptedData**

The `encryptedData` represents a encrypted version of the request payload, the process entails generating a hash using HMACSHA256 encryption.

The signature is generated using the following formula, relatively;

```
HMACSHA256(randomKey + uri.path + request.body, secretKey)
```

{% hint style="info" %}
**`randomKey`**`;`&#x20;

* could be either x-iyzi-rnd used to be random key from previous SHA1 Authentication.
* Or please do not hesitate generate randomly.
  {% endhint %}

With in a sample, below you may find a dummy [Bin Check](https://docs.iyzico.com/v/en/advanced/installment-and-bin-service#bin-service-request-1) request curl;

```
curl 
--location --request POST 'https://api.iyzipay.com/payment/bin/check' \
--header 'Authorization: IYZWSv2 ***' \
--header 'x-iyzi-rnd: 123456789' \ 
--header 'Content-Type: application/json' \
--data-raw '{
    "locale":"tr",
    "binNumber":"535805",
    "conversationId": "docsTest-v1"
}'
```

`encryptedData` for that Bin Check request above is;

```
079df4b2426fc7f4208d8f22fbc0349794019f8ce2b0711de7808b4874f4e796
```

### 2. base64Encoded

Assuming that the `encryptedData` has been generated correctly, it is now time for Base64 encryption.&#x20;

The signature is generated using the following formula, relatively;

```plaintext
base64("apiKey:"+apiKey+"&randomKey:"+randomKey+"&signature:"+encryptedData)
```

The result is our `base64EncodedAuthorization` to be used in the header.

### 3. Authorization

After all the operations, the final and simplest step is to include `IYZWSv2`, `base64EncodedAuthorization` in the header, relatively.

```
...
"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"
...
```

{% hint style="warning" %}
In between IYZWSv2 and base64EncodedAuthorization there is a single line space.
{% endhint %}

## Sample Pre-request Script of Authorization on Postman

Taking a dummy Bin Check request as an example, the authorization process would be as follows;

```javascript
var apiKey = environment.apiKey;
var secretKey = environment.secretKey;
 
//Generate authorization string
function generateAuthorizationString() {

    // Lets create uniq randomKey
    // Sample randomKey : 1722246017090123456789
    // x-iyzi-rnd used to be random key from previous SHA1 Authentication, so plese do not hesitate to use x-iyzi-rnd as your randomkey.
    var randomKey = new Date().getTime() + "123456789";
    
    // Get the uri path for this request
    // Sample uri_path : /payment/bin/check
    var uri_path = "/payment/bin/check";
    
    // Get the payload and concatanete with uri path and randomKey.
    // Sample payload : payload: 1722246017090123456789/payment/bin/check{"binNumber":"589004"}
    var payload = _.isEmpty(request.data) ? randomKey + uri_path : randomKey + uri_path + request.data;
    
    // Encrypt the payload with HMACSHA256
    // Sample encryptedData : 91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9
    var encryptedData = CryptoJS.HmacSHA256(payload, secretKey);
 
    // Create the authorizationString using encryptedData
    /* Sample authorizationString : apiKey:sandbox-3uHv0LccjcWDyFHTvJpiACKPcJwbczmZ&
                                        randomKey:1722246017090123456789&
                                        signature:91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9 */
    var authorizationString = "apiKey:" + apiKey
                        + "&randomKey:" + randomKey
                        + "&signature:" + encryptedData;
    
 
    // Encode the authorizationString with base64 
    // Sample base64EncodedAuthorization : YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    var base64EncodedAuthorization = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(authorizationString));
 
    // Concatanate the encoded authorizationString with 'IYZWSv2 '.
    // Sample return value : IYZWSv2 YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    return "IYZWSv2 " + base64EncodedAuthorization;
}
var authorization = generateAuthorizationString();
postman.setEnvironmentVariable("authorization", authorization);
```


# Postman Collections

{% hint style="info" %}
To perform transactions in the test environment, a sandbox test account must be created before the Postman configuration.
{% endhint %}

### API 101

Basically, the fastest way to use iyzico APIs.

### **Step-1: Launch the Collection**

First, click the button below to view our collection.

\
[![Run in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/iyzico/iyzico/overview)

After that, you will be able to view the collection online as shown below.

<figure><img src="/files/mFcDsc3AJzjvOARwJF7A" alt=""><figcaption></figcaption></figure>

### **Step-2: Configuring API Information**<br>

Now it's time to run the services with your API information. To perform testing online, you will need to log in to your Postman account.

1. First, log in to your Postman account.

<figure><img src="/files/obmZdt0e7IwAYyBfJzGL" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
In the pre-request script section of the sample collection that includes iyzico services, there is an environment definition where the API information is set, as shown below.
{% endhint %}

```javascript
var apiKey = environment.apiKey;
var secretKey = environment.secretKey;
```

2. To define your API information, create a new environment or edit the iyzico environment. Postman will ask you to fork the collection in order to save your changes.

<figure><img src="/files/wP6mvzSNJI3ewN7Ktjyr" alt=""><figcaption></figcaption></figure>

3. After saving the collection to your account, edit and save your API information.

<figure><img src="/files/yxSrplVQe4hX4WfjhZ3l" alt=""><figcaption></figcaption></figure>

###

Once you have defined your API information, you can test all services.

If you have any questions regarding the integration, you can contact us at **<entegrasyon@iyzico.com> !**


# Live vs Sandbox

At iyzico, we understand the importance of a seamless payment experience in the fintech industry. To ensure the reliability and accuracy of your payment integration, we offer both Live and Sandbox environments.

While Live environment allows you to process real transactions, ensuring that your customers' payments are securely processed and funds are transferred smoothly.&#x20;

On the other hand, our Sandbox environment provides a safe and controlled testing environment. It mimics the behavior of the Live environment, allowing you to simulate transactions and test your payment flows without affecting real transactions or funds.&#x20;

Key differences;

### Endpoints

Our ENVs are exactly same regarding architecture.\
The only difference between our LIVE and Sandbox ENVs is URL paths on your API call.

{% tabs %}
{% tab title="LIVE ENV Url Path" %}

```
https://api.iyzipay.com
```

{% endtab %}

{% tab title="SANDBOX ENV Url Path" %}

```
https://sandbox-api.iyzipay.com
```

{% endtab %}
{% endtabs %}

###

### Credentials

iyzico authenticaton requires two pairs of credentials, apiKey and secretKey. Similar to Endpoints headline above, Sandbox credentials comes with "sandbox-..." prefix.

With in "abc" sample;

{% tabs %}
{% tab title="LIVE ENV Credentials" %}

* `"apiKey":"abc..."`&#x20;
* `"secretKey":"def..."`
  {% endtab %}

{% tab title="SANDBOX ENV Credentials" %}

* `"apiKey":"sandbox-ghj..."`&#x20;
* `"secretKey":"sanbox-klm..."`
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
Note that, Live and Sandbox crendentials are entirely different.
{% endhint %}

### Test Cards

For testing purposes, we provide a set of test cards that you can use in the [Sandbox ](/en/getting-started/preliminaries/sandbox)environment. These test cards simulate different payment scenarios, allowing you to validate your payment flows, handle various response codes, and ensure smooth transaction processing only on Sandbox ENV.


# Idempotency

Majority of iyzico services have designed non-idempotent to ensure predictable and consistent behavior when making repeated requests.&#x20;

In the context of our APIs, developers typically utilize following parameters for an idempotent payment architecture with parameters generated either merchants or iyzico;

### Parameters Generated by Merchants

#### "conversationId" or "basketId"

Optional values that merchants generates where It helps to match request and response pairs. Most known use cases are merchant order numbers, basket numbers, transaction reconciliation.

### Parameters Generated by iyzico

#### "token"

Unique value generated for hosted payment page payment methods. Parameter "token" specially produce for each request. It is a required field to find out the result of the payment.

#### "paymentId"

The id of the payment. It is expected from merchants to save on their systems. "paymentId" is crucial for cancellation of payment and effective communication with iyzico.


# Limiters

iyzico rate limiters, from a fintech perspective, play a crucial role in maintaining the security, reliability, and stability of financial services provided through HTTP-based APIs.

### Fundamental Rate Limiters Table

Table below represents list of essentials services

| Method                  | Limit | Time Frame |
| ----------------------- | ----- | ---------- |
| initialize Payment      | 50    | per Minute |
| retrieve Payment Result | 50    | per Minute |
| initialize HPP          | 100   | per Minute |
| retrieve HPP Result     | 100   | per Minute |
| refund                  | 50    | per Minute |
| cancel                  | 50    | per Minute |

{% hint style="info" %}
In case you exceed the limit, the response message will be as below:
{% endhint %}

```http
curl -X POST "BASE_URL" \
     -H "Content-Type: application/json" \
     -d '{
           "status": "failure",
           "errorCode": 50000,
           "errorMessage": "Request Limit Exceeded",
           "locale": "en"
         }'

```


# API Reference (Beta)

With iyzico APIs, you can manage the entire payment journey end-to-end — from one-time payments to subscription management, from marketplace flows to reporting.

The values shown in the **Authorization** header in the examples are for demonstration purposes only. You must generate and use your own HASH signature.\
You can access the documentation for the authentication steps [**here**](/en/getting-started/preliminaries/authentication).

Don’t forget to visit our [**GitHub**](https://github.com/iyzico) page for sample codes in different programming languages and our [Postman collection](/en/getting-started/preliminaries/postman-collections) for ready-to-use requests.


# Installment & BIN Service

## Installment Service Request

> The API provides installment counts, rates and amounts, as well as attributes such as issuing bank, card family and card scheme. It lists available installment options based on the given BIN and amount. You can also query installment rates with only the BIN or only the amount.

```json
{"openapi":"3.0.3","info":{"title":"BIN and Installment","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.iyzipay.com"}],"paths":{"/payment/iyzipos/installment":{"post":{"summary":"Installment Service Request","description":"The API provides installment counts, rates and amounts, as well as attributes such as issuing bank, card family and card scheme. It lists available installment options based on the given BIN and amount. You can also query installment rates with only the BIN or only the amount.","tags":["Installment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallmentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallmentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with IYZWSv2 and contains a Base64-encoded signed hash.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"InstallmentRequest":{"type":"object","required":["price"],"properties":{"locale":{"type":"string","description":"Language preference used in requests and responses.","enum":["tr","en"]},"price":{"type":"number","format":"decimal","description":"Amount for installment calculation."},"binNumber":{"type":"string","description":"8-digit card BIN. If provided, suitability is returned per card/bank. If omitted, installment rates can be returned based on the amount only."},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned as-is in the response."}}},"InstallmentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID matching the request."},"installmentDetails":{"type":"array","description":"Installment options calculated according to BIN and amount.","items":{"$ref":"#/components/schemas/InstallmentDetail"}}}},"InstallmentDetail":{"type":"object","properties":{"binNumber":{"type":"string","description":"BIN used in the calculation."},"price":{"type":"number","format":"decimal","description":"Amount used in the calculation."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card scheme.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamilyName":{"type":"string","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"],"description":"Card family."},"force3ds":{"type":"integer","description":"3DS requirement (0; No, 1; Yes).","enum":[0,1]},"bankCode":{"type":"integer","description":"Bank code."},"bankName":{"type":"string","description":"Bank name."},"forceCvc":{"type":"integer","description":"CVC requirement (0; No, 1; Yes).","enum":[0,1]},"commercial":{"type":"integer","description":"Commercial card flag (0; Personal, 1; Commercial).","enum":[0,1]},"dccEnabled":{"type":"integer","description":"DCC (Dynamic Currency Conversion) support (0; No, 1; Yes).","enum":[0,1]},"agricultureEnabled":{"type":"integer","description":"Agricultural card flag (0; No, 1; Yes).","enum":[0,1]},"installmentPrices":{"type":"array","description":"Installment options and prices.","items":{"$ref":"#/components/schemas/InstallmentPrice"}}}},"InstallmentPrice":{"type":"object","properties":{"installmentPrice":{"type":"number","format":"decimal","description":"Amount per installment."},"totalPrice":{"type":"number","format":"decimal","description":"Total amount with installments."},"installmentNumber":{"type":"integer","description":"Number of installments."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID matching the request."}}}}}}
```

## BIN Service Request

> Retrieves card attributes in BIN inquiries such as issuing bank, card family, and card scheme. To obtain the desired information, simply include the required parameters in your request. The API will respond with comprehensive details.

```json
{"openapi":"3.0.3","info":{"title":"BIN and Installment","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.iyzipay.com"}],"paths":{"/payment/bin/check":{"post":{"summary":"BIN Service Request","description":"Retrieves card attributes in BIN inquiries such as issuing bank, card family, and card scheme. To obtain the desired information, simply include the required parameters in your request. The API will respond with comprehensive details.","tags":["BIN"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BINCheckRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BINCheckResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with IYZWSv2 and contains a Base64-encoded signed hash.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"BINCheckRequest":{"type":"object","required":["binNumber"],"properties":{"locale":{"type":"string","description":"Language preference used in requests and responses.","enum":["tr","en"]},"binNumber":{"type":"string","description":"BIN to query (8 digits)."},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned as-is in the response."}}},"BINCheckResponse":{"type":"object","properties":{"binNumber":{"type":"string","description":"Queried BIN."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card scheme.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"bankName":{"type":"string","description":"Bank name."},"bankCode":{"type":"integer","description":"Bank code."},"commercial":{"type":"integer","description":"Commercial card flag (0; Personal, 1; Commercial).","enum":[0,1]},"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID matching the request."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID matching the request."}}}}}}
```


# Payment Methods


# API - NON3D

## Create Non3D Payment

> Initiates a payment without 3D Secure.

```json
{"openapi":"3.0.3","info":{"title":"NON3D","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/auth":{"post":{"summary":"Create Non3D Payment","description":"Initiates a payment without 3D Secure.","tags":["Non3D Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paidPrice","price","currency","paymentCard","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"conversationId":{"type":"string","description":"Unique ID used to match request/response."},"locale":{"type":"string","description":"Language code. Allowed values; tr, en. Default; tr","enum":["tr","en"]},"paidPrice":{"type":"decimal","description":"Total amount to be charged from the buyer."},"price":{"type":"decimal","description":"Basket total amount."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"installment":{"type":"integer","description":"Installment count. If omitted, single payment (1) is applied.","enum":[1,2,3,6,9,12]},"basketId":{"type":"string","description":"Basket ID."},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer"},"shippingAddress":{"description":"Shipping address. Required if at least one of the basket items has itemType \"PHYSICAL\". Not required if all items are \"VIRTUAL\".","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Items in the basket.","items":{"$ref":"#/components/schemas/BasketItem"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header starting with IYZWSv2 and a signed hash value encoded in base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"PaymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireYear","expireMonth","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder full name."},"cardNumber":{"type":"string","description":"Card number."},"expireYear":{"type":"string","description":"Expiry year (YYYY format)."},"expireMonth":{"type":"string","description":"Expiry month (MM format)."},"cvc":{"type":"string","description":"CVC code."},"registerCard":{"type":"integer","description":"Save the card? (0 = no, 1 = yes)"}}},"Buyer":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number (TR)."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Phone number."},"registrationDate":{"type":"string","description":"Registration date (yyyy-MM-dd HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (yyyy-MM-dd HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Product ID."},"price":{"type":"decimal","description":"Product price."},"name":{"type":"string","description":"Product name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model. Required only for marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model. Required only for marketplace model."}}},"PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Indicates the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status per fraud filters. If the risk score is low, the payment is approved instantly; if high, the payment is declined. The merchant should ship products only for transactions with value 1; for 0, the merchant should wait for notification.\n - 1: Approved\n - 0: Under review\n - -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant's applied installment/commission rate. For example, if price=100 and paidPrice=110, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant's commission amount. For example, if price=100 and paidPrice=110, the commission amount is 10. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico transaction commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Payment line items for basket entries.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown. Must be stored by the merchant. Used for refund/approve/disapprove operations and communication with iyzico. Preferably stored in relation with itemId."},"itemId":{"type":"string","description":"ID of the item in the basket provided by the merchant."},"price":{"type":"decimal","description":"Amount of the item in the merchant's basket."},"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- 0: In fraud control\n- -1: Declined after fraud control\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace Approval Given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount per breakdown."},"blockageResolvedDate":{"type":"string","description":"Blockage release date per transaction. Format yyyy-MM-dd HH:mm:ss, e.g. 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate distributed per breakdown."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount distributed per breakdown."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Rate of the amount to be sent to the sub-merchant."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per breakdown.","properties":{"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"iyziConversationRate":{"type":"decimal","description":"Exchange rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the exchange rate."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Host reference value given by the bank for the payment."},"signature":{"type":"string","description":"Signature value that can be used for signature verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure info."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"errorGroup":{"type":"string","description":"Error group."},"locale":{"type":"string","description":"Language code."},"systemTime":{"type":"integer","description":"System time."},"conversationId":{"type":"string","description":"Request/response matching ID."}}}}}}
```

## Retrieve Payment Result

> Retrieves the result of a payment.

```json
{"openapi":"3.0.3","info":{"title":"NON3D","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/detail":{"post":{"summary":"Retrieve Payment Result","description":"Retrieves the result of a payment.","tags":["Non3D Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentId"],"properties":{"locale":{"type":"string","description":"Language code. Allowed values; tr, en. Default; tr","enum":["tr","en"]},"paymentId":{"type":"string","description":"Payment transaction ID."},"paymentConversationId":{"type":"string","description":"ConversationId of the payment transaction. Required if paymentId is not sent."}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponseTwo"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header starting with IYZWSv2 and a signed hash value encoded in base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"PaymentResponseTwo":{"type":"object","properties":{"status":{"type":"string","description":"Indicates the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status per fraud filters. If the risk score is low, the payment is approved instantly; if high, the payment is declined. The merchant should ship products only for transactions with value 1; for 0, the merchant should wait for notification.\n - 1: Approved\n - 0: Under review\n - -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant's applied installment/commission rate. For example, if price=100 and paidPrice=110, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant's commission amount. For example, if price=100 and paidPrice=110, the commission is 10. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico transaction commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Payment line items for basket entries.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown. Must be stored by the merchant. Used for refund/approve/disapprove operations and communication with iyzico. Preferably stored in relation with itemId."},"itemId":{"type":"string","description":"ID of the item in the basket provided by the merchant."},"price":{"type":"decimal","description":"Amount of the item in the merchant's basket."},"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- 0: In fraud control\n- -1: Declined after fraud control\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace Approval Given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount per breakdown."},"blockageResolvedDate":{"type":"string","description":"Blockage release date per transaction. Format yyyy-MM-dd HH:mm:ss, e.g. 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate distributed per breakdown."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount distributed per breakdown."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Rate of the amount to be sent to the sub-merchant."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per breakdown.","properties":{"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"iyziConversationRate":{"type":"decimal","description":"Exchange rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the exchange rate."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Host reference value given by the bank for the payment."},"signature":{"type":"string","description":"Signature value that can be used for signature verification."},"paymentStatus":{"type":"string","description":"Shows the result of the payment process.","enum":["SUCCESS","FAILURE","INIT_THREEDS","CALLBACK_THREEDS"]}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure info."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"errorGroup":{"type":"string","description":"Error group."},"locale":{"type":"string","description":"Language code."},"systemTime":{"type":"integer","description":"System time."},"conversationId":{"type":"string","description":"Request/response matching ID."}}}}}}
```


# API - 3DS

## Initialize 3DS Payment

> Starts a 3D Secure session and returns an htmlContent value for 3DS authentication.

```json
{"openapi":"3.0.3","info":{"title":"3DS Payments","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/3dsecure/initialize":{"post":{"summary":"Initialize 3DS Payment","description":"Starts a 3D Secure session and returns an htmlContent value for 3DS authentication.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (3DS initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSInitializeRequest":{"type":"object","required":["price","paidPrice","callbackUrl","paymentCard","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Final amount to be charged to the customer."},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"installment":{"type":"integer","description":"Installment count (if omitted, a single installment is used).","enum":[1,2,3,4,6,9,12]},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"callbackUrl":{"type":"string","description":"Redirect URL after 3DS flow completes."},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard3DS"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer3DS"},"shippingAddress":{"description":"Shipping address. Required if at least one basket item has itemType \"PHYSICAL\". If all items are \"VIRTUAL\", it is not required.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Basket items.","items":{"$ref":"#/components/schemas/BasketItem"}}}},"PaymentCard3DS":{"type":"object","required":["cardHolderName","cardNumber","expireYear","expireMonth","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder’s full name."},"cardNumber":{"type":"string","description":"Card number (PAN)."},"expireYear":{"type":"string","description":"Expiration year (YY or YYYY)."},"expireMonth":{"type":"string","description":"Expiration month (MM)."},"cvc":{"type":"string","description":"Card security code."},"registerCard":{"type":"integer","description":"Save the card? (0 = no, 1 = yes)"}}},"Buyer3DS":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Identity/ID number."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"Mobile phone."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City code/name."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Main category."},"category2":{"type":"string","description":"Subcategory (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model; required only for marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model; required only for marketplace model."}}},"ThreeDSInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"threeDSHtmlContent":{"type":"string","description":"Base64-encoded HTML content of the 3DS verification screen."},"paymentId":{"type":"string","description":"Unique paymentId returned by iyzico."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}}
```

## Create 3DS Payment

> Finalizes the payment after successful 3D authentication.

```json
{"openapi":"3.0.3","info":{"title":"3DS Payments","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/3dsecure/auth":{"post":{"summary":"Create 3DS Payment","description":"Finalizes the payment after successful 3D authentication.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSAuthRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSAuthRequest":{"type":"object","required":["paymentId"],"properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"paymentId":{"type":"string","description":"Payment ID returned by the initialize call."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"conversationData":{"type":"string","description":"Data posted by the 3DS result. If present, it must be sent."}}},"PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters.\n- 1: Approved\n- 0: Under review\n- -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme/brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card product/family."},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment."},"itemTransactions":{"type":"array","description":"Line items per basket item.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Line-item ID; must be stored by the merchant (used for refund/approve operations)."},"itemId":{"type":"string","description":"Merchant-defined item ID in the basket."},"price":{"type":"decimal","description":"Item price on merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"transactionStatus":{"type":"integer","description":"Line item status.\n- 0: In fraud check\n- -1: Declined after fraud check\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage release date (yyyy-MM-dd HH:mm:ss)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission rate allocated to the line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission amount allocated to the line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant-side blockage amount."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Converted amount produced by the rate."}}}}}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"mdStatus":{"type":"integer","description":"3DS authentication result (1 means successful).","enum":[-1,0,1,2,3,4,5,6,7,8]},"hostReference":{"type":"string","description":"Host reference returned by the bank/acquirer."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}}
```

## Create 3DS v2 Payment

> After the verification step, both the v1 and the new-generation v2 endpoints can be used to finalize the payment. However, to align with more advanced and secure technologies, the use of the v2 endpoint is recommended.

```json
{"openapi":"3.0.3","info":{"title":"3DS v2 Payments","version":"1.0.2"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/v2/3dsecure/auth":{"post":{"summary":"Create 3DS v2 Payment","description":"After the verification step, both the v1 and the new-generation v2 endpoints can be used to finalize the payment. However, to align with more advanced and secure technologies, the use of the v2 endpoint is recommended.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSV2AuthRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSV2PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSV2AuthRequest":{"type":"object","required":["paymentId","paidPrice","basketId","currency"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"paymentId":{"type":"string","description":"Payment ID returned after 3DS initialization."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"paidPrice":{"type":"decimal","description":"Collected amount to be used in 3DS v2 completion. Must match the paidPrice sent in INIT 3DS."},"basketId":{"type":"string","description":"Basket ID (must match INIT 3DS basketId)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"],"description":"Currency. Default; TRY (must match the value sent in INIT 3DS)."}}},"ThreeDSV2PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters.\n- 1: Approved\n- 0: Under review\n- -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme/brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card product/family."},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment."},"itemTransactions":{"type":"array","description":"Line items per basket item.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Line-item ID; must be stored by the merchant (used for refund/approve operations)."},"itemId":{"type":"string","description":"Merchant-defined item ID in the basket."},"price":{"type":"decimal","description":"Item price on merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"transactionStatus":{"type":"integer","description":"Line item status.\n- 0: In fraud check\n- -1: Declined after fraud check\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage release date (yyyy-MM-dd HH:mm:ss)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission rate allocated to the line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission amount allocated to the line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant-side blockage amount."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Converted amount produced by the rate."}}}}}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"mdStatus":{"type":"integer","description":"3DS authentication result.\n- 1: Successful\n- 0,2-8: Failed\n","enum":[-1,0,1,2,3,4,5,6,7,8]},"hostReference":{"type":"string","description":"Host reference returned by the bank/acquirer."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}}
```


# Pay with iyzico

## Pay with iyzico (PWI) — Initialize

> Starts a PWI session; returns the token and page URL for redirection.

```json
{"openapi":"3.0.3","info":{"title":"Pay with iyzico (PWI)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/pay-with-iyzico/initialize":{"post":{"summary":"Pay with iyzico (PWI) — Initialize","description":"Starts a PWI session; returns the token and page URL for redirection.","tags":["Pay with iyzico"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (PWI initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiInitializeResponse"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; starts with IYZWSv2 and is a signed hash in Base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"}}},"schemas":{"PwiInitializeRequest":{"type":"object","required":["price","basketId","callbackUrl","currency","paidPrice","buyer","billingAddress","shippingAddress","basketItems"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"conversationId":{"type":"string","description":"Request/response correlation ID."},"price":{"type":"decimal","description":"Basket total amount."},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","enum":["PRODUCT","LISTING","SUBSCRIPTION"],"description":"Payment group."},"callbackUrl":{"type":"string","description":"URL to redirect after the transaction."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"],"description":"Currency. Default; TRY."},"paidPrice":{"type":"decimal","description":"Amount to be collected."},"paymentChannel":{"type":"string","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"],"description":"Payment channel."},"enabledInstallments":{"type":"array","items":{"type":"integer","enum":[1,2,3,6,9,12]},"description":"Installment options to offer."},"buyer":{"$ref":"#/components/schemas/PwiBuyer"},"shippingAddress":{"$ref":"#/components/schemas/PwiAddress","description":"Shipping Address. Required if at least one basket item is PHYSICAL. If all items are VIRTUAL, this is not required."},"billingAddress":{"$ref":"#/components/schemas/PwiAddress"},"basketItems":{"type":"array","description":"Basket items.","minItems":1,"items":{"$ref":"#/components/schemas/PwiBasketItem"}}}},"PwiBuyer":{"type":"object","description":"Buyer information","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country","ip"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number (e.g., TR ID)."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"Mobile phone number."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"ip":{"type":"string","description":"IP address."},"zipCode":{"type":"string","description":"Postal code."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD hh:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD hh:mm:ss)."}}},"PwiAddress":{"type":"object","description":"Address information","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Address."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."}}},"PwiBasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key of the service provider. Not used in the standard business model; required only in marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not used in the standard business model; required only in marketplace model."}}},"PwiInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."},"token":{"type":"string","description":"Token generated for Pay with iyzico. Returned per request and required to retrieve the result."},"tokenExpireTime":{"type":"integer","description":"Token validity in seconds; 1800 seconds."},"payWithIyzicoPageUrl":{"type":"string","description":"Payment page URL to redirect to."},"signature":{"type":"string","description":"Response signature (hash)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure indicator."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."}}}}}}
```

## Pay with iyzico (PWI) — Retrieve

> Queries the PWI transaction result by token.

```json
{"openapi":"3.0.3","info":{"title":"Pay with iyzico (PWI)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/auth/ecom/detail":{"post":{"summary":"Pay with iyzico (PWI) — Retrieve","description":"Queries the PWI transaction result by token.","tags":["Pay with iyzico"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiRetrieveRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiPaymentResponse"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; starts with IYZWSv2 and is a signed hash in Base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"}}},"schemas":{"PwiRetrieveRequest":{"type":"object","required":["token"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"conversationId":{"type":"string","description":"Request/response correlation ID."},"token":{"type":"string","description":"Token of the PWI session to be retrieved."}}},"PwiPaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en).","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Fraud status of the payment.\n- 1: Approved\n- 0: In review\n- -1: Rejected\n","enum":[1,0,-1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission/deferral rate (informational). For example, if price=100 and paidPrice=110, the rate is 10%."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission/deferral amount (informational). For example, if price=100 and paidPrice=110, the amount is 10."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last four digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Transaction items for basket lines.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Payment line ID; must be stored by the merchant (used for refund/capture/void and communication)."},"itemId":{"type":"string","description":"Item ID provided by the merchant."},"price":{"type":"decimal","description":"Amount of the basket item on the merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount distributed to this line; must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Line status:\n- 0: In fraud check\n- -1: Rejected after fraud check\n- 1: Approved (in marketplace: waiting for merchant approval)\n- 2: Approved (marketplace approved)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for this line (if applicable per agreement)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution date (yyyy-MM-dd HH:mm:ss), e.g., 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico fee at line level."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount at line level."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission/deferral rate at line level."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission/deferral amount at line level."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant after fees/commissions/blockages."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount distributed to this line; must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico fee at line level."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after conversion."},"currency":{"type":"string","description":"Currency."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Bank-provided host reference for the payment."},"signature":{"type":"string","description":"Signature value for verification."},"token":{"type":"string","description":"Token associated with the transaction (returned by the retrieval)."},"callbackUrl":{"type":"string","description":"Callback URL sent at initialization."},"paymentStatus":{"type":"string","description":"Payment status.","enum":["SUCCESS","FAILURE"]},"memberEmail":{"type":"string","description":"Email of the member who paid via PWI."},"memberGsmNumber":{"type":"string","description":"GSM number of the member who paid via PWI."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure indicator."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."}}}}}}
```


# CheckoutForm

## Checkout Form (CF) Initialize

> Starts a Checkout Form session and returns \`checkoutFormContent\` / \`paymentPageUrl\` and a \`token\` to render the payment page.

```json
{"openapi":"3.0.3","info":{"title":"Checkout Form (CF)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/initialize/auth/ecom":{"post":{"summary":"Checkout Form (CF) Initialize","description":"Starts a Checkout Form session and returns `checkoutFormContent` / `paymentPageUrl` and a `token` to render the payment page.","tags":["CheckoutForm"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (CF initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFInitializeResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with **IYZWSv2** and is a signed hash generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"CFInitializeRequest":{"type":"object","required":["price","paidPrice","currency","callbackUrl","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`. Send `en` to render the form in English.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned unchanged in the response."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Total amount to be charged."},"currency":{"type":"string","description":"Currency. Default is `TRY`.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default is `PRODUCT`.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"callbackUrl":{"type":"string","description":"Merchant URL that iyzico calls to deliver both success and failure results. Must have a valid SSL certificate."},"enabledInstallments":{"type":"array","description":"Available installment options.","items":{"type":"integer"}},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/BuyerCF"},"shippingAddress":{"description":"Shipping address. Required if at least one basket item is `PHYSICAL`. If all items are `VIRTUAL`, it is not required.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Basket items.","items":{"$ref":"#/components/schemas/BasketItem"}}}},"BuyerCF":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Mobile phone number."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD hh:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD hh:mm:ss)."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model. Required only for the marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model. Required only for the marketplace model."}}},"CFInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."},"token":{"type":"string","description":"Unique token generated for the checkout form. Mandatory to retrieve the payment result."},"checkoutFormContent":{"type":"string","description":"HTML content of the payment form (Base64-encoded)."},"paymentPageUrl":{"type":"string","description":"URL of iyzico’s hosted payment page (Common Payment Page)."},"signature":{"type":"string","description":"Signature value that can be used for integrity verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."}}}}}}
```

## Checkout Form (CF) Retrieve

> After the CF payment form is completed, queries the result using the \`token\`.

```json
{"openapi":"3.0.3","info":{"title":"Checkout Form (CF)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/auth/ecom/detail":{"post":{"summary":"Checkout Form (CF) Retrieve","description":"After the CF payment form is completed, queries the result using the `token`.","tags":["CheckoutForm"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFRetrieveRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFRetrieveResponse"}}}},"400":{"description":"Failed response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with **IYZWSv2** and is a signed hash generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"CFRetrieveRequest":{"type":"object","required":["token"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned unchanged in the response."},"token":{"type":"string","description":"Token returned in the CF initialize response."}}},"CFRetrieveResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Number of installments."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is **1**; for **0**, wait for notification.\n - **1**: Approved\n - **0**: In review\n - **-1**: Rejected\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate. For example, if price=100 and paidPrice=110, the rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount. Example; 10 when price=100 and paidPrice=110. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico processing commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico processing fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Line items corresponding to basket items.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID for the payment line item. Must be stored by the merchant. Used for refund/capture/void and when communicating with iyzico (ideally stored together with `itemId`)."},"itemId":{"type":"string","description":"Merchant-provided ID of the item in the basket."},"price":{"type":"decimal","description":"Item amount on the merchant’s side."},"paidPrice":{"type":"decimal","description":"Collected amount distributed per line item. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment line item.\n- **0**: In fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (in Marketplace, 1 means “Awaiting Merchant Approval”)\n- **2**: Approved (Marketplace approval granted)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for this line item. According to the iyzico–merchant agreement, a per-transaction blockage may be applied to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant. If the blockage exceeds the merchant amount, it is reflected to the sub-merchant as well."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution datetime for this line item. Format **yyyy-MM-dd HH:mm:ss** (e.g., 2015-10-19 14:36:52)."},"iyziCommissionFee":{"type":"decimal","description":"Portion of iyzico processing fee distributed to this line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"Portion of iyzico processing commission distributed to this line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate distributed to this line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount distributed to this line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant for this line item after fees/commissions and blockages."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount per line item (must be stored)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico processing fee distributed to this line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico processing commission distributed to this line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage reflected to the merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/commissions and blockages."},"iyziConversionRate":{"type":"decimal","description":"Conversion rate."},"iyziConversionRateAmount":{"type":"decimal","description":"Amount resulting from the conversion rate."}}}}},"currency":{"type":"string","description":"Currency of the payment."}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Bank-provided host reference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for integrity verification."},"token":{"type":"string","description":"Checkout Form token value."},"callbackUrl":{"type":"string","description":"Callback URL."},"paymentStatus":{"type":"string","description":"Result of the payment."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."}}}}}}
```


# Refund & Cancel

## Refund

> Used to refund a payment. The refund is executed over \*\*paymentTransactionId\*\* (per basket item). You can perform a \*\*full\*\* or \*\*partial\*\* refund for the payment amount.<br>

```json
{"openapi":"3.0.3","info":{"title":"Payment Operations - Cancel & Refund","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/refund":{"post":{"summary":"Refund","description":"Used to refund a payment. The refund is executed over **paymentTransactionId** (per basket item). You can perform a **full** or **partial** refund for the payment amount.\n","tags":["Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundPaymentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundPaymentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content type of the request body."}},"schemas":{"RefundPaymentRequest":{"type":"object","required":["paymentTransactionId","price"],"properties":{"paymentTransactionId":{"type":"string","description":"Basket item (payment breakdown) identifier (**paymentTransactionId**) to be refunded."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"ip":{"type":"string","description":"IP address the request is sent from."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"price":{"type":"decimal","description":"Amount to refund. **Must not exceed** the item price."},"currency":{"type":"string","description":"Payment currency."}}},"RefundPaymentResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the outcome of the request."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Current **epoch ms** at the time of response."},"conversationId":{"type":"string","description":"Echoes the conversationId sent in the request."},"paymentId":{"type":"string","description":"Payment number."},"paymentTransactionId":{"type":"string","description":"Refunded payment item identifier."},"price":{"type":"decimal","description":"Refunded amount."},"currency":{"type":"string","description":"Currency."},"authCode":{"type":"string","description":"Authorization (auth) code returned by the bank."},"hostReference":{"type":"string","description":"Reference value provided by the bank for the payment."},"refundHostReference":{"type":"string","description":"Reference value provided by the bank for the refund."},"retryable":{"type":"boolean","description":"Indicates whether the operation can be retried.","enum":[true,false]},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Current **epoch ms** at the time of response."},"conversationId":{"type":"string","description":"conversationId sent in the request."},"paymentId":{"type":"string","description":"Related payment id (if any)."},"paymentTransactionId":{"type":"string","description":"Related payment transaction id (if any)."},"price":{"type":"decimal","description":"Related amount (if any)."},"retryable":{"type":"boolean","description":"Whether the operation can be retried."}}}}}}
```

## Refund V2

> Enables refunds over \*\*paymentId\*\*. No item breakdown is required; the system determines the basket item to refund. You can perform a \*\*full\*\* or \*\*partial\*\* refund for the payment amount.<br>

```json
{"openapi":"3.0.3","info":{"title":"Payment Operations - Cancel & Refund","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/payment/refund":{"post":{"summary":"Refund V2","description":"Enables refunds over **paymentId**. No item breakdown is required; the system determines the basket item to refund. You can perform a **full** or **partial** refund for the payment amount.\n","tags":["Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundPaymentV2Request"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundPaymentV2Response"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content type of the request body."}},"schemas":{"RefundPaymentV2Request":{"type":"object","required":["paymentId","price"],"properties":{"paymentId":{"type":"string","description":"Payment identifier to be refunded."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"ip":{"type":"string","description":"IP address the request is sent from."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"price":{"type":"decimal","description":"Amount to refund. **Must not exceed** the payment total."},"currency":{"type":"string","description":"Payment currency."}}},"RefundPaymentV2Response":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the outcome of the request."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Current **epoch ms** at the time of response."},"conversationId":{"type":"string","description":"Echoes the conversationId sent in the request."},"paymentId":{"type":"string","description":"Refunded payment identifier."},"price":{"type":"decimal","description":"Refunded amount."},"currency":{"type":"string","description":"Currency."},"authCode":{"type":"string","description":"Authorization (auth) code returned by the bank."},"hostReference":{"type":"string","description":"Reference value provided by the bank for the payment."},"refundHostReference":{"type":"string","description":"Reference value provided by the bank for the refund."},"retryable":{"type":"boolean","description":"Indicates whether the operation can be retried.","enum":[true,false]},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Current **epoch ms** at the time of response."},"conversationId":{"type":"string","description":"conversationId sent in the request."},"paymentId":{"type":"string","description":"Related payment id (if any)."},"paymentTransactionId":{"type":"string","description":"Related payment transaction id (if any)."},"price":{"type":"decimal","description":"Related amount (if any)."},"retryable":{"type":"boolean","description":"Whether the operation can be retried."}}}}}}
```

## Cancel

> Used to cancel a payment.

```json
{"openapi":"3.0.3","info":{"title":"Payment Operations - Cancel & Refund","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/cancel":{"post":{"summary":"Cancel","description":"Used to cancel a payment.","tags":["Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPaymentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPaymentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content type of the request body."}},"schemas":{"CancelPaymentRequest":{"type":"object","required":["paymentId"],"properties":{"paymentId":{"type":"string","description":"The **unique payment number** assigned by iyzico for the payment you want to cancel."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation. Returned as-is in the response."},"ip":{"type":"string","description":"IP address the request is sent from."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language for iyzico messages."}}},"CancelPaymentResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the outcome of the request."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Current **epoch ms** at the time of response."},"conversationId":{"type":"string","description":"Echoes the conversationId sent in the request."},"paymentId":{"type":"string","description":"Canceled payment number."},"price":{"type":"decimal","description":"Canceled payment amount."},"currency":{"type":"string","description":"Currency (payment currency)."},"authCode":{"type":"string","description":"Authorization (auth) code returned by the bank."},"hostReference":{"type":"string","description":"Transaction reference value."},"cancelHostReference":{"type":"string","description":"Reference value for the cancel transaction."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Current **epoch ms** at the time of response."},"conversationId":{"type":"string","description":"conversationId sent in the request."},"paymentId":{"type":"string","description":"Related payment id (if any)."},"paymentTransactionId":{"type":"string","description":"Related payment transaction id (if any)."},"price":{"type":"decimal","description":"Related amount (if any)."},"retryable":{"type":"boolean","description":"Whether the operation can be retried."}}}}}}
```


# Subscription


# Product

## Create Product

> Creates a new subscription product. The Subscription API charges on a recurring basis according to pricing plans, and each plan is linked to at least one product. There is no limit on the number of products; a product can be created by providing only a name.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products":{"post":{"summary":"Create Product","operationId":"createSubscriptionProduct","description":"Creates a new subscription product. The Subscription API charges on a recurring basis according to pricing plans, and each plan is linked to at least one product. There is no limit on the number of products; a product can be created by providing only a name.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductCreateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductCreateSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductCreateRequest":{"type":"object","properties":{"locale":{"type":"string","description":"Language of iyzico response messages. Default **en**; **tr** is supported."},"conversationId":{"type":"string","description":"A reference value that can be used to match request and response."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."}},"required":["name"]},"SubscriptionProductCreateSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"$ref":"#/components/schemas/ProductResource"}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

## Update Product

> Updates a subscription product. Product name and description can be edited via API or the iyzico merchant panel. Use the product’s unique reference code for API updates.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}":{"post":{"summary":"Update Product","operationId":"updateSubscriptionProduct","description":"Updates a subscription product. Product name and description can be edited via API or the iyzico merchant panel. Use the product’s unique reference code for API updates.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Unique reference code of the product."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductGetSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductUpdateRequest":{"type":"object","properties":{"locale":{"type":"string","description":"Response language (**en**/**tr**)."},"conversationId":{"type":"string","description":"Value used for request/response matching."},"name":{"type":"string","description":"New product name."},"description":{"type":"string","description":"New product description."}},"required":["name"]},"SubscriptionProductGetSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"$ref":"#/components/schemas/ProductResource"}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

## Delete Product

> Deletes a subscription product. Products can be deleted via API or the iyzico merchant panel only when there are no plans linked to the product.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}":{"delete":{"summary":"Delete Product","operationId":"deleteSubscriptionProduct","description":"Deletes a subscription product. Products can be deleted via API or the iyzico merchant panel only when there are no plans linked to the product.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Unique reference code of the product."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductDeleteSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductDeleteSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

## List Products

> Lists subscription products. Use this to fetch all products and their linked plans. To reduce latency and payload size, pagination is used so you can retrieve the product list page by page.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products":{"get":{"summary":"List Products","operationId":"listSubscriptionProducts","description":"Lists subscription products. Use this to fetch all products and their linked plans. To reduce latency and payload size, pagination is used so you can retrieve the product list page by page.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductListRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductListSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductListRequest":{"type":"object","properties":{"page":{"type":"integer","description":"Returns products for the specified page."},"count":{"type":"integer","description":"Number of products per page."}}},"SubscriptionProductListSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","description":"Pagination results.","properties":{"totalCount":{"type":"string","description":"Total number of results returned."},"currentPage":{"type":"integer","description":"Page number returned."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Product list.","items":{"$ref":"#/components/schemas/ProductResource"}}}}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

## Get Product

> Retrieves details of a single product. Provide the product reference code in the request.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}":{"get":{"summary":"Get Product","operationId":"getSubscriptionProduct","description":"Retrieves details of a single product. Provide the product reference code in the request.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Unique reference code of the product."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductGetSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductGetSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"$ref":"#/components/schemas/ProductResource"}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```


# Pricing Plan

## Create Pricing Plan

> Creates a new pricing plan for a specific product.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}/pricing-plans":{"post":{"summary":"Create Pricing Plan","description":"Creates a new pricing plan for a specific product.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the product the plan will be attached to."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePricingPlanRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"CreatePricingPlanRequest":{"type":"object","required":["name","price","currencyCode","paymentInterval","planPaymentType"],"properties":{"name":{"type":"string","description":"Pricing plan name."},"price":{"type":"decimal","description":"Amount to charge on each billing period."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency. (For foreign currency, only non-TRY cards are allowed.)"},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Recurrence interval for the subscription charge."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"paymentIntervalCount":{"type":"integer","description":"Frequency multiplier for the interval. For example, if you set a weekly plan and send **2**, the charge occurs every 2 weeks."},"recurrenceCount":{"type":"integer","description":"Total number of repeats (e.g., **12** → 12 months). If omitted, it continues until the subscription is canceled."},"trialPeriodDays":{"type":"integer","description":"Free trial length in days. If provided, the first charge happens after this period."},"locale":{"type":"string","enum":["tr","en"],"description":"Language of the response and error messages."},"conversationId":{"type":"string","description":"Custom identifier for request tracking."}}},"CreatePricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the operation."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Plan name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"price":{"type":"decimal","description":"Subscription price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"recurrenceCount":{"type":"integer","description":"Number of repeats."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

## Update Pricing Plan

> This method allows updating \*\*only\*\* the \*\*name\*\* and \*\*trialPeriodDays\*\* fields.   The plan's reference code must be provided as a path parameter.   Updates can be performed via API or the iyzico merchant panel. Active subscriptions are not affected.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/pricing-plans/{pricingPlanReferenceCode}":{"post":{"summary":"Update Pricing Plan","description":"This method allows updating **only** the **name** and **trialPeriodDays** fields.   The plan's reference code must be provided as a path parameter.   Updates can be performed via API or the iyzico merchant panel. Active subscriptions are not affected.\n","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"pricingPlanReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the pricing plan to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePricingPlanRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"UpdatePricingPlanRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Updated plan name."},"trialPeriodDays":{"type":"integer","description":"Updated trial period (days)."}}},"UpdatePricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the operation."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the updated plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Updated plan name."},"price":{"type":"decimal","description":"Plan price."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"trialPeriodDays":{"type":"integer","description":"Updated trial period (days)."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"productReferenceCode":{"type":"string","description":"Product reference code."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."},"recurrenceCount":{"type":"integer","description":"Number of repeats."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

## Delete Pricing Plan

> Deletes the specified pricing plan by reference code. Plans with active subscriptions or pending updates cannot be deleted.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/pricing-plans/{pricingPlanReferenceCode}":{"delete":{"summary":"Delete Pricing Plan","description":"Deletes the specified pricing plan by reference code. Plans with active subscriptions or pending updates cannot be deleted.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"pricingPlanReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the pricing plan to delete."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"DeletePricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

## List Pricing Plans

> Lists all pricing plans for a given product. The response is paginated.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}/pricing-plans":{"get":{"summary":"List Pricing Plans","description":"Lists all pricing plans for a given product. The response is paginated.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product reference code."},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number to list."},{"name":"count","in":"query","schema":{"type":"integer"},"description":"Number of records per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"ListPricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"},"data":{"type":"object","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer"},"pageCount":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatePricingPlanResponse/properties/data"}}}}}},"CreatePricingPlanResponse":{"properties":{"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Plan name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"price":{"type":"decimal","description":"Subscription price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"recurrenceCount":{"type":"integer","description":"Number of repeats."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

## Get Pricing Plan Detail

> Returns details of a pricing plan. Merchants can see all details both in the merchant panel and via API.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/pricing-plans/{pricingPlanReferenceCode}":{"get":{"summary":"Get Pricing Plan Detail","description":"Returns details of a pricing plan. Merchants can see all details both in the merchant panel and via API.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"pricingPlanReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Pricing plan reference code."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingPlanDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"PricingPlanDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"},"data":{"$ref":"#/components/schemas/CreatePricingPlanResponse/properties/data"}}},"CreatePricingPlanResponse":{"properties":{"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Plan name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"price":{"type":"decimal","description":"Subscription price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"recurrenceCount":{"type":"integer","description":"Number of repeats."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```


# Subscription


# Initialize Subscription

## Initialize Subscription (iyzico Checkout Form)

> Used to start a subscription with iyzico Checkout Form. Returns the form content and token.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/checkoutform/initialize":{"post":{"summary":"Initialize Subscription (iyzico Checkout Form)","description":"Used to start a subscription with iyzico Checkout Form. Returns the form content and token.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormInitializeRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormInitializeResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionCheckoutFormInitializeRequest":{"type":"object","required":["callbackUrl","pricingPlanReferenceCode","subscriptionInitialStatus","customer"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`. Send `\"en\"` to create the checkout form in English.","enum":["tr","en"]},"callbackUrl":{"type":"string","description":"Callback URL to which the payment result will be sent."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"conversationId":{"type":"string","description":"Optional correlation value to match request/response pairs."},"customer":{"$ref":"#/components/schemas/SubscriptionCustomer"}}},"SubscriptionCustomer":{"description":"Buyer information.","type":"object","required":["name","surname","email","gsmNumber","identityNumber","billingAddress"],"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer E.164 when possible (e.g., +905555555555)."},"identityNumber":{"type":"string","description":"National ID (string)."},"billingAddress":{"$ref":"#/components/schemas/SubscriptionBillingAddress"},"shippingAddress":{"$ref":"#/components/schemas/SubscriptionShippingAddress"}}},"SubscriptionBillingAddress":{"type":"object","description":"Billing address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Billing address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"SubscriptionShippingAddress":{"type":"object","description":"Shipping address.","properties":{"address":{"type":"string","description":"Shipping address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"StartSubscriptionCheckoutFormInitializeResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Echoes the value you sent in the request."},"token":{"type":"string","description":"Token of the checkout form."},"checkoutFormContent":{"type":"string","description":"HTML content of the checkout form."},"tokenExpireTime":{"type":"integer","description":"Token validity time in seconds."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

## Retrieve Checkout Form Result

> After the checkout form flow completes, query the subscription creation result with the returned token.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/checkoutform/{token}":{"get":{"summary":"Retrieve Checkout Form Result","description":"After the checkout form flow completes, query the subscription creation result with the returned token.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token returned by checkout form initialize for this operation."},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional correlation value you send in the request to match with the response."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormResultResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionCheckoutFormResultResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."},"conversationId":{"type":"string","description":"Echoes the value you sent in the request."},"token":{"type":"string","description":"Token of the checkout form."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Unique code used to match updates on the merchant side."},"customerReferenceCode":{"type":"string","description":"Unique customer code created from user info (based on email and gsmNumber)."},"subscriptionStatus":{"type":"string","description":"Subscription status.","enum":["ACTIVE","PENDING"]},"pricingPlanReferenceCode":{"type":"string"},"trialDays":{"type":"integer","description":"Trial period defined in the plan. No charge during this period."},"trialStartDate":{"type":"integer","description":"Start time of the trial period (epoch ms)."},"trialEndDate":{"type":"integer","description":"End time of the trial period (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

## Initialize Subscription (NON3D)

> Start a subscription without the hosted checkout form, using your own payment form via NON3D service.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/initialize":{"post":{"summary":"Initialize Subscription (NON3D)","description":"Start a subscription without the hosted checkout form, using your own payment form via NON3D service.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionNon3DRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionNon3DResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionNon3DRequest":{"type":"object","required":["pricingPlanReferenceCode","customer","paymentCard","subscriptionInitialStatus"],"properties":{"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"conversationId":{"type":"string","description":"Optional correlation value to match request/response pairs."},"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"customer":{"$ref":"#/components/schemas/SubscriptionCustomer"},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard"}}},"SubscriptionCustomer":{"description":"Buyer information.","type":"object","required":["name","surname","email","gsmNumber","identityNumber","billingAddress"],"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer E.164 when possible (e.g., +905555555555)."},"identityNumber":{"type":"string","description":"National ID (string)."},"billingAddress":{"$ref":"#/components/schemas/SubscriptionBillingAddress"},"shippingAddress":{"$ref":"#/components/schemas/SubscriptionShippingAddress"}}},"SubscriptionBillingAddress":{"type":"object","description":"Billing address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Billing address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"SubscriptionShippingAddress":{"type":"object","description":"Shipping address.","properties":{"address":{"type":"string","description":"Shipping address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"PaymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireMonth","expireYear","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder name."},"cardNumber":{"type":"string","description":"Card number."},"expireMonth":{"type":"string","description":"Expiry month."},"expireYear":{"type":"string","description":"Expiry year."},"cvc":{"type":"string","description":"CVC/CVV."}}},"StartSubscriptionNon3DResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the request result; `success` if the operation succeeded."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Unique code used to match updates on the merchant side."},"customerReferenceCode":{"type":"string","description":"Unique customer code created from user info (based on email and gsmNumber)."},"subscriptionStatus":{"type":"string","description":"Subscription status.","enum":["ACTIVE","PENDING"]},"pricingPlanReferenceCode":{"type":"string"},"trialDays":{"type":"integer","description":"Trial period defined in the plan."},"trialStartDate":{"type":"integer","description":"Start time of the trial period (epoch ms)."},"trialEndDate":{"type":"integer","description":"End time of the trial period (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

## Initialize Subscription (Existing Customer)

> If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/initialize/with-customer":{"post":{"summary":"Initialize Subscription (Existing Customer)","description":"If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionWithCustomerRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionWithCustomerResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionWithCustomerRequest":{"type":"object","required":["subscriptionInitialStatus","pricingPlanReferenceCode","customerReferenceCode"],"properties":{"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"customerReferenceCode":{"type":"string","description":"Reference code of the existing customer. Must already have an active subscription to start a new one with this flow."}}},"StartSubscriptionWithCustomerResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Reference code to correlate subscription updates on the merchant side."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan linked to the created subscription."},"customerReferenceCode":{"type":"string","description":"Reference code of the related customer."},"subscriptionStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Subscription status."},"trialDays":{"type":"integer","description":"Trial period (days)."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"startDate":{"type":"integer","description":"Start time (epoch ms)."},"endDate":{"type":"integer","description":"End time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```


# Subscription Transactions

## Activate Subscription

> A subscription that was started as pending can be activated via this service.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Activate Subscription","version":"1.0.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/activate":{"post":{"summary":"Activate Subscription","description":"A subscription that was started as pending can be activated via this service.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription that was started as pending."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a Base64-encoded signed hash value that begins with IYZWSv2."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ActivateSubscriptionRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Reference code of the subscription that was started as pending."}}},"ActivateSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the result of the request. Returns `success` if the operation succeeds."},"systemTime":{"type":"integer","description":"Unix timestamp (milliseconds) of the response."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the result of the request (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Unix timestamp (milliseconds) of the response."}}}}}}
```

## Cancel Subscription

> Cancels an active subscription.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/cancel":{"post":{"summary":"Cancel Subscription","description":"Cancels an active subscription.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to cancel."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"CancelSubscriptionRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Subscription reference code. Can optionally be sent in the request body."}}},"CancelSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

## Retry Subscription Payment

> If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/operation/retry":{"post":{"summary":"Retry Subscription Payment","description":"If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrySubscriptionPaymentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrySubscriptionPaymentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"RetrySubscriptionPaymentRequest":{"type":"object","required":["referenceCode"],"properties":{"referenceCode":{"type":"string","description":"Reference code of the failed payment. This is the **orderReferenceCode** value provided in the webhook notification for the failed subscription payment.\n"}}},"RetrySubscriptionPaymentResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

{% hint style="warning" %}
A failed payment transaction can be retried within a maximum of 160 days. If this period is exceeded, no further payment attempts can be made for the subscription.
{% endhint %}

{% hint style="info" %}
After the retry operation is successfully triggered, an additional webhook notification is sent for the newly created payment transaction.
{% endhint %}

## Upgrade Subscription

> You can change or upgrade the plan during the subscription, provided that the \*\*new plan belongs to the same product\*\* and the billing interval (\*\*paymentInterval\*\* and \*\*paymentIntervalCount\*\*) remains the same. Use this service for price changes.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/upgrade":{"post":{"summary":"Upgrade Subscription","description":"You can change or upgrade the plan during the subscription, provided that the **new plan belongs to the same product** and the billing interval (**paymentInterval** and **paymentIntervalCount**) remains the same. Use this service for price changes.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to upgrade."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"UpgradeSubscriptionRequest":{"type":"object","required":["upgradePeriod","newPricingPlanReferenceCode"],"properties":{"upgradePeriod":{"type":"string","enum":["NOW","NEXT_PERIOD"],"description":"When the upgrade will take effect.\nValues:\n- **NOW**: Apply the change immediately.\n- **NEXT_PERIOD**: Apply the change at the next billing period.\n"},"newPricingPlanReferenceCode":{"type":"string","description":"Reference code of the target pricing plan."},"useTrial":{"type":"boolean","description":"If **true**, includes the trial period of the upgraded plan."},"resetRecurrenceCount":{"type":"boolean","description":"- **true**: Recalculates the subscription end date according to the new plan’s **recurrenceCount**.  \n- **false**: Keeps the current plan’s end date and transfers it to the new plan.\n"}}},"UpgradeSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the newly created subscription."},"parentReferenceCode":{"type":"string","description":"Reference code used by the merchant to correlate subscription updates."},"pricingPlanReferenceCode":{"type":"string"},"customerReferenceCode":{"type":"string"},"subscriptionStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Subscription status."},"trialDays":{"type":"integer","description":"Trial period of the plan (days)."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"startDate":{"type":"date","description":"Start time (epoch ms)."},"endDate":{"type":"date","description":"End time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

## Subscription Card Update (Checkout Form)

> Updates the credit card used in a subscription. In cases like payment failure or card expiry, merchants can prompt customers to update their card. \*\*The update can only be performed through the iyzico Checkout Form.\*\*\
> A \*\*₺1\*\* validation charge is taken and immediately refunded to validate the updated card.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/card-update/checkoutform/initialize":{"post":{"summary":"Subscription Card Update (Checkout Form)","description":"Updates the credit card used in a subscription. In cases like payment failure or card expiry, merchants can prompt customers to update their card. **The update can only be performed through the iyzico Checkout Form.**\nA **₺1** validation charge is taken and immediately refunded to validate the updated card.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCardUpdateCheckoutFormRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCardUpdateCheckoutFormResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"InitializeCardUpdateCheckoutFormRequest":{"type":"object","required":["callbackUrl","customerReferenceCode"],"properties":{"callbackUrl":{"type":"string","description":"Callback URL where the update result will be posted."},"customerReferenceCode":{"type":"string","description":"Reference code of the customer whose card will be updated."},"subscriptionReferenceCode":{"type":"string","description":"If updating on a specific subscription, the subscription reference code (optional).\n"},"locale":{"type":"string","enum":["tr","en"],"description":"Response language preference."}}},"InitializeCardUpdateCheckoutFormResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"token":{"type":"string","description":"Token of the card update checkout form."},"checkoutFormContent":{"type":"string","description":"HTML content for the checkout form where card information is updated."},"tokenExpireTime":{"type":"integer","description":"Token validity period (seconds)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

## Get Subscription Detail

> Returns full details of a subscription by its reference code.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}":{"get":{"summary":"Get Subscription Detail","description":"Returns full details of a subscription by its reference code.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to query."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubscriptionDetailOptionalRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubscriptionDetailResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"GetSubscriptionDetailOptionalRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Subscription reference code. Can optionally be sent in the request body."}}},"GetSubscriptionDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","description":"Pagination information and subscription records.","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer","description":"Current page number."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Detailed subscription records.","items":{"$ref":"#/components/schemas/SubscriptionDetailItem"}}}}}},"SubscriptionDetailItem":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Subscription reference code."},"parentReferenceCode":{"type":"string","description":"Reference used by the merchant to correlate subscription updates."},"pricingPlanName":{"type":"string","description":"Name of the pricing plan linked to the subscription."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the pricing plan linked to the subscription."},"productName":{"type":"string","description":"Product name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"customerEmail":{"type":"string","description":"Customer email address."},"customerGsmNumber":{"type":"string","description":"Customer GSM number."},"customerReferenceCode":{"type":"string","description":"Customer reference code."},"subscriptionStatus":{"type":"string","description":"Subscription status.\n\nValues:\n- **ACTIVE**: Subscription is active and payments are being collected regularly.\n- **PENDING**: Subscription is paused.\n- **UNPAID**: Payment could not be collected during the subscription.\n- **UPGRADED**: Subscription has been updated to another plan.\n- **CANCELED**: Subscription is canceled.\n- **EXPIRED**: Subscription period ended; no further charges are attempted.\n","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"trialDays":{"type":"integer","description":"Trial period (days) of the pricing plan."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."},"orders":{"type":"array","description":"List of periods (orders) within the subscription.","items":{"$ref":"#/components/schemas/SubscriptionOrder"}}}},"SubscriptionOrder":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the subscription period (order)."},"price":{"type":"decimal","description":"Period price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency."},"startPeriod":{"type":"integer","description":"Start time of the period (epoch ms)."},"endPeriod":{"type":"integer","description":"End time of the period (epoch ms)."},"orderStatus":{"type":"string","description":"Period status.","enum":["WAITING","SUCCESS","FAILED"]},"paymentAttempts":{"type":"array","description":"Payment attempts made for this period.","items":{"$ref":"#/components/schemas/SubscriptionPaymentAttempt"}}}},"SubscriptionPaymentAttempt":{"type":"object","description":"A single payment attempt for a subscription period.","properties":{"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"createdDate":{"type":"integer","description":"Creation time of the attempt (epoch ms)."},"paymentStatus":{"type":"string","description":"Result of the payment attempt.","enum":["SUCCESS","FAILED"]},"paymentId":{"type":"integer","description":"Payment ID for a successful payment. Present only when **SUCCESS**."},"errorCode":{"type":"string","description":"Error code for a failed payment. Present only when **FAILED**."},"errorMessage":{"type":"string","description":"Error message for a failed payment. Present only when **FAILED**."}}}}}}
```

## Search Subscriptions

> Retrieve subscription and payment details by filtering with various parameters, or without any parameters. For example, by sending only \*\*subscriptionStatus\*\*, you can list subscriptions with that status.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions":{"get":{"summary":"Search Subscriptions","description":"Retrieve subscription and payment details by filtering with various parameters, or without any parameters. For example, by sending only **subscriptionStatus**, you can list subscriptions with that status.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Reference code of the subscription to query."},{"name":"customerReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Customer reference code."},{"name":"pricingPlanReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Reference code of the pricing plan used in the subscription."},{"name":"parent","in":"path","required":false,"schema":{"type":"string"},"description":"Parent reference code used for matching in subscription updates."},{"name":"subscriptionStatus","in":"path","required":false,"schema":{"type":"string","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"description":"Subscription status filter."},{"name":"startDate","in":"path","required":false,"schema":{"type":"integer"},"description":"Subscription start date."},{"name":"endDate","in":"path","required":false,"schema":{"type":"integer"},"description":"Subscription end date (epoch ms)."},{"name":"page","in":"path","required":false,"schema":{"type":"integer"},"description":"Page number."},{"name":"count","in":"path","required":false,"schema":{"type":"integer"},"description":"Number of records per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSubscriptionsResponse"}}}},"404":{"description":"Example response for a wrong endpoint (e.g., typo).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"SearchSubscriptionsResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","description":"Pagination information and subscription records.","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer","description":"Current page number."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Detailed subscription records.","items":{"$ref":"#/components/schemas/SubscriptionDetailItem"}}}}}},"SubscriptionDetailItem":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Subscription reference code."},"parentReferenceCode":{"type":"string","description":"Reference used by the merchant to correlate subscription updates."},"pricingPlanName":{"type":"string","description":"Name of the pricing plan linked to the subscription."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the pricing plan linked to the subscription."},"productName":{"type":"string","description":"Product name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"customerEmail":{"type":"string","description":"Customer email address."},"customerGsmNumber":{"type":"string","description":"Customer GSM number."},"customerReferenceCode":{"type":"string","description":"Customer reference code."},"subscriptionStatus":{"type":"string","description":"Subscription status.\n\nValues:\n- **ACTIVE**: Subscription is active and payments are being collected regularly.\n- **PENDING**: Subscription is paused.\n- **UNPAID**: Payment could not be collected during the subscription.\n- **UPGRADED**: Subscription has been updated to another plan.\n- **CANCELED**: Subscription is canceled.\n- **EXPIRED**: Subscription period ended; no further charges are attempted.\n","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"trialDays":{"type":"integer","description":"Trial period (days) of the pricing plan."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."},"orders":{"type":"array","description":"List of periods (orders) within the subscription.","items":{"$ref":"#/components/schemas/SubscriptionOrder"}}}},"SubscriptionOrder":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the subscription period (order)."},"price":{"type":"decimal","description":"Period price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency."},"startPeriod":{"type":"integer","description":"Start time of the period (epoch ms)."},"endPeriod":{"type":"integer","description":"End time of the period (epoch ms)."},"orderStatus":{"type":"string","description":"Period status.","enum":["WAITING","SUCCESS","FAILED"]},"paymentAttempts":{"type":"array","description":"Payment attempts made for this period.","items":{"$ref":"#/components/schemas/SubscriptionPaymentAttempt"}}}},"SubscriptionPaymentAttempt":{"type":"object","description":"A single payment attempt for a subscription period.","properties":{"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"createdDate":{"type":"integer","description":"Creation time of the attempt (epoch ms)."},"paymentStatus":{"type":"string","description":"Result of the payment attempt.","enum":["SUCCESS","FAILED"]},"paymentId":{"type":"integer","description":"Payment ID for a successful payment. Present only when **SUCCESS**."},"errorCode":{"type":"string","description":"Error code for a failed payment. Present only when **FAILED**."},"errorMessage":{"type":"string","description":"Error message for a failed payment. Present only when **FAILED**."}}},"NotFoundErrorResponse":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server time (epoch ms)."},"status":{"type":"integer","description":"HTTP status code."},"error":{"type":"string","description":"Short error description."},"path":{"type":"string","description":"Requested path."}}}}}}
```


# Subscriber Transactions

## Update Subscriber

> Update all details of a subscriber via API. Provide the subscriber's \*\*customerReferenceCode\*\* as a path parameter and include the fields to be updated in the request body. At least \*\*one field\*\* in the body is required; only the provided fields will be updated.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Subscriber Management","version":"1.1.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/customers/{customerReferenceCode}":{"post":{"summary":"Update Subscriber","description":"Update all details of a subscriber via API. Provide the subscriber's **customerReferenceCode** as a path parameter and include the fields to be updated in the request body. At least **one field** in the body is required; only the provided fields will be updated.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"customerReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Subscriber reference code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request content type."}},"schemas":{"CustomerUpdateRequest":{"type":"object","description":"Fields to update. All fields are **optional**, but the body must contain at least one property.\n","minProperties":1,"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer **+90** format."},"identityNumber":{"type":"string","description":"Turkish National ID Number (11 digits)."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}},"CustomerAddress":{"type":"object","description":"Address information.","properties":{"address":{"type":"string","description":"Address line."},"zipCode":{"type":"string","description":"Postal/ZIP code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"district":{"type":"string","description":"District (if any)."},"country":{"type":"string","description":"Country."}}},"CustomerUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the result of the request."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."},"data":{"type":"object","description":"Updated subscriber information.","properties":{"referenceCode":{"type":"string","description":"Subscriber reference code."},"createdDate":{"type":"integer","description":"Subscriber creation time (epoch ms)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Record status."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Turkish National ID Number."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number."},"contactEmail":{"type":"string","description":"Contact email."},"contactGsmNumber":{"type":"string","description":"Contact GSM number."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."}}}}}}
```

## Subscriber Detail

> Retrieve all details of a subscriber by its reference code.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Subscriber Management","version":"1.1.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/customers/{customerReferenceCode}":{"get":{"summary":"Subscriber Detail","description":"Retrieve all details of a subscriber by its reference code.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"customerReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Subscriber reference code."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request content type."}},"schemas":{"CustomerDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."},"data":{"type":"object","description":"Subscriber (customer) details.","properties":{"referenceCode":{"type":"string","description":"Subscriber reference code."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Record status."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Turkish National ID Number."},"email":{"type":"string","description":"Subscriber email."},"gsmNumber":{"type":"string","description":"Subscriber GSM number."},"contactEmail":{"type":"string","description":"Contact email."},"contactGsmNumber":{"type":"string","description":"Contact GSM number."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}}}},"CustomerAddress":{"type":"object","description":"Address information.","properties":{"address":{"type":"string","description":"Address line."},"zipCode":{"type":"string","description":"Postal/ZIP code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"district":{"type":"string","description":"District (if any)."},"country":{"type":"string","description":"Country."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."}}}}}}
```

## List Subscribers

> List all subscribers with basic details.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Subscriber Management","version":"1.1.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/customers":{"get":{"summary":"List Subscribers","description":"List all subscribers with basic details.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number to fetch."},{"name":"count","in":"query","required":false,"schema":{"type":"integer"},"description":"Number of subscribers per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request content type."}},"schemas":{"CustomerListResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."},"data":{"type":"object","description":"Pagination info and subscriber list.","properties":{"totalCount":{"type":"integer","description":"Total number of records."},"currentPage":{"type":"integer","description":"Current page."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Subscriber records.","items":{"type":"object","allOf":[{"$ref":"#/components/schemas/CustomerDetailResponse/properties/data"}]}}}}}},"CustomerDetailResponse":{"properties":{"data":{"type":"object","description":"Subscriber (customer) details.","properties":{"referenceCode":{"type":"string","description":"Subscriber reference code."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Record status."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Turkish National ID Number."},"email":{"type":"string","description":"Subscriber email."},"gsmNumber":{"type":"string","description":"Subscriber GSM number."},"contactEmail":{"type":"string","description":"Contact email."},"contactGsmNumber":{"type":"string","description":"Contact GSM number."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}}}},"CustomerAddress":{"type":"object","description":"Address information.","properties":{"address":{"type":"string","description":"Address line."},"zipCode":{"type":"string","description":"Postal/ZIP code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"district":{"type":"string","description":"District (if any)."},"country":{"type":"string","description":"Country."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."}}}}}}
```


# Marketplace


# Submerchant

## Create Submerchant

> Creates a submerchant for the marketplace model. Supported types are \*\*PERSONAL\*\*, \*\*PRIVATE\_COMPANY\*\*, and \*\*LIMITED\_OR\_JOINT\_STOCK\_COMPANY\*\*. The subme rchant type is selected via the \*\*subMerchantType\*\* parameter.<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant":{"post":{"summary":"Create Submerchant","description":"Creates a submerchant for the marketplace model. Supported types are **PERSONAL**, **PRIVATE_COMPANY**, and **LIMITED_OR_JOINT_STOCK_COMPANY**. The subme rchant type is selected via the **subMerchantType** parameter.\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantCreateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantCreateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantCreateRequest":{"oneOf":[{"$ref":"#/components/schemas/SubmerchantPersonalRequest"},{"$ref":"#/components/schemas/SubmerchantPrivateCompanyRequest"},{"$ref":"#/components/schemas/SubmerchantLimitedJointRequest"}],"discriminator":{"propertyName":"subMerchantType","mapping":{"PERSONAL":"#/components/schemas/SubmerchantPersonalRequest","PRIVATE_COMPANY":"#/components/schemas/SubmerchantPrivateCompanyRequest","LIMITED_OR_JOINT_STOCK_COMPANY":"#/components/schemas/SubmerchantLimitedJointRequest"}},"description":"The request body varies depending on **subMerchantType**."},"SubmerchantPersonalRequest":{"description":"Personal Submerchant","type":"object","required":["subMerchantType","email","gsmNumber","address","contactName","contactSurname","subMerchantExternalId","identityNumber"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use PERSONAL for personal accounts."},"name":{"type":"string","description":"Submerchant (store) name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone."},"address":{"type":"string","description":"Submerchant address."},"iban":{"type":"string","description":"Submerchant IBAN. Must be consistent with **contactName/contactSurname**. If not sent during creation, it must be provided before product approval for payouts.\n"},"contactName":{"type":"string","description":"Contact first name."},"contactSurname":{"type":"string","description":"Contact last name."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant to map your Submerchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"conversationId":{"type":"string","description":"Correlation id for request/response."}}},"SubmerchantPrivateCompanyRequest":{"description":"Private Company","type":"object","required":["subMerchantType","email","gsmNumber","address","taxOffice","legalCompanyTitle","subMerchantExternalId"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use \"PRIVATE_COMPANY\" for private companies."},"name":{"type":"string","description":"Submerchant name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone (E.164)."},"address":{"type":"string","description":"Submerchantt address."},"iban":{"type":"string","description":"Submerchant IBAN. Must match **legalCompanyTitle**. If not sent during creation, it must be provided before product approval for payouts.\n"},"taxOffice":{"type":"string","description":"Tax office."},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string","description":"Registered company title."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantLimitedJointRequest":{"description":"Limited/Joint-Stock Company","type":"object","required":["subMerchantType","email","gsmNumber","address","taxOffice","taxNumber","legalCompanyTitle","subMerchantExternalId"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use \"LIMITED_OR_JOINT_STOCK_COMPANY\" for LTD/JSC companies."},"name":{"type":"string","description":"Submerchant name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone."},"address":{"type":"string","description":"Submerchant address."},"iban":{"type":"string","description":"Submerchant IBAN. Must match **legalCompanyTitle**. If not sent during creation, it must be provided before product approval for payouts.\n"},"taxOffice":{"type":"string","description":"Tax office."},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string","description":"Registered company title."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantCreateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent in the request."},"subMerchantKey":{"type":"string","description":"Generated Submerchant key."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Update Submerchant

> Updates an existing submerchant. The request body shape varies by submerchant type; \*\*one of three variants\*\* must be sent. The \*\*subMerchantType\*\* field is \*\*not\*\* included in the update body.<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant":{"put":{"summary":"Update Submerchant","description":"Updates an existing submerchant. The request body shape varies by submerchant type; **one of three variants** must be sent. The **subMerchantType** field is **not** included in the update body.\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantUpdateRequest":{"oneOf":[{"$ref":"#/components/schemas/SubmerchantPersonalUpdateRequest"},{"$ref":"#/components/schemas/SubmerchantPrivateCompanyUpdateRequest"},{"$ref":"#/components/schemas/SubmerchantLimitedJointUpdateRequest"}],"description":"Update fields vary by submerchant type. **Do not send subMerchantType** in update."},"SubmerchantPersonalUpdateRequest":{"description":"Personal Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","contactName","contactSurname","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string","description":"Store name."},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"contactName":{"type":"string"},"contactSurname":{"type":"string"},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"subMerchantKey":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantPrivateCompanyUpdateRequest":{"description":"Private Company Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","legalCompanyTitle","taxOffice","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"taxOffice":{"type":"string"},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string"},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"subMerchantKey":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantLimitedJointUpdateRequest":{"description":"Limited/Joint-Stock Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","legalCompanyTitle","taxOffice","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"taxOffice":{"type":"string"},"legalCompanyTitle":{"type":"string"},"taxNumber":{"type":"string","description":"Tax number."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"subMerchantKey":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent in the request."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Get Submerchant Detail

> Returns submerchant details by external ID (\*\*subMerchantExternalId\*\*).

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant/detail":{"post":{"summary":"Get Submerchant Detail","description":"Returns submerchant details by external ID (**subMerchantExternalId**).","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantDetailRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantDetailRequest":{"type":"object","required":["subMerchantExternalId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"subMerchantExternalId":{"type":"string","description":"ExternalId of the submerchant to query."}}},"SubmerchantDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"bankCountry":{"type":"string"},"currency":{"type":"string"},"taxOffice":{"type":"string"},"legalCompanyTitle":{"type":"string"},"subMerchantExternalId":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"subMerchantType":{"type":"string"},"subMerchantKey":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Submerchant Item/Price Update

> This service is used to modify the payout amount of the submerchant or update the submerchant information based on a single paymentTransaction<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/item":{"put":{"summary":"Submerchant Item/Price Update","description":"This service is used to modify the payout amount of the submerchant or update the submerchant information based on a single paymentTransaction\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPayoutUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPayoutUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemPayoutUpdateRequest":{"type":"object","required":["paymentTransactionId","subMerchantPrice","subMerchantKey"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Payment split id."},"subMerchantKey":{"type":"string","description":"Submerchant key."},"subMerchantPrice":{"type":"number","description":"Amount to be transferred to the submerchant."}}},"ItemPayoutUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"itemId":{"type":"string"},"paymentTransactionId":{"type":"string"},"transactionStatus":{"type":"integer"},"price":{"type":"number"},"paidPrice":{"type":"number"},"merchantCommissionRate":{"type":"number"},"merchantCommissionRateAmount":{"type":"number"},"iyziCommissionRateAmount":{"type":"number"},"iyziCommissionFee":{"type":"number"},"blockageRate":{"type":"number"},"blockageRateAmountMerchant":{"type":"number"},"blockageRateAmountSubMerchant":{"type":"number"},"blockageResolvedDate":{"type":"string"},"subMerchantKey":{"type":"string"},"subMerchantPrice":{"type":"number"},"subMerchantPayoutRate":{"type":"number"},"subMerchantPayoutAmount":{"type":"number"},"merchantPayoutAmount":{"type":"number"},"convertedPayout":{"type":"object","properties":{"paidPrice":{"type":"number"},"iyziCommissionRateAmount":{"type":"number"},"iyziCommissionFee":{"type":"number"},"blockageRateAmountMerchant":{"type":"number"},"blockageRateAmountSubMerchant":{"type":"number"},"subMerchantPayoutAmount":{"type":"number"},"merchantPayoutAmount":{"type":"number"},"iyziConversionRate":{"type":"number"},"iyziConversionRateAmount":{"type":"number"},"currency":{"type":"string"}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```


# Marketplace Payment

## Marketplace Payment (Non3D)

> Example shows the \*\*Non3D\*\* method. In a marketplace flow, each basket split \*\*must\*\*\
> include sub-merchant fields.<br>

```json
{"openapi":"3.0.3","info":{"title":"Non3D Payment (Marketplace)","version":"1.0.4"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/auth":{"post":{"summary":"Marketplace Payment (Non3D)","description":"Example shows the **Non3D** method. In a marketplace flow, each basket split **must**\ninclude sub-merchant fields.\n","tags":["Payment Methods"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Non3DMarketplaceRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Non3DMarketplaceResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"Non3DMarketplaceRequest":{"type":"object","required":["price","paidPrice","shippingAddress","billingAddress","paymentCard","basketItems","buyer"],"description":"Non3D payment request. In the marketplace model, each basket split **must** include\nsub-merchant fields.\n","properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"conversationId":{"type":"string","description":"Correlation value that is echoed back in the response."},"price":{"type":"decimal","description":"Basket (cart) total. **Sum of basket item prices must equal `price`.**"},"paidPrice":{"type":"decimal","description":"Final amount to be charged at POS; can be less than, greater than, or equal to `price`."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP"],"description":"Payment currency (default TRY)."},"installment":{"type":"integer","enum":[1,2,3,6,9,12],"description":"Installment count. Default; 1"},"paymentChannel":{"type":"string","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"],"description":"Payment channel. Default; \"WEB\""},"basketId":{"type":"string","description":"Basket/order identifier on the merchant side."},"paymentGroup":{"type":"string","enum":["PRODUCT","LISTING","SUBSCRIPTION","OTHER"],"description":"Payment group."},"paymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireMonth","expireYear","cvc"],"description":"Card details.","properties":{"cardHolderName":{"type":"string","description":"Name on card."},"cardNumber":{"type":"string","description":"PAN."},"expireYear":{"type":"string","description":"Expiration year (YYYY)."},"expireMonth":{"type":"string","description":"Expiration month (MM)."},"cvc":{"type":"string","description":"Security code."},"registerCard":{"type":"integer","enum":[0,1],"description":"Send 1 to store the card (card storage feature must be enabled)."}}},"buyer":{"type":"object","description":"Buyer information.","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Merchant-side user ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID (TR)."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"GSM number (prefer E.164)."},"registrationDate":{"type":"string","description":"Registration date."},"lastLoginDate":{"type":"string","description":"Last login date."},"registrationAddress":{"type":"string","description":"Registration address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"ip":{"type":"string","description":"Client IP address."}}},"shippingAddress":{"$ref":"#/components/schemas/Address"},"billingAddress":{"$ref":"#/components/schemas/BillingAddress"},"basketItems":{"type":"array","minItems":1,"description":"Basket items. **For marketplace**, sub-merchant fields are required.","items":{"$ref":"#/components/schemas/BasketItemMarketplace"}}}},"Address":{"type":"object","description":"Shipping Address. Required if at least one basket item has itemType = \"PHYSICAL\". Not required if all items are \"VIRTUAL\".\n","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BillingAddress":{"type":"object","description":"Billing Address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItemMarketplace":{"type":"object","description":"Basket item definition for marketplace payments.","required":["id","price","name","category1","itemType","subMerchantKey","subMerchantPrice"],"properties":{"id":{"type":"string","description":"Item ID per split on merchant side."},"name":{"type":"string","description":"Split name."},"price":{"type":"decimal","description":"Split amount; cannot be 0. Sum of splits must equal `price` (basket total)."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category."},"itemType":{"type":"string","enum":["PHYSICAL","VIRTUAL"],"description":"Item type."},"subMerchantKey":{"type":"string","description":"Sub-merchant **key** (required for marketplace)."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant’s payable amount (required for marketplace)."},"withholdingTax":{"type":"decimal","description":"Withholding tax amount. If the marketplace withholds tax from the sub-merchant payout and wants it to appear in the payment result and **Payout Report**, `withholdingTax` must be sent. (Recorded for information only; iyzico does not calculate it.)\n"}}},"Non3DMarketplaceResponse":{"type":"object","description":"Successful Non3D payment response.","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Charged total amount (via POS)."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"iyzico payment ID."},"fraudStatus":{"type":"integer","enum":[0,-1,1],"description":"Fraud filter result:\n- **1**: Approved — merchant may proceed (ship).\n- **0**: Under review — wait for a later notification.\n- **-1**: Rejected.\n"},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fixed fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme."},"cardFamily":{"type":"string","description":"Card family/brand."},"binNumber":{"type":"string","description":"First 6 digits of the card."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency."},"itemTransactions":{"type":"array","description":"Per-item split results.","items":{"type":"object","properties":{"itemId":{"type":"string","description":"Split ID."},"paymentTransactionId":{"type":"string","description":"Split transaction ID."},"transactionStatus":{"type":"integer","enum":[0,-1,1,2],"description":"Split status:\n- **0**: In fraud check\n- **-1**: Rejected after fraud check\n- **1**: Approved (**Marketplace meaning:** Waiting for merchant approval)\n- **2**: Approved (**Marketplace meaning:** Merchant-approved)\n"},"price":{"type":"decimal","description":"Split amount."},"paidPrice":{"type":"decimal","description":"Charged amount for the split."},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate on split."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount on split."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount on split."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fixed fee on split."},"blockageRate":{"type":"integer","description":"Blockage rate."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant blockage amount."},"blockageRateAmountSubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount."},"withholdingTax":{"type":"decimal","description":"Withholding tax amount."},"blockageResolvedDate":{"type":"string","description":"Blockage resolve date (YYYY-MM-DD hh:mm:ss)."},"subMerchantKey":{"type":"string","description":"Sub-merchant key."},"externalSubMerchantId":{"type":"string","description":"Merchant’s external ID for the sub-merchant."},"subMerchantPrice":{"type":"decimal","description":"Amount payable to the sub-merchant."},"subMerchantPayoutRate":{"type":"decimal","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to sub-merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to merchant."},"convertedPayout":{"type":"object","description":"Summary (in converted currency).","properties":{"paidPrice":{"type":"decimal","description":"Charged amount (converted)."},"iyziCommissionRateAmount":{"type":"decimal","description":"Commission rate amount (converted)."},"iyziCommissionFee":{"type":"decimal","description":"Fixed commission (converted)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant blockage (converted)."},"blockageRateAmountSubMerchant":{"type":"decimal","description":"Sub-merchant blockage (converted)."},"subMerchantPayoutAmount":{"type":"decimal","description":"Sub-merchant payable (converted)."},"merchantPayoutAmount":{"type":"decimal","description":"Merchant payable (converted)."},"iyziConversionRate":{"type":"decimal","description":"FX conversion rate."},"iyziConversionRateAmount":{"type":"decimal","description":"FX conversion amount."},"currency":{"type":"string","description":"Converted currency."}}}}}},"authCode":{"type":"string","description":"Bank authorization code."},"phase":{"type":"string","description":"Transaction phase (AUTH/PREAUTH etc.)."},"hostReference":{"type":"string","description":"Host reference."},"signature":{"type":"string","description":"Response signature (for verification)."}}},"ErrorResponse":{"type":"object","description":"Error response.","properties":{"status":{"type":"string","enum":["failure"],"description":"Operation result."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID."}}}}}}
```


# Approve

## Approve Item

> To approve an item, provide the split id (\*\*paymentTransactionId\*\*). The id is returned by the payment service.

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/item/approve":{"post":{"summary":"Approve Item","description":"To approve an item, provide the split id (**paymentTransactionId**). The id is returned by the payment service.","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemApproveRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemActionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemApproveRequest":{"type":"object","required":["paymentTransactionId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Split id to be approved."}}},"ItemActionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Dissapprove

> To disapprove a product, the related paymentTransactionId must be provided in the request. The id (paymentTransactionId) of the disapproved payment transaction will be returned in the response.

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/item/disapprove":{"post":{"summary":"Dissapprove","description":"To disapprove a product, the related paymentTransactionId must be provided in the request. The id (paymentTransactionId) of the disapproved payment transaction will be returned in the response.","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemDisapproveRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemActionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemDisapproveRequest":{"type":"object","required":["paymentTransactionId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Split id whose approval will be revoked."}}},"ItemActionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```


# iyzico Link

## Create iyzico Link

> Used to create a new iyzico Link. On success, returns the link URL. You can share the returned URL with your customers.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products":{"post":{"tags":["iyzilink"],"summary":"Create iyzico Link","description":"Used to create a new iyzico Link. On success, returns the link URL. You can share the returned URL with your customers.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateRequest"}}}},"responses":{"200":{"description":"Successful creation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateOrUpdateResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkCreateRequest":{"type":"object","required":["name","description","price","currencyCode","encodedImageFile"],"properties":{"conversationId":{"type":"string","description":"Value sent for request/response correlation."},"locale":{"type":"string","description":"Response language. Default **tr**.","enum":["en","tr"]},"name":{"type":"string","description":"The product name that will be visible to the customer."},"description":{"type":"string","description":"The product description that will be visible to the customer."},"price":{"type":"string","format":"decimal","description":"Product price."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"encodedImageFile":{"type":"string","description":"Base64-encoded product image."},"addressIgnorable":{"type":"boolean","description":"Do not request address at checkout (true) / request address (false).","enum":[true,false]},"installmentRequested":{"type":"boolean","description":"Enable/disable installment sales.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"flexibleLink":{"type":"boolean","description":"Lets the customer complete the payment with one of three preset amounts or a custom amount. This feature must be enabled on the merchant account.","enum":[true,false]},"presetPriceValues":{"type":"integer","description":"Preset amounts shown for FlexibleLink.","enum":[10,20,30]},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}},"IyziLinkCreateOrUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Created/updated link information.","properties":{"token":{"type":"string","description":"Token generated by iyzico."},"url":{"type":"string","description":"Purchase URL of the product."},"imageUrl":{"type":"string","description":"Product image URL."}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

## Create Fast Link

> Creates a Fast Link. Fast Link is a solution that enables quick and easy collection for payments up to 750 TRY. A Fast Link can be used only once. To create a Fast Link, you must first have an approved iyzico link.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/fast-link/products":{"post":{"tags":["iyzico Link"],"summary":"Create Fast Link","description":"Creates a Fast Link. Fast Link is a solution that enables quick and easy collection for payments up to 750 TRY. A Fast Link can be used only once. To create a Fast Link, you must first have an approved iyzico link.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkFastLinkRequest"}}}},"responses":{"200":{"description":"Successful creation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateOrUpdateResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkFastLinkRequest":{"type":"object","required":["price","currencyCode"],"properties":{"conversationId":{"type":"string","description":"Value sent for request/response correlation."},"locale":{"type":"string","description":"Response language. Default **tr**.","enum":["tr","en"]},"description":{"type":"string","description":"Link description shown to the customer."},"price":{"type":"string","format":"decimal","description":"Product price."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]}}},"IyziLinkCreateOrUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Created/updated link information.","properties":{"token":{"type":"string","description":"Token generated by iyzico."},"url":{"type":"string","description":"Purchase URL of the product."},"imageUrl":{"type":"string","description":"Product image URL."}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

## Get iyzico Link

> Query a single link by token. Returns the iyzico Link details for the given token.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}":{"get":{"tags":["iyzico Link"],"summary":"Get iyzico Link","description":"Query a single link by token. Returns the iyzico Link details for the given token.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token value of the iyzico Link to query."},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language (default **en**).","enum":["tr","en"]},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Request/response correlation value."}],"responses":{"200":{"description":"Product detail response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkDetailResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkDetailResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IyziLinkProduct"}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}},"IyziLinkProduct":{"type":"object","description":"iyzico Link product detail.","properties":{"name":{"type":"string","description":"Product name."},"conversationId":{"type":"string","description":"Merchant-side reference."},"description":{"type":"string","description":"Product description."},"price":{"type":"string","format":"decimal","description":"Product price (decimal)."},"currencyId":{"type":"integer","description":"Currency ID."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"token":{"type":"string","description":"Token generated by iyzico."},"productType":{"type":"string","description":"Product type.","enum":["IYZILINK","FASTLINK"]},"productStatus":{"type":"string","description":"Product status.","enum":["ACTIVE","PASSIVE"]},"merchantId":{"type":"integer","description":"Merchant ID."},"url":{"type":"string","description":"Purchase link."},"imageUrl":{"type":"string","description":"Product image."},"addressIgnorable":{"type":"boolean","description":"Do not request/request address.","enum":[true,false]},"soldCount":{"type":"integer","description":"Number of sold items."},"installmentRequested":{"type":"boolean","description":"Installment status.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"presetPriceValues":{"type":"array","description":"Preset price options.","items":{"type":"string","format":"decimal"}},"flexibleLink":{"type":"boolean","description":"Flexible priced link."},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}}}}}
```

## List iyzico Links

> Lists all created iyzico Links with pagination.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products":{"get":{"tags":["iyzico Link"],"summary":"List iyzico Links","description":"Lists all created iyzico Links with pagination.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language.","enum":["tr","en"]},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Page number."},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of items per page."},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Free-form field for request/response correlation."}],"responses":{"200":{"description":"Listing response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkListResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkListResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"listingReviewed":{"type":"boolean","description":"Status information for the listing operation."},"totalCount":{"type":"integer","description":"Total item count."},"currentPage":{"type":"integer","description":"Current page."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Product list.","items":{"$ref":"#/components/schemas/IyziLinkProduct"}}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}},"IyziLinkProduct":{"type":"object","description":"iyzico Link product detail.","properties":{"name":{"type":"string","description":"Product name."},"conversationId":{"type":"string","description":"Merchant-side reference."},"description":{"type":"string","description":"Product description."},"price":{"type":"string","format":"decimal","description":"Product price (decimal)."},"currencyId":{"type":"integer","description":"Currency ID."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"token":{"type":"string","description":"Token generated by iyzico."},"productType":{"type":"string","description":"Product type.","enum":["IYZILINK","FASTLINK"]},"productStatus":{"type":"string","description":"Product status.","enum":["ACTIVE","PASSIVE"]},"merchantId":{"type":"integer","description":"Merchant ID."},"url":{"type":"string","description":"Purchase link."},"imageUrl":{"type":"string","description":"Product image."},"addressIgnorable":{"type":"boolean","description":"Do not request/request address.","enum":[true,false]},"soldCount":{"type":"integer","description":"Number of sold items."},"installmentRequested":{"type":"boolean","description":"Installment status.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"presetPriceValues":{"type":"array","description":"Preset price options.","items":{"type":"string","format":"decimal"}},"flexibleLink":{"type":"boolean","description":"Flexible priced link."},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}}}}}
```

## Update iyzico Link

> Update an existing iyzico Link by using the token returned at creation time.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}":{"put":{"tags":["iyzico Link"],"summary":"Update iyzico Link","description":"Update an existing iyzico Link by using the token returned at creation time.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token value of the iyzico Link to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkUpdateRequest"}}}},"responses":{"200":{"description":"Successful update response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateOrUpdateResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkUpdateRequest":{"type":"object","required":["name","description","price","currencyCode"],"description":"Fields that can be sent for link update (**token** is sent in the path).","properties":{"conversationId":{"type":"string","description":"Value used for request/response correlation."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"price":{"type":"string","format":"decimal","description":"Product price."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"encodedImageFile":{"type":"string","description":"Base64-encoded product image."},"addressIgnorable":{"type":"boolean","description":"Do not request/request address.","enum":[true,false]},"installmentRequested":{"type":"boolean","description":"Enable/disable installment sales.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}},"IyziLinkCreateOrUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Created/updated link information.","properties":{"token":{"type":"string","description":"Token generated by iyzico."},"url":{"type":"string","description":"Purchase URL of the product."},"imageUrl":{"type":"string","description":"Product image URL."}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

## Update Link Status

> Sets an iyzico link’s status to \*\*ACTIVE\*\* or \*\*PASSIVE\*\*. Requires the link token and the new status value.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}/status/{status}":{"patch":{"tags":["iyzico Link"],"summary":"Update Link Status","description":"Sets an iyzico link’s status to **ACTIVE** or **PASSIVE**. Requires the link token and the new status value.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token of the iyzico link."},{"name":"status","in":"path","required":true,"schema":{"type":"string","enum":["ACTIVE","PASSIVE"]},"description":"New status to set."},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language (default **en**).","enum":["tr","en"]},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Request/response correlation value."}],"responses":{"200":{"description":"Status update result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicStatusResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

## Delete iyzico Link

> Deletes an iyzico Link.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}":{"delete":{"tags":["iyzico Link"],"summary":"Delete iyzico Link","description":"Deletes an iyzico Link.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token of the link to delete."},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language (default **en**).","enum":["tr","en"]},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Request/response correlation value."}],"responses":{"200":{"description":"Deletion result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkDeleteResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkDeleteResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```


# Card Storage

## Create User and Card

> You can create a \*\*user\*\* and a \*\*card\*\* linked to that user in iyzico without creating a payment. Or, using the same endpoint, you can \*\*add a new card\*\* to an \*\*existing user\*\*. Request parameters differ between the two variants. Both request bodies and JSON examples are provided below.

```json
{"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/cardstorage/card":{"post":{"summary":"Create User and Card","description":"You can create a **user** and a **card** linked to that user in iyzico without creating a payment. Or, using the same endpoint, you can **add a new card** to an **existing user**. Request parameters differ between the two variants. Both request bodies and JSON examples are provided below.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CardCreateRequest"},{"$ref":"#/components/schemas/CardCreateWithUserKeyRequest"}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCreateSuccessResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"CardCreateRequest":{"type":"object","description":"Create a user and a card (new user + first card).","properties":{"locale":{"type":"string","description":"Sets the language of messages returned by iyzico. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Value you send to correlate request/response."},"externalId":{"type":"string","description":"ID assigned by the merchant to the card to be stored."},"email":{"type":"string","description":"Email of the stored card owner."},"card":{"$ref":"#/components/schemas/Card"}},"required":["email","card"]},"Card":{"type":"object","description":"Card information.","properties":{"cardAlias":{"type":"string","description":"The name assigned to the stored card. It is defined by the merchant and can be used to match it with your system."},"expireYear":{"type":"string","description":"Expiration year on the card."},"expireMonth":{"type":"string","description":"Expiration month on the card."},"cardNumber":{"type":"string","description":"Card number."},"cardHolderName":{"type":"string","description":"Name printed on the card."}},"required":["cardNumber","expireYear","expireMonth","cardHolderName"]},"CardCreateWithUserKeyRequest":{"type":"object","description":"Add a second/additional card to an existing user.","properties":{"locale":{"type":"string","description":"Sets the language of messages returned by iyzico. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation (optional)."},"cardUserKey":{"type":"string","description":"Existing user key to which the card will be added."},"card":{"$ref":"#/components/schemas/Card"}},"required":["cardUserKey","card"]},"CardCreateSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"externalId":{"type":"string","description":"The `externalId` value sent in the request."},"email":{"type":"string","description":"Email on the stored card (may be returned only in the first variant)."},"cardUserKey":{"type":"string","description":"User key for the stored card. Used to charge again."},"cardToken":{"type":"string","description":"Token of the stored card. Used to charge again."},"binNumber":{"type":"string","description":"First 8 digits of the card."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family (returned for local cards).","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"cardAlias":{"type":"string","description":"Alias of the card."},"cardBankCode":{"type":"integer","description":"If the card is a local card, its bank code."},"cardBankName":{"type":"string","description":"If the card is a local card, its bank name."}}}]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}}
```

## List Stored Cards

> You can list the cards that belong to a user in iyzico.

```json
{"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/cardstorage/cards":{"post":{"summary":"List Stored Cards","description":"You can list the cards that belong to a user in iyzico.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListRequest"}}}},"responses":{"200":{"description":"Successful response — Card list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListSuccessResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"CardListRequest":{"type":"object","description":"Request to list stored cards.","properties":{"locale":{"type":"string","description":"Response language. Default `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Correlation ID sent for request/response matching."},"cardUserKey":{"type":"string","description":"User key whose cards will be listed."}},"required":["cardUserKey"]},"CardListSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"cardUserKey":{"type":"string","description":"User key whose cards are listed."},"cardDetails":{"type":"array","description":"List of stored cards for the user.","items":{"$ref":"#/components/schemas/CardListItem"}}}}]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"CardListItem":{"type":"object","description":"Stored card information.","properties":{"cardToken":{"type":"string","description":"Stored card token."},"cardAlias":{"type":"string","description":"Alias for the card."},"binNumber":{"type":"string","description":"First 6 or 8 digits of the card."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family (for local cards).","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"cardBankCode":{"type":"integer","description":"Bank code (for local cards)."},"cardBankName":{"type":"string","description":"Bank name (for local cards)."},"expireMonth":{"type":"string","description":"Expire month."},"expireYear":{"type":"string","description":"Expire year."}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}}
```

## Delete a Stored Card

> Deletes a card that belongs to a user created in iyzico.

```json
{"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/cardstorage/card":{"delete":{"summary":"Delete a Stored Card","description":"Deletes a card that belongs to a user created in iyzico.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardDeleteRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"CardDeleteRequest":{"type":"object","description":"Request to delete a stored card.","properties":{"locale":{"type":"string","description":"Response language. Default `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Correlation ID sent for request/response matching."},"cardUserKey":{"type":"string","description":"User key of the stored card."},"cardToken":{"type":"string","description":"Token of the card to be deleted."}},"required":["cardUserKey","cardToken"]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}}
```

## Crate Payment with Stored Card (NON3D)

> After card storage, you can send a “NON3D or 3DS” payment request using the returned \`cardUserKey\` and \`cardToken\`. Unlike a standard payment request, card details are sent via \`cardUserKey\` and \`cardToken\`. Suitable for one-click payments or subscription cycles. Example below shows NON3D.

```json
{"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/auth":{"post":{"summary":"Crate Payment with Stored Card (NON3D)","description":"After card storage, you can send a “NON3D or 3DS” payment request using the returned `cardUserKey` and `cardToken`. Unlike a standard payment request, card details are sent via `cardUserKey` and `cardToken`. Suitable for one-click payments or subscription cycles. Example below shows NON3D.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAuthSavedCardRequest"}}}},"responses":{"200":{"description":"Successful response — payment captured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAuthSuccessResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"PaymentAuthSavedCardRequest":{"type":"object","description":"Request to NON3D payment using a stored card.","properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"paidPrice":{"type":"decimal","description":"Total amount to be charged from the customer."},"price":{"type":"decimal","description":"Basket total amount."},"installment":{"type":"integer","description":"Installment count. If omitted, single installment (1) is used.","enum":[1,2,3,6,9,12]},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"paymentCard":{"$ref":"#/components/schemas/PaymentCardSaved"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer"},"shippingAddress":{"description":"Shipping Address. Required if at least one basket item is `PHYSICAL`. Not required if all items are `VIRTUAL`.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing Address.","$ref":"#/components/schemas/Address"},"basketItems":{"description":"Basket items.","type":"array","items":{"$ref":"#/components/schemas/BasketItem"}}},"required":["price","paidPrice","paymentCard","buyer","shippingAddress","billingAddress","basketItems"]},"PaymentCardSaved":{"type":"object","description":"Token data for the card.","properties":{"cardUserKey":{"type":"string","description":"cardUserKey returned by iyzico after card storage."},"cardToken":{"type":"string","description":"cardToken returned by iyzico for the stored card."}},"required":["cardUserKey","cardToken"]},"Buyer":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Buyer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number (Türkiye)."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Phone number."},"registrationDate":{"type":"string","description":"Registration date (yyyy-MM-dd HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (yyyy-MM-dd HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Zip / postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Zip / postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Product ID."},"price":{"type":"decimal","description":"Product price."},"name":{"type":"string","description":"Product name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not used in the standard business model; required only for marketplace model."},"subMerchantPrice":{"type":"decimal","description":"Amount to be transferred to the sub-merchant. Not used in the standard business model; required only for marketplace model."}}},"PaymentAuthSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}}
```


# Reporting

## Transaction Detail Reporting

> The reporting service returns the current status of payments, refund results, and fraud statuses. It works with both paymentConversationId and paymentId. At least one of these must be provided.

```json
{"openapi":"3.0.3","info":{"title":"Transaction Detail Reporting","version":"1.0.0"},"tags":[{"name":"Reporting","description":"Reporting endpoints"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/reporting/payment/details":{"get":{"summary":"Transaction Detail Reporting","description":"The reporting service returns the current status of payments, refund results, and fraud statuses. It works with both paymentConversationId and paymentId. At least one of these must be provided.","tags":["Reporting"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"},{"$ref":"#/components/parameters/ConversationIdQuery"},{"name":"paymentId","in":"query","required":true,"schema":{"type":"string"},"description":"Payment ID. Required if paymentConversationId is not sent.\n"},{"name":"paymentConversationId","in":"query","required":true,"schema":{"type":"string"},"description":"Conversation ID of the payment. Can be used to query by conversationId. Required if paymentId is not sent.\n"}],"responses":{"200":{"description":"Successful response — transaction detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingPaymentDetailsResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content type of the request body."},"LocaleQuery":{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["tr","en"]},"description":"Language code."},"ConversationIdQuery":{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Can be used to correlate request/response. Echoed back in the response as-is."}},"schemas":{"ReportingPaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"payments":{"type":"array","description":"Transactions returned by the query.","items":{"$ref":"#/components/schemas/ReportingPaymentDetailsItem"}}}}]},"BaseResponse":{"type":"object","properties":{"status":{"type":"string","description":"Indicates the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request (if present)."}}},"ReportingPaymentDetailsItem":{"type":"object","properties":{"paymentId":{"description":"Payment ID.","type":"string"},"paymentStatus":{"type":"integer","description":"Payment status.\n\n- **1** (Success)\n- **2** (Failure / INIT_THREEDS)\n- **3** (CALLBACK_THREEDS)\n","enum":[1,2,3]},"paymentRefundStatus":{"type":"string","description":"Refund status.\n\n- **NOT_REFUNDED**\n- **PARTIALLY_REFUNDED**\n- **TOTALLY_REFUNDED**\n"},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s surcharge/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s surcharge/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"paymentConversationId":{"type":"string","description":"Conversation ID of the payment."},"fraudStatus":{"type":"integer","description":"Fraud status per fraud filters. If the score is low, the payment is approved; if high, it is rejected.\nMerchants should ship goods only for status **1**; for **0**, they should wait for notification.\n- **1**: Approved\n- **0**: Under Review\n- **-1**: Rejected\n","enum":[-1,0,1]},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"connectorName":{"type":"string","description":"Connector/POS provider name."},"authCode":{"type":"string","description":"Auth code returned from the bank."},"threeDS":{"type":"boolean","description":"Whether the transaction used 3DS."},"phase":{"type":"string","description":"Payment phase."},"acquirerBankName":{"type":"string","description":"Acquiring bank/provider name."},"hostReference":{"type":"string","description":"hostReference value returned by the provider."},"createdDate":{"type":"string","description":"ISO-8601 creation time."},"cancels":{"type":"array","description":"List of cancel operations.","items":{"$ref":"#/components/schemas/ReportingCancel"}},"itemTransactions":{"type":"array","description":"Line-item level transaction breakdowns.","items":{"$ref":"#/components/schemas/ReportingItemTransaction"}}}},"ReportingCancel":{"type":"object","properties":{"refundId":{"description":"Refund/ID information for the cancel.","oneOf":[{"type":"string"},{"type":"integer"}]},"cancelConversationId":{"type":"string","description":"Conversation ID of the cancel operation."},"refundPrice":{"type":"decimal","description":"Cancel/refund amount."},"refundStatus":{"type":"integer","description":"Cancel/refund status code."},"createdDate":{"type":"string","description":"ISO-8601 creation time."},"currencyCode":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"authCode":{"type":"string","description":"Auth code returned from the bank."},"hostReference":{"type":"string","description":"hostReference value returned by the provider."}}},"ReportingItemTransaction":{"type":"object","properties":{"paymentTransactionId":{"description":"Line-item transaction ID.","type":"string"},"transactionStatus":{"type":"integer","description":"Line-item status.\n- **0**: In fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace: Waiting for Sub-merchant Approval)\n- **2**: Approved (Marketplace Approval Granted)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount."},"paidPrice":{"type":"decimal","description":"Distribution of collected amount at line-item level."},"merchantCommissionRate":{"type":"decimal","description":"Merchant surcharge/commission rate (line-item)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant surcharge/commission amount (line-item)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount (line-item)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee (line-item)."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate (line-item)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageRateAmountSubMerchant":{"type":"decimal","description":"Blockage amount reflected to the sub-merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution date (ISO-8601)."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant item amount."},"subMerchantPayoutRate":{"type":"decimal","description":"Rate of payout to sub-merchant."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after commissions and blockages."},"convertedPayout":{"$ref":"#/components/schemas/ReportingConvertedPayout"},"refunds":{"type":"array","description":"Line-item refunds.","items":{"$ref":"#/components/schemas/ReportingRefund"}}}},"ReportingConvertedPayout":{"type":"object","properties":{"paidPrice":{"type":"decimal","description":"Distribution of collected amount at line-item level."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount (line-item, after conversion)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee (line-item, after conversion)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant blockage amount (after conversion, merchant)."},"blockageRateAmountSubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount (after conversion)."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant (after conversion)."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant (after conversion)."},"iyziConversionRate":{"type":"decimal","description":"FX rate."},"iyziConversionRateAmount":{"type":"decimal","description":"Amount after applying the FX rate."},"currency":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ReportingRefund":{"type":"object","properties":{"refundTxId":{"description":"Refund transaction ID.","oneOf":[{"type":"string"},{"type":"integer"}]},"refundConversationId":{"type":"string","description":"Conversation ID of the refund."},"refundPrice":{"type":"decimal","description":"Refund amount."},"refundStatus":{"type":"integer","description":"Refund status code."},"isAfterSettlement":{"type":"boolean","description":"Was the refund processed after payout?"},"createdDate":{"type":"string","description":"ISO-8601 creation time."},"currencyCode":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"authCode":{"type":"string","description":"Auth code returned from the bank."},"hostReference":{"type":"string","description":"hostReference value returned by the provider."},"iyziCommissionRateAmount":{"type":"decimal","description":"Commission amount on the refund (if any)."}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Error code for the operation."},"errorMessage":{"type":"string","description":"Error message for the operation. Supports localization based on the locale parameter."},"errorGroup":{"type":"string","description":"Error group."}}}]}}}}
```

## Daily Transactions Reporting

> Returns the list of payment/cancel/refund operations that occurred on a specific date.

```json
{"openapi":"3.0.3","info":{"title":"Transaction Detail Reporting","version":"1.0.0"},"tags":[{"name":"Reporting","description":"Reporting endpoints"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/reporting/payment/transactions":{"get":{"summary":"Daily Transactions Reporting","description":"Returns the list of payment/cancel/refund operations that occurred on a specific date.","tags":["Reporting"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"},{"$ref":"#/components/parameters/ConversationIdQuery"},{"name":"page","in":"query","required":true,"schema":{"type":"integer","minimum":1},"description":"Page number (starts from 1)."},{"name":"transactionDate","in":"query","required":true,"schema":{"type":"string"},"description":"Date to query (YYYY-MM-DD). Example: `2025-07-24`.\n"}],"responses":{"200":{"description":"Successful response — daily transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingDailyTransactionsResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content type of the request body."},"LocaleQuery":{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["tr","en"]},"description":"Language code."},"ConversationIdQuery":{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Can be used to correlate request/response. Echoed back in the response as-is."}},"schemas":{"ReportingDailyTransactionsResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"transactions":{"type":"array","description":"Transactions on the specified day.","items":{"$ref":"#/components/schemas/ReportingDailyTransactionItem"}},"currentPage":{"type":"integer","description":"Current page number."},"totalPageCount":{"type":"integer","description":"Total number of pages."}}}]},"BaseResponse":{"type":"object","properties":{"status":{"type":"string","description":"Indicates the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request (if present)."}}},"ReportingDailyTransactionItem":{"type":"object","properties":{"transactionType":{"type":"string","description":"Transaction type.","enum":["CANCEL","PAYMENT","REFUND"]},"transactionDate":{"type":"string","description":"Transaction time (yyyy-MM-dd HH:mm:ss)."},"transactionId":{"description":"Transaction ID.","type":"string"},"transactionStatus":{"type":"integer","description":"Line-item status.\n- 0: In fraud review\n- -1: Rejected after fraud review\n- 1: Approved (In marketplace, 1 means Waiting for Sub-merchant Approval)\n- 2: Approved (Marketplace Approval Granted)\nenum: [ 0, -1, 1, 2 ]\n"},"afterSettlement":{"type":"integer","description":"Was it processed after payout? 0=No, 1=Yes (for REFUND).","enum":[0,1]},"paymentTxId":{"description":"Line-item payment transaction ID.","type":"string"},"paymentId":{"description":"Payment ID.","type":"string"},"conversationId":{"type":"string","description":"Conversation ID of the transaction (if any)."},"paymentPhase":{"type":"string","description":"Payment phase."},"price":{"type":"decimal","description":"Item/transaction amount."},"paidPrice":{"type":"decimal","description":"Collected amount."},"transactionCurrency":{"type":"string","description":"Transaction currency.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"installment":{"type":"integer","description":"Installment count."},"threeDS":{"type":"integer","description":"Was 3DS used? 0=No, 1=Yes.","enum":[0,1]},"settlementCurrency":{"type":"string","description":"Settlement currency.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"connectorType":{"type":"string","description":"Connector/POS provider type."},"posOrderId":{"type":"string","description":"POS order number."},"authCode":{"type":"string","description":"Bank auth code."},"hostReference":{"type":"string","description":"Provider hostReference value."},"basketId":{"type":"string","description":"Basket ID."},"iyzicoCommission":{"type":"decimal","description":"Commission (for PAYMENT)."},"iyzicoFee":{"type":"decimal","description":"Transaction fee (for PAYMENT)."},"parity":{"type":"decimal","description":"FX parity (for PAYMENT)."},"iyzicoConversionAmount":{"type":"decimal","description":"FX conversion amount (for PAYMENT)."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant (for PAYMENT)."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the sub-merchant (for PAYMENT)."}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Error code for the operation."},"errorMessage":{"type":"string","description":"Error message for the operation. Supports localization based on the locale parameter."},"errorGroup":{"type":"string","description":"Error group."}}}]}}}}
```


# API

#### Payments via API

The API integration allows you to accept payments **using your own payment form**. Instead of using iyzico’s hosted payment page, you can collect card details on your custom-designed checkout page and process the payment directly through iyzico’s APIs.

With the API, you can implement:

* **Non-3DS** payments, where the customer completes the payment without being redirected to the bank’s authentication page,
* **3DS** payments, where the customer is redirected to the bank’s 3D Secure page for an additional authentication step.

This section provides the technical details required to connect to iyzico using **your own payment form** and to implement both Non-3DS and 3DS payment flows.

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="/pages/vWOALYeBCByAwYRZO68u">Non-3DS</a></td></tr><tr><td><a href="/pages/iNgiC8QEc0t2t7hK2bRv">3DS</a></td></tr></tbody></table>


# Non-3DS

NON-3DS is an invaluable resource for businesses looking to streamline their payment processes and maximize efficiency. By leveraging the NON-3DS functionality offered by iyzico, businesses can easily initiate and manage payment transactions with ease.

{% hint style="info" %}
**IMPORTANT NOTE :** To use NON-3DS, you must have this feature in your iyzico account. To enable this feature, you can create this request by sending an e-mail to <entegrasyon@iyzico.com>.
{% endhint %}

Incorporating NON-3DS into your software solution allows you to provide a seamless and user-friendly payment experience for your customers. With the abilities of NON-3DS, merchants can focus on growing their business while leaving the complexities of payment processing to a trusted and reliable platform.

### Advantages

<div align="left"><figure><img src="/files/SLIv5ohc6w0izdZvoo3E" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/JNHjS4Y5qK1HKQR3B2e6" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/qjb1S88UovNwNWHnLRXe" alt="" width="188"><figcaption></figcaption></figure></div>

### Non-3DS Payment Flow

The Non-3DS payment process consists of selecting a credit card, entering the card information, and then finalizing the transaction.

<div><figure><img src="/files/9Fh8IccCrsEq7cQvbkCm" alt=""><figcaption></figcaption></figure> <figure><img src="/files/ONhWyRbxpxXHbyzRXImK" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/3bpJH1iUjhJ8WFtwwWUh" alt=""><figcaption></figcaption></figure> <figure><img src="/files/DEma2vE8b4eBEi1mMebm" alt=""><figcaption></figcaption></figure></div>

### Which Products Can It be Used with?

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/Pgl8HExhdPcF1FtoIlMT">/pages/Pgl8HExhdPcF1FtoIlMT</a></td><td></td><td></td></tr><tr><td><a href="/pages/IZR5VcY1BoQ3zPDVajzZ">/pages/IZR5VcY1BoQ3zPDVajzZ</a></td><td></td><td></td></tr><tr><td><a href="/pages/x32YqNIzXEIggyJzagrU">/pages/x32YqNIzXEIggyJzagrU</a></td><td></td><td></td></tr><tr><td><a href="/pages/91l0cOFxOgw6BTmbFtvA">/pages/91l0cOFxOgw6BTmbFtvA</a></td><td></td><td></td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td></td><td></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td></td><td></td></tr></tbody></table>


# NON-3DS Implementation

<figure><img src="/files/gI9Q5MNg8U6iasle7n81" alt=""><figcaption></figcaption></figure>

### **Integration Steps**

1. [BIN Check](#id-1.-bin-check)
2. [Create Payment](#id-2.-create-payment)
3. [Retrieve(Optional)](/en/payment-methods/api/non-3ds/non-3ds-implementation/retrieve)
4. [Webhook](/en/advanced/webhook)

### Top View

* [ ] BIN Check; section of identifying issuer details where API returns information about installment options and card details.
* [ ] Create Payment; essential requirement on managing payment request at one-step flow transactions.
* [ ] Retrieve(Optional); engage step to check transaction details of recorded payment by iyzico.
* [ ] Webhook; real-time notification of relevant payment.

{% @mermaid/diagram content="---
config:
look: classic
theme: darkMode
---------------

sequenceDiagram

%% START
Customer-->>Merchant: Ecom Journey (1)

%% CREATE PAYMENT PHASE - START
alt CREATE PAYMENT PHASE
Merchant-->>iyzico: POST ...payment/auth (2)
iyzico->>Acquirer: Authentication operations (3)
Acquirer->>iyzico: Acquirer response (4)
iyzico->>Merchant: --RESPONSE Payment Result (5)
end
%% CREATE PAYMENT PHASE - END

iyzico-->>Merchant: Webhook Notification (6)

%% RETRIEVE PAYMENT PHASE - START
opt RETRIEVE PAYMENT PHASE
Merchant-->>iyzico: POST ...payment/detail (6.1)
iyzico->>Merchant: --RESPONSE Payment Result (6.2)
end
%% RETRIEVE PAYMENT PHASE - START

Merchant-->>Customer: Confirmation of payment (7)
%% END" %}

### Sample Implementation

Even if essential NON-3DS implementation consists of 2 subsequent `POST` requests in short.

* [Create Payment](#id-2.-create-payment)
* [Retrieve(Optional)](/en/payment-methods/api/non-3ds/non-3ds-implementation/retrieve)

Suggested integration tracks following order;

### 1. BIN Check

Whether 3DS or NON-3DS payment method, It is advised to identify issuer card feature beforehand. BIN detail services provides further details of card type, card scheme, card association which indicates installment and 3DS features.

#### Sample Retrieve Installment Request;

{% code lineNumbers="true" %}

```json
{
"price":"100.0",
"binNumber":"535805"
}
```

{% endcode %}

#### Sample Retrieve Installment Response;

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685905139724,
    "installmentDetails": [
        {
            "binNumber": "535805",
            "price": 100.0,
            "cardType": "DEBIT_CARD",
            "cardAssociation": "MASTER_CARD",
            "cardFamilyName": "iyzico DC",
            "force3ds": 0,
            "bankCode": 864,
            "bankName": "iyzico",
            "forceCvc": 0,
            "commercial": 0,
            "dccEnabled": 0,
            "installmentPrices": [
                {
                    "installmentPrice": 100.0,
                    "totalPrice": 100.0,
                    "installmentNumber": 1
                }
            ]
        }
    ]
}
```

{% endcode %}

### 2. Create Payment

NON-3DS payment journey begins with [Create Payment](broken://pages/0o6OvsDWNRazC5vycUOy) `POST` request.

#### Sample Create Payment Request;

{% code lineNumbers="true" %}

```json
{
   "locale":"en",
   "conversationId":"deviyzico",
   "price":"10.01",
   "paidPrice":"10.01",
   "currency":"TRY",
   "installment":1,
   "paymentChannel":"WEB",
   "basketId":"B67832",
   "paymentGroup":"PRODUCT",
   "paymentCard":{
      "cardHolderName":"Mehmet Test",
      "cardNumber":"5526080000000006",
      "expireYear":"2028",
      "expireMonth":"11",
      "cvc":"245",
      "registerCard":0
   },
   "buyer":{
      "id":"BY789",
      "name":"John",
      "surname":"Doe",
      "identityNumber":"11111111111",
      "email":"test@testtt.com",
      "gsmNumber":"+905393623333",
      "registrationDate":"2013-04-21 15:12:09",
      "lastLoginDate":"2015-10-05 12:43:35",
      "registrationAddress":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "city":"Istanbul",
      "country":"Turkey",
      "zipCode":"34732",
      "ip":"85.34.78.112"
   },
   "shippingAddress":{
      "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "zipCode":"34742",
      "contactName":"Jane Doe",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "billingAddress":{
      "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "zipCode":"34742",
      "contactName":"Jane Doe",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "basketItems":[
      {
         "id":"BI101",
         "price":"10.01",
         "name":"Binocular",
         "category1":"Collectibles",
         "category2":"Accessories",
         "itemType":"PHYSICAL"
      }
   ]
}
```

{% endcode %}

#### Sample Create Payment Response;

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1686413012592,
    "conversationId": "deviyzico",
    "price": 10.01,
    "paidPrice": 10.01,
    "installment": 1,
    "paymentId": "19682125",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0.00,
    "iyziCommissionRateAmount": 0.40040000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Axess",
    "binNumber": "552608",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "20945921",
            "transactionStatus": 2,
            "price": 10.01,
            "paidPrice": 10.01000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.40040000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-18 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 9.35960000,
            "convertedPayout": {
                "paidPrice": 10.01000000,
                "iyziCommissionRateAmount": 0.40040000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 9.35960000,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "013627",
    "phase": "AUTH",
    "hostReference": "mock00007iyzihostrfn"
}
```

{% endcode %}

###

### 3. Retrieve(Optional)

After having completing all the steps above, Its now time to check payment operation between Issuer and Acquirer with [Retrieve](/en/payment-methods/api/non-3ds/non-3ds-implementation/retrieve) request.

{% hint style="danger" %}
Retrieve step is an additional precaution we advice our stakeholders to perform before shipping their products.
{% endhint %}

#### Sample Retrieve Request;

{% code lineNumbers="true" %}

```json
{  
   "locale":"tr",
   "paymentId":"19682125" //or "paymentConversationId":"deviyzico"
}
```

{% endcode %}

#### Sample Retrieve Response;

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1686413104142,
    "price": 10.01000000,
    "paidPrice": 10.01000000,
    "installment": 1,
    "paymentId": "19682125",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.40040000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Axess",
    "binNumber": "552608",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "20945921",
            "transactionStatus": 2,
            "price": 10.01000000,
            "paidPrice": 10.01000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.40040000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2023-06-18 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 9.35960000,
            "convertedPayout": {
                "paidPrice": 10.01000000,
                "iyziCommissionRateAmount": 0.40040000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 9.35960000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "013627",
    "phase": "AUTH",
    "hostReference": "mock00007iyzihostrfn",
    "paymentStatus": "SUCCESS"
}
```

{% endcode %}

### 4.Webhook

Webhooks are tail subject of our implementation streamline.&#x20;

Receiving real-time payment notifications leverages overall 3DS experience while ensuring that the notifications are coming from trusted sources, preventing any potential tampering or unauthorized access to sensitive data.&#x20;

Each payment event triggers webhooks;&#x20;

* In `15` seconds.&#x20;
* Until your server responds with `200`.
* For every `10` minutes.
* Max `3` times.

**Sample Auth 3DS Webhook**

| Parametere                | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| **iyziEventTime**         | long   | Unix timestamp value of first notification.                           |
| **iyziEventType**         | string | Shows the request type. Values: API\_AUTH, THREE\_DS\_AUTH, BKM\_AUTH |
| **iyziReferenceCode**     | string | A unique reference code for the notification                          |
| **paymentId**             | long   | Unique iyzico reference code of related payment                       |
| **paymentConversationId** | string | Merchant's reference id for the related payment                       |
| **status**                | string | Payment status. Values: SUCCESS, FAILURE                              |

Happy path includes `success` parameter in the `status` variable.

#### Confirmation

To finalize payment operations successfully, correlation of certain variables plays significant role;

* `paymentId`
* `status`
* `price`
* Other [Idempotency](file:///iyzico-dokuemantasyon/getting-started/preliminaries/idempotency) parameters optionally

&#x20;

Its vital that [Create Payment](broken://pages/0o6OvsDWNRazC5vycUOy) response and [Webhook](file:///iyzico-dokuemantasyon/advanced/webhook) notification have to authenticate each other.

* `paymentId` on [Create Payment](broken://pages/0o6OvsDWNRazC5vycUOy) response should be equal to `paymentId`from [Webhook](/en/advanced/webhook)
* Both of the `status` parameters should be `success`
* `price` parameter amounts should be the same
* And lastly, [Idempotency](/en/getting-started/preliminaries/idempotency) parameters should be the same as well.

If so, congratulations! Just finished NON-3DS implementation.

Transaction details could get from merchant panel.


# Create Payment

Create Payment API is responsible for processing the customer's card payments. When this service is used, iyzico provides an instant response regarding the success of the transaction.

* It supports transactions made with TROY, MASTERCARD, VISA, and AMEX branded cards.&#x20;
* For cards participating in installment programs such as BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, and ADVANTAGE, the service allows options for 2, 3, 6, 9, and 12 installments.
* Successful transactions are displayed in green, while failed transactions are displayed in red on the panel.&#x20;
* The merchant can utilize the conversationId and basketId parameters as order numbers on their side.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

## Create Non3D Payment

> Initiates a payment without 3D Secure.

```json
{"openapi":"3.0.3","info":{"title":"NON3D","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/auth":{"post":{"summary":"Create Non3D Payment","description":"Initiates a payment without 3D Secure.","tags":["Non3D Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paidPrice","price","currency","paymentCard","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"conversationId":{"type":"string","description":"Unique ID used to match request/response."},"locale":{"type":"string","description":"Language code. Allowed values; tr, en. Default; tr","enum":["tr","en"]},"paidPrice":{"type":"decimal","description":"Total amount to be charged from the buyer."},"price":{"type":"decimal","description":"Basket total amount."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"installment":{"type":"integer","description":"Installment count. If omitted, single payment (1) is applied.","enum":[1,2,3,6,9,12]},"basketId":{"type":"string","description":"Basket ID."},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer"},"shippingAddress":{"description":"Shipping address. Required if at least one of the basket items has itemType \"PHYSICAL\". Not required if all items are \"VIRTUAL\".","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Items in the basket.","items":{"$ref":"#/components/schemas/BasketItem"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header starting with IYZWSv2 and a signed hash value encoded in base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"PaymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireYear","expireMonth","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder full name."},"cardNumber":{"type":"string","description":"Card number."},"expireYear":{"type":"string","description":"Expiry year (YYYY format)."},"expireMonth":{"type":"string","description":"Expiry month (MM format)."},"cvc":{"type":"string","description":"CVC code."},"registerCard":{"type":"integer","description":"Save the card? (0 = no, 1 = yes)"}}},"Buyer":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number (TR)."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Phone number."},"registrationDate":{"type":"string","description":"Registration date (yyyy-MM-dd HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (yyyy-MM-dd HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Product ID."},"price":{"type":"decimal","description":"Product price."},"name":{"type":"string","description":"Product name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model. Required only for marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model. Required only for marketplace model."}}},"PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Indicates the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status per fraud filters. If the risk score is low, the payment is approved instantly; if high, the payment is declined. The merchant should ship products only for transactions with value 1; for 0, the merchant should wait for notification.\n - 1: Approved\n - 0: Under review\n - -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant's applied installment/commission rate. For example, if price=100 and paidPrice=110, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant's commission amount. For example, if price=100 and paidPrice=110, the commission amount is 10. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico transaction commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Payment line items for basket entries.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown. Must be stored by the merchant. Used for refund/approve/disapprove operations and communication with iyzico. Preferably stored in relation with itemId."},"itemId":{"type":"string","description":"ID of the item in the basket provided by the merchant."},"price":{"type":"decimal","description":"Amount of the item in the merchant's basket."},"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- 0: In fraud control\n- -1: Declined after fraud control\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace Approval Given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount per breakdown."},"blockageResolvedDate":{"type":"string","description":"Blockage release date per transaction. Format yyyy-MM-dd HH:mm:ss, e.g. 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate distributed per breakdown."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount distributed per breakdown."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Rate of the amount to be sent to the sub-merchant."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per breakdown.","properties":{"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"iyziConversationRate":{"type":"decimal","description":"Exchange rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the exchange rate."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Host reference value given by the bank for the payment."},"signature":{"type":"string","description":"Signature value that can be used for signature verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure info."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"errorGroup":{"type":"string","description":"Error group."},"locale":{"type":"string","description":"Language code."},"systemTime":{"type":"integer","description":"System time."},"conversationId":{"type":"string","description":"Request/response matching ID."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/create_payment.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/PaymentSample.java#L31">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/PaymentSample.cs#L12">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L479">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/create_payment.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/xs07eti/2-1-create-non3d-payment?sideView=agentMode">Postman</a></td></tr></tbody></table>

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers.

* The `status` parameter provides information about the status of the transaction. `success` indicates that the transaction has been successfully completed and the payment has been processed. `failure` indicates that the transaction has failed, and an error message related to the failure reason is provided.
* The `paymentStatus` parameter is null for this service.
* The `paymentId` and `paymentTransactionId` values should be stored for future reference and tracking.
* In the event of a failed transaction (`failure` status), the `errorCode`, `errorMessage`, and `errorGroup` parameters will be returned with corresponding values, providing details about the error.


# Retrieve

To retrieve the details of a transaction registered in iyzico, you can use the payment inquiry service.

The parameters that need to be sent to the service are as follows:

## Retrieve Payment Result

> Retrieves the result of a payment.

```json
{"openapi":"3.0.3","info":{"title":"NON3D","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/detail":{"post":{"summary":"Retrieve Payment Result","description":"Retrieves the result of a payment.","tags":["Non3D Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentId"],"properties":{"locale":{"type":"string","description":"Language code. Allowed values; tr, en. Default; tr","enum":["tr","en"]},"paymentId":{"type":"string","description":"Payment transaction ID."},"paymentConversationId":{"type":"string","description":"ConversationId of the payment transaction. Required if paymentId is not sent."}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponseTwo"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header starting with IYZWSv2 and a signed hash value encoded in base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"PaymentResponseTwo":{"type":"object","properties":{"status":{"type":"string","description":"Indicates the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status per fraud filters. If the risk score is low, the payment is approved instantly; if high, the payment is declined. The merchant should ship products only for transactions with value 1; for 0, the merchant should wait for notification.\n - 1: Approved\n - 0: Under review\n - -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant's applied installment/commission rate. For example, if price=100 and paidPrice=110, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant's commission amount. For example, if price=100 and paidPrice=110, the commission is 10. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico transaction commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Payment line items for basket entries.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown. Must be stored by the merchant. Used for refund/approve/disapprove operations and communication with iyzico. Preferably stored in relation with itemId."},"itemId":{"type":"string","description":"ID of the item in the basket provided by the merchant."},"price":{"type":"decimal","description":"Amount of the item in the merchant's basket."},"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- 0: In fraud control\n- -1: Declined after fraud control\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace Approval Given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount per breakdown."},"blockageResolvedDate":{"type":"string","description":"Blockage release date per transaction. Format yyyy-MM-dd HH:mm:ss, e.g. 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate distributed per breakdown."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount distributed per breakdown."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Rate of the amount to be sent to the sub-merchant."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per breakdown.","properties":{"paidPrice":{"type":"decimal","description":"Distributed collected amount per breakdown. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee distributed per breakdown."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount distributed per breakdown."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees, commissions and blockages are deducted for this breakdown."},"iyziConversationRate":{"type":"decimal","description":"Exchange rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the exchange rate."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Host reference value given by the bank for the payment."},"signature":{"type":"string","description":"Signature value that can be used for signature verification."},"paymentStatus":{"type":"string","description":"Shows the result of the payment process.","enum":["SUCCESS","FAILURE","INIT_THREEDS","CALLBACK_THREEDS"]}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure info."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"errorGroup":{"type":"string","description":"Error group."},"locale":{"type":"string","description":"Language code."},"systemTime":{"type":"integer","description":"System time."},"conversationId":{"type":"string","description":"Request/response matching ID."}}}}}}
```

#### Sample Codes<br>

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/retrieve_payment_result.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/PaymentSample.java#L324">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/PaymentSample.cs#L586">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L985">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/retrieve_payment_result.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/l0kyutg/2-2-retrieve-payment-result?sideView=agentMode">Postman</a></td></tr></tbody></table>


# 3DS

With iyzico robust and reliable 3DS infrastructure, payment transactions can handle with confidence, focusing on growing your business rather than worrying about payment complexities.

This powerful feature allows businesses to seamlessly handle secure online payments while providing a smooth user experience.

The documentation covers the entire process of integrating and utilizing the iyzico handled 3DS operations. It includes detailed explanations of the flow, step-by-step instructions, and code examples in various programming languages to assist developers in implementing this feature effectively.

### Advantages

<div align="left"><figure><img src="/files/bdvPj4AizkcD7EIN5AOW" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/6MyP3ulpGDW9OZ9iZ0gW" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/shF00wEZHHusWmkTDf8f" alt="" width="188"><figcaption></figcaption></figure></div>

### 3DS Payment Flow

The 3DS payment process involves selecting a credit card, entering card details, opting for 3D Secure payment, continuing to the next step, entering OTP received via SMS, and finalizing the transaction.

<div><figure><img src="/files/nuQVT8MCRhLWHKaQbTaV" alt=""><figcaption></figcaption></figure> <figure><img src="/files/wY2wIlW6vV8Q0O6zcpGy" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Jc3QJN6QZJwEcztpCrrL" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/ejOFTz3sflN87X1RmlXj" alt=""><figcaption></figcaption></figure> <figure><img src="/files/hkdFrBOPslTqg9vM4zZ8" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Iu38ueJ0ydVucBbwzLai" alt=""><figcaption></figcaption></figure></div>

### Which Products Can It be Used with?

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/Pgl8HExhdPcF1FtoIlMT">/pages/Pgl8HExhdPcF1FtoIlMT</a></td><td></td><td></td></tr><tr><td><a href="/pages/IZR5VcY1BoQ3zPDVajzZ">/pages/IZR5VcY1BoQ3zPDVajzZ</a></td><td></td><td></td></tr><tr><td><a href="/pages/x32YqNIzXEIggyJzagrU">/pages/x32YqNIzXEIggyJzagrU</a></td><td></td><td></td></tr><tr><td><a href="/pages/91l0cOFxOgw6BTmbFtvA">/pages/91l0cOFxOgw6BTmbFtvA</a></td><td></td><td></td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td></td><td></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td></td><td></td></tr></tbody></table>


# 3DS Implementation

<figure><img src="/files/zEygj3NmGHAXHVJTB9cM" alt=""><figcaption></figcaption></figure>

### Steps

1. [BIN Check](/en/advanced/installment-and-bin-service#bin-service)
2. [Init 3DS](/en/payment-methods/api/3ds/3ds-implementation/init-3ds)
3. ["threeDSHtmlContent" Decode](#id-3.-threedshtmlcontent-decode)
4. [Redirection](#id-4.-redirection)
5. [Auth 3DS](/en/payment-methods/api/3ds/3ds-implementation/auth-3ds)
6. [Webhook](/en/advanced/webhook)

### Top View

* [ ] BIN Check; section of identifying issuer details where API returns information about installment options and card details.
* [ ] Init 3DS; first `POST` request of managing two-step 3DS transactions.
* [ ] "threeDSHtmlContent"; base64 encrypted HTML page where your end-user expected to validate 3DS page OTP verification.
* [ ] Redirection; Following up consumers' payment, iyzico triggers correlated IPN(Instant Payment Notification) to given callbackUrl.
* [ ] Auth 3DS; engage step to officialize transaction between Acquirer and Issuer.
* [ ] Webhook; real-time notification of relevant payment.

{% @mermaid/diagram content="---
config:
look: classic
theme: darkMode
---------------

sequenceDiagram

```
%% START
Customer-->>Merchant: Ecom Journey (1)

%% INIT PHASE - START
alt INIT 3DS PHASE
    Merchant-->>iyzico: POST ...payment/3dsecure/initialize (2)
    iyzico->>Acquirer: 3DS authorization steps (2.1)
    Acquirer->>iyzico: 3DS authorization steps (2.2)
    iyzico->>Merchant:  --RESPONSE / "threeDSHtmlContent" (3)
end
%% INIT PHASE - END

%% CONSUMER OPERATIONS
Merchant-->>Merchant: Decodes "threeDSHtmlContent" (4)
Merchant-->>Customer: Renders 3DS Verify Page (5)
Customer-->>Merchant: Card holder validates their identity on 3DS page (6)

%% AUTH PHASE - START
alt AUTH 3DS PHASE
    Merchant-->>iyzico: POST ...payment/3dsecure/auth (7)
    iyzico->>Acquirer: Confirmation by MPI, DS, ACS (7.1)
    Acquirer->>iyzico: Confirmation by MPI, DS, ACS (7.2)
    iyzico->>Merchant: --RESPONSE Payment Result (8)
end
%% AUTH PHASE - END

iyzico -->> Merchant: Webhook Notification (9)
Merchant-->>Customer: Confirmation of payment (10)
%% END" %}
```

### Sample Implementation

3DS implementation consists of 2 subsequent `POST` requests in short.

* [Init 3DS](/en/payment-methods/api/3ds/3ds-implementation/init-3ds)
* [Auth 3DS](/en/payment-methods/api/3ds/3ds-implementation/auth-3ds)

Suggested integration tracks following order;

### 1. BIN Check

Whether 3DS or NON-3DS payment method, It is advised to identify issuer card feature beforehand. BIN detail services provides further details of card type, card scheme, card association which indicates installment and 3DS features.

#### Sample Retrieve Installment Request;

{% code lineNumbers="true" %}

```json
{
  "price":"100.0",
  "binNumber":"535805"
}
```

{% endcode %}

#### Sample Retrieve Installment Response;

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685905139724,
    "installmentDetails": [
        {
            "binNumber": "535805",
            "price": 100.0,
            "cardType": "DEBIT_CARD",
            "cardAssociation": "MASTER_CARD",
            "cardFamilyName": "iyzico DC",
            "force3ds": 0,
            "bankCode": 864,
            "bankName": "iyzico",
            "forceCvc": 0,
            "commercial": 0,
            "dccEnabled": 0,
            "installmentPrices": [
                {
                    "installmentPrice": 100.0,
                    "totalPrice": 100.0,
                    "installmentNumber": 1
                }
            ]
        }
    ]
}
```

{% endcode %}

### 2. Init 3DS

3DS payment journey begins with [Init 3DS](broken://pages/EYes0DUYqEgTjLMywGlb) `POST` request.

#### Sample Init 3DS Request;

{% code lineNumbers="true" %}

```json
{
    "locale": "en",
    "price": "3.2",
    "paidPrice": "3.2",
    "installment": 1,
    "paymentChannel": "WEB",
    "basketId": "B67832",
    "paymentGroup": "PRODUCT",
    "paymentCard": {
        "cardHolderName": "Dev iyzico",
        "cardNumber": "5526080000000006",
        "expireYear": "2023",
        "expireMonth": "11",
        "cvc": "200"
    },
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864791",
        "email": "email@email.com",
        "gsmNumber": "+905350000000",
        "registrationDate": "2013-04-21 15:12:09",
        "lastLoginDate": "2015-10-05 12:43:35",
        "registrationAddress": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34732",
        "ip": "85.34.78.112"
    },
    "conversationId": "deviyzico",
    "shippingAddress": {
        "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
        "zipCode": "34742",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "billingAddress": {
        "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
        "zipCode": "34742",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "basketItems": [
        {
            "id": "BI101",
            "price": "1.1",
            "name": "Binocular",
            "category1": "Collectibles",
            "category2": "Accessories",
            "itemType": "PHYSICAL"
        },
        {
            "id": "BI1012",
            "price": "2.1",
            "name": "Binocular",
            "category1": "Collectibles",
            "category2": "Accessories",
            "itemType": "PHYSICAL"
        }
    ],
    "currency": "TRY",
    "callbackUrl": "https://deviyzico.com/"
}n
```

{% endcode %}

In return It is expected to receive "`threeDSHtmlContent`" key-value with other pieces;

#### Sample Init 3DS Response;

{% code overflow="wrap" lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1685539494559,
    "conversationId": "deviyzico",
    "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg=="
}
```

{% endcode %}

### 3. "threeDSHtmlContent" Decode

"`threeDSHtmlContent`" represents encrypted 3DS form itself.&#x20;

Once we render encoded "`threeDSHtmlContent`" parameter from [Init 3DS](broken://pages/EYes0DUYqEgTjLMywGlb) response on the browser, 3DS screen will display in front of the consumer.&#x20;

#### Decoded "threeDSHtmlContent" Sandbox Sample;

{% code overflow="wrap" %}

```json
"threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg=="
```

{% endcode %}

#### Encoded "threeDSHtmlContent" Sandbox Sample;

```html
<!doctype html>
<html lang="en">
<head>
    <title>iyzico Mock 3D-Secure Processing Page</title>
</head>
<body>
<form id="iyzico-3ds-form" action="https://sandbox-api.iyzipay.com/payment/mock/init3ds" method="post">
    <input type="hidden" name="orderId" value="mock46-6876558008262395iyziord">
    <input type="hidden" name="bin" value="552608">
    <input type="hidden" name="successUrl" value="https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/success/27">
    <input type="hidden" name="failureUrl" value="https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/failure/27">
    <input type="hidden" name="confirmationUrl" value="https://sandbox-api.iyzipay.com/payment/mock/confirm3ds">
    
    <input type="hidden" name="PaReq" value="cab1604a-61bb-444d-8a15-dd6f38cddb63">
    <input type="hidden" name="termUrl" value="cab1604a-61bb-444d-8a15-dd6f38cddb63">
    <input type="hidden" name="md" value="cab1604a-61bb-444d-8a15-dd6f38cddb63">
    
</form>
<script type="text/javascript">
    document.getElementById("iyzico-3ds-form").submit();
</script>
</body>
</html>
```

#### An example of decoded threeDSHtmlContent interface on the browser;

<figure><img src="/files/0CtPZiHwW9peqHGVBdsl" alt=""><figcaption></figcaption></figure>

### 4. Redirection

Redirection phase ties [Init 3DS](broken://pages/EYes0DUYqEgTjLMywGlb) and [Auth 3DS](/en/payment-methods/api/3ds/3ds-implementation/auth-3ds) steps overall.

Following up cardholder OTP(One Time Password) confirmation iyzico will automatically redirect the page to the address given in the "callbackUrl" parameter. Redirection `POST`  includes;

| Input Name           | Type   | Description                                                                                    |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| **status**           | String | Service response result (success / failure)                                                    |
| **paymentId**        | String | If verification is successful, iyzico will return a paymentid. It must be set in Auth request  |
| **conversationData** | String | If verification is successful, iyzico might return. If returns, it must be set in Auth request |
| **conversationId**   | Long   | If set, conversation ID to match request and response                                          |
| **mdStatus**         | String | **1** for successful payment, **0,2,3,4,5,6,7,8** for failure payments                         |

#### mdStatuses

"`mdStatus`" interprets merchant plug-in responses on 3DS triangle.

While successful 3DS operations results with `"mdStatus":"1"` on "`callbackUrl",` failure scenarios might have one of the items from list below;

| mdStatus     | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| mdStatus = 0 | Invalid 3D Secure signature or verification                                  |
| mdStatus = 2 | Card holder or Issuer not registered to 3D Secure network                    |
| mdStatus = 3 | Issuer is not registered to 3D secure network                                |
| mdStatus = 4 | Verification is not possible, card holder chosen to register later on system |
| mdStatus = 5 | Verification is not possbile                                                 |
| mdStatus = 6 | 3D Secure error                                                              |
| mdStatus = 7 | System error                                                                 |
| mdStatus = 8 | Unknown card                                                                 |

### 5. Auth 3DS

After having completing all the steps above, Its now time to officialize payment operation between Issuer and Acquirer with [Auth 3DS](/en/payment-methods/api/3ds/3ds-implementation/auth-3ds) request.

#### Sample Init 3DS Request;

{% code lineNumbers="true" %}

```json
{
  "paymentId": "123456789"
}
```

{% endcode %}

#### Sample Init 3DS Response;

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685539637584,
    "price": 3.20000000,
    "paidPrice": 3.20000000,
    "installment": 1,
    "paymentId": "123456789",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.12800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "DEBIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamilyName": "iyzico DC",
    "binNumber": "535805",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "123456789",
            "transactionStatus": 2,
            "price": 1.10000000,
            "paidPrice": 1.10000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.04400000,
            "iyziCommissionFee": 0.08593750,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-08 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.97006250,
            "convertedPayout": {
                "paidPrice": 1.10000000,
                "iyziCommissionRateAmount": 0.04400000,
                "iyziCommissionFee": 0.08593750,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.97006250,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI1012",
            "paymentTransactionId": "123456788",
            "transactionStatus": 2,
            "price": 2.10000000,
            "paidPrice": 2.10000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.08400000,
            "iyziCommissionFee": 0.16406250,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-08 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 1.85193750,
            "convertedPayout": {
                "paidPrice": 2.10000000,
                "iyziCommissionRateAmount": 0.08400000,
                "iyziCommissionFee": 0.16406250,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 1.85193750,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "905307",
    "phase": "AUTH",
    "mdStatus": 1,
    "hostReference": "mock00007iyzihostrfn"
}
```

{% endcode %}

{% hint style="info" %}
**NOTE  :** `mdStatus` parameter will only appear on 3DS operations.
{% endhint %}

### 6. Webhook

Webhooks are tail subject of our implementation streamline.&#x20;

Receiving real-time payment notifications leverages overall 3DS experience while ensuring that the notifications are coming from trusted sources, preventing any potential tampering or unauthorized access to sensitive data.&#x20;

Each payment event triggers webhooks;&#x20;

* In `15` seconds.&#x20;
* Until your server responds with `200`.
* For every `10` minutes.
* Max `3` times.

**Sample Auth 3DS Webhook**

| Parametere                | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| **iyziEventTime**         | long   | Unix timestamp value of first notification.                           |
| **iyziEventType**         | string | Shows the request type. Values: API\_AUTH, THREE\_DS\_AUTH, BKM\_AUTH |
| **iyziReferenceCode**     | string | A unique reference code for the notification                          |
| **paymentId**             | long   | Unique iyzico reference code of related payment                       |
| **paymentConversationId** | string | Merchant's reference id for the related payment                       |
| **status**                | string | Payment status. Values: SUCCESS, FAILURE                              |

Happy path includes `success` parameter in the `status` variable.

#### Confirmation

To finalize payment operations successfully, correlation of certain variables plays significant role;

* `paymentId`
* `status`
* `price`
* Other [Idempotency](file:///iyzico-dokuemantasyon/getting-started/preliminaries/idempotency) parameters optionally

&#x20;

Its vital that [Auth 3DS](file:///iyzico-dokuemantasyon/oedeme-metotlari/3ds/3ds-implementation/auth-3ds) response and [Webhook](file:///iyzico-dokuemantasyon/advanced/webhook) notification have to authenticate each other.

* `paymentId` on [Auth 3DS](/en/payment-methods/api/3ds/3ds-implementation/auth-3ds) response should be equal to `paymentId`from Webhook
* Both of the `status` parameters should be `success`
* `price` parameter amounts should be the same
* And lastly, Idempotency parameters should be the same as well.

&#x20;

If so, congratulations! Just finished 3DS implementation.

Transaction details coudl getfrom merchant panel.<br>

### Which Products Can It be Used with?

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/Pgl8HExhdPcF1FtoIlMT">/pages/Pgl8HExhdPcF1FtoIlMT</a></td><td></td><td></td></tr><tr><td><a href="/pages/IZR5VcY1BoQ3zPDVajzZ">/pages/IZR5VcY1BoQ3zPDVajzZ</a></td><td></td><td></td></tr><tr><td><a href="/pages/x32YqNIzXEIggyJzagrU">/pages/x32YqNIzXEIggyJzagrU</a></td><td></td><td></td></tr><tr><td><a href="/pages/91l0cOFxOgw6BTmbFtvA">/pages/91l0cOFxOgw6BTmbFtvA</a></td><td></td><td></td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td></td><td></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td></td><td></td></tr></tbody></table>

### Advantages

* Faster integration
* Single 3DS method which covers 1.X.X or 2.X.X
* Easy to plug\&play among other iyzico APIs


# Init 3DS

[Init 3DS](/en/payment-methods/api/3ds/3ds-implementation/init-3ds) API is responsible for processing the customer's card payments with 3DS.&#x20;

As like Its ancestor [NON-3DS](/en/payment-methods/api/non-3ds);

* It supports transactions made with TROY, MASTERCARD, VISA, and AMEX branded cards.&#x20;
* For cards participating in installment programs such as BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, and ADVANTAGE, the service allows options for 2, 3, 6, 9, and 12 installments.
* Successful transactions are displayed in green, while failed transactions are displayed in red on the panel.&#x20;
* The merchant can utilize the conversationId and basketId parameters as order numbers on their side.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

## Initialize 3DS Payment

> Starts a 3D Secure session and returns an htmlContent value for 3DS authentication.

```json
{"openapi":"3.0.3","info":{"title":"3DS Payments","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/3dsecure/initialize":{"post":{"summary":"Initialize 3DS Payment","description":"Starts a 3D Secure session and returns an htmlContent value for 3DS authentication.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (3DS initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSInitializeRequest":{"type":"object","required":["price","paidPrice","callbackUrl","paymentCard","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Final amount to be charged to the customer."},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"installment":{"type":"integer","description":"Installment count (if omitted, a single installment is used).","enum":[1,2,3,4,6,9,12]},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"callbackUrl":{"type":"string","description":"Redirect URL after 3DS flow completes."},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard3DS"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer3DS"},"shippingAddress":{"description":"Shipping address. Required if at least one basket item has itemType \"PHYSICAL\". If all items are \"VIRTUAL\", it is not required.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Basket items.","items":{"$ref":"#/components/schemas/BasketItem"}}}},"PaymentCard3DS":{"type":"object","required":["cardHolderName","cardNumber","expireYear","expireMonth","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder’s full name."},"cardNumber":{"type":"string","description":"Card number (PAN)."},"expireYear":{"type":"string","description":"Expiration year (YY or YYYY)."},"expireMonth":{"type":"string","description":"Expiration month (MM)."},"cvc":{"type":"string","description":"Card security code."},"registerCard":{"type":"integer","description":"Save the card? (0 = no, 1 = yes)"}}},"Buyer3DS":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Identity/ID number."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"Mobile phone."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City code/name."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Main category."},"category2":{"type":"string","description":"Subcategory (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model; required only for marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model; required only for marketplace model."}}},"ThreeDSInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"threeDSHtmlContent":{"type":"string","description":"Base64-encoded HTML content of the 3DS verification screen."},"paymentId":{"type":"string","description":"Unique paymentId returned by iyzico."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/initialize_threeds.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/ThreedsSample.java#L36">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/ThreedsSample.cs#L12">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L1324">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/initialize_threeds.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/2i4nkq9/3-1-initialize-3d-payment">Postman</a></td></tr></tbody></table>

<br>

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers.

* The `status` parameter provides information about the status of the transaction. `success` indicates that the transaction has been successfully completed and the payment has been processed. `failure` indicates that the transaction has failed, and an error message related to the failure reason is provided.
* The `paymentStatus` parameter is null for this service.
* The `paymentId` and `paymentTransactionId` values should be stored for future reference and tracking.
* In the event of a failed transaction (`failure` status), the `errorCode`, `errorMessage`, and `errorGroup` parameters will be returned with corresponding values, providing details about the error.


# Auth 3DS

To retrieve the details of a transaction registered in iyzico, you can use the payment inquiry service.

The parameters that need to be sent to the service are as follows:

## Create 3DS Payment

> Finalizes the payment after successful 3D authentication.

```json
{"openapi":"3.0.3","info":{"title":"3DS Payments","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/3dsecure/auth":{"post":{"summary":"Create 3DS Payment","description":"Finalizes the payment after successful 3D authentication.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSAuthRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSAuthRequest":{"type":"object","required":["paymentId"],"properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"paymentId":{"type":"string","description":"Payment ID returned by the initialize call."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"conversationData":{"type":"string","description":"Data posted by the 3DS result. If present, it must be sent."}}},"PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters.\n- 1: Approved\n- 0: Under review\n- -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme/brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card product/family."},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment."},"itemTransactions":{"type":"array","description":"Line items per basket item.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Line-item ID; must be stored by the merchant (used for refund/approve operations)."},"itemId":{"type":"string","description":"Merchant-defined item ID in the basket."},"price":{"type":"decimal","description":"Item price on merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"transactionStatus":{"type":"integer","description":"Line item status.\n- 0: In fraud check\n- -1: Declined after fraud check\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage release date (yyyy-MM-dd HH:mm:ss)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission rate allocated to the line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission amount allocated to the line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant-side blockage amount."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Converted amount produced by the rate."}}}}}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"mdStatus":{"type":"integer","description":"3DS authentication result (1 means successful).","enum":[-1,0,1,2,3,4,5,6,7,8]},"hostReference":{"type":"string","description":"Host reference returned by the bank/acquirer."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/create_threeds_payment.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/ThreedsSample.java#L135">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/ThreedsSample.cs#L300">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L1412">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/create_threeds_payment.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/1fogzj5/3-2-create-3d-payment">Postman</a></td></tr></tbody></table>

## Auth 3DS v2 Request - Advanced Data Protection

\
At iyzico, following the recent HMACSHA256 update, we launched the `payment/v2/3dsecure/auth` endpoint alongside the existing `payment/3dsecure/auth` endpoint. This endpoint is used to finalize registered 3D payments and retrieve details of the corresponding transactions by including the final amount charged to the customer’s card, its conversationId and paymentId.

With this, more reliable validation techniques can be used to complete the respective payment. As mentioned on the [Response Signature Validation](/en/advanced/response-signature-validation), the variables listed in the request table, returned as a result of the payment request, play a crucial role in this process.

As shown on the [Response Signature Validation](/en/advanced/response-signature-validation), when a signature is generated for the encrypted payload on both sides and these signatures are equal, the respective payment is successfully completed.

The parameters that need to be sent to the service are as follows:

## Create 3DS v2 Payment

> After the verification step, both the v1 and the new-generation v2 endpoints can be used to finalize the payment. However, to align with more advanced and secure technologies, the use of the v2 endpoint is recommended.

```json
{"openapi":"3.0.3","info":{"title":"3DS v2 Payments","version":"1.0.2"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/v2/3dsecure/auth":{"post":{"summary":"Create 3DS v2 Payment","description":"After the verification step, both the v1 and the new-generation v2 endpoints can be used to finalize the payment. However, to align with more advanced and secure technologies, the use of the v2 endpoint is recommended.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSV2AuthRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSV2PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSV2AuthRequest":{"type":"object","required":["paymentId","paidPrice","basketId","currency"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"paymentId":{"type":"string","description":"Payment ID returned after 3DS initialization."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"paidPrice":{"type":"decimal","description":"Collected amount to be used in 3DS v2 completion. Must match the paidPrice sent in INIT 3DS."},"basketId":{"type":"string","description":"Basket ID (must match INIT 3DS basketId)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"],"description":"Currency. Default; TRY (must match the value sent in INIT 3DS)."}}},"ThreeDSV2PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters.\n- 1: Approved\n- 0: Under review\n- -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme/brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card product/family."},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment."},"itemTransactions":{"type":"array","description":"Line items per basket item.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Line-item ID; must be stored by the merchant (used for refund/approve operations)."},"itemId":{"type":"string","description":"Merchant-defined item ID in the basket."},"price":{"type":"decimal","description":"Item price on merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"transactionStatus":{"type":"integer","description":"Line item status.\n- 0: In fraud check\n- -1: Declined after fraud check\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage release date (yyyy-MM-dd HH:mm:ss)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission rate allocated to the line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission amount allocated to the line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant-side blockage amount."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Converted amount produced by the rate."}}}}}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"mdStatus":{"type":"integer","description":"3DS authentication result.\n- 1: Successful\n- 0,2-8: Failed\n","enum":[-1,0,1,2,3,4,5,6,7,8]},"hostReference":{"type":"string","description":"Host reference returned by the bank/acquirer."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/ThreedsSample.java#L157">Java</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/x8knzd4/3-2-create-3d-payment-v2?sideView=agentMode">Json</a></td></tr></tbody></table>

## Auth 3DS vs Auth v2 3DS

The `payment/3dsecure/auth` endpoint employs the standard 3D Secure 1.0 protocol, offering basic authentication with a simpler structure, making it easier for legacy systems to integrate. In contrast, the `payment/v2/3dsecure/auth` endpoint is built on the more advanced 3D Secure 2.0 protocol, which enhances security through richer data points for risk analysis and smoother integration with modern systems. While `payment/3dsecure/auth` is a reliable option for basic transactions, `payment/v2/3dsecure/auth` offers superior security, improved user experience, and better compliance with evolving payment regulations. We recommend transitioning to `payment/v2/3dsecure/auth` for these benefits.<br>


# Checkout Form (CF)

iyzico's payment form is a convenient and secure solution for online businesses to accept payments. It provides a user-friendly interface that simplifies the payment process for customers.&#x20;

By integrating iyzico's payment form into your website or mobile application, you can offer various payment options to your customers, including credit cards and digital wallets.

{% embed url="<https://www.youtube.com/watch?v=zmMPtyhtcco>" %}

With robust security measures, iyzico ensures that transactions are protected and sensitive customer data is kept secure. By using iyzico's payment form, you can enhance the payment experience for your customers and make your online payment operations more efficient.

### Advantages

<div align="left"><figure><img src="/files/fpZBFyx8u4LdHgPEpIOG" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/cZJuniLo3foHmqT45CVy" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/ppx4ia0e25ffvCSiVPdH" alt="" width="188"><figcaption></figcaption></figure></div>

### Checkout Form Payment Flow

You can make your payment either by credit card, money order/EFT, credit or by scanning the QR code given to you in the Checkout Form.

<div align="left"><figure><img src="/files/uREXr04A7P7NyKJCM8r4" alt=""><figcaption></figcaption></figure> <figure><img src="/files/a2UfKBxxmXo1jj0WJrw5" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/HVJaNpteYbwsbgymAkM5" alt=""><figcaption></figcaption></figure> <figure><img src="/files/o8mMnlrVRhZQ3ipxeQAl" alt=""><figcaption></figcaption></figure></div>


# CF Implementation

<figure><img src="/files/D3xcFrOU5aVqLL97oWKK" alt=""><figcaption></figcaption></figure>

CF(Checkoutform) technically consists of 2(two) basic steps as like [PWI](/en/payment-methods/paywithiyzico);

* [CF-Initalize](/en/payment-methods/checkoutform/cf-implementation/cf-initialize)
* [CF-Retrieve](/en/payment-methods/checkoutform/cf-implementation/cf-retrieve)

**CF-Initialize** is where we start the payment process.\
While **CF-Retrieve** step is retrieving payment result, simply.

### Implementation Steps

1. [Usage](#usage)
2. [CF - Initialize](/en/payment-methods/checkoutform/cf-implementation/cf-initialize)
3. Redirection
4. [CF - Retrieve](/en/payment-methods/checkoutform/cf-implementation/cf-retrieve)
5. [Webhook](/en/advanced/webhook)

### Top View

* [ ] Usage; decision making of payment form which is available in pop-up, responsive, iframe or redirection forms.
* [ ] CF-Initialize; first `POST` request of managing two-step CF transactions.
* [ ] Redirection; Following up consumers' payment, iyzico triggers correlated IPN(Instant Payment Notification) to given callbackUrl.
* [ ] CF-Retrieve; engage step to officialize transaction between Acquirer and Issuer.
* [ ] Webhook; real-time notification of relevant payment.

### UML Diagram

<figure><img src="/files/JKPkeOHQUHLcfHzwQ13q" alt=""><figcaption></figcaption></figure>

### Usage

CF(Checkoutform) offers multiple way of forms on the browsers;&#x20;

#### Responsive

```html
<div id="iyzipay-checkout-form" class="responsive"></div>
```

#### Pop-up

```html
<div id="iyzipay-checkout-form" class="popup"></div>
```

#### iFrame

* It requires to add `&iframe=true` postfix to `paymentPageUrl` parameter that returns after CF-Initialize request.

#### Redirection

* Most common method where direct routing of `paymentPageUrl` on the application.


# CF-Initialize

This is the quickest and easiest way to complete your payments. It allows for a seamless payment process without the need for additional queries such as card front side checks, BIN queries, installment queries, 3D Secure checks, or card information saving integrations. By following this process, you can ensure a smooth and efficient integration with iyzico, providing a streamlined payment experience for your customers.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

## Checkout Form (CF) Initialize

> Starts a Checkout Form session and returns \`checkoutFormContent\` / \`paymentPageUrl\` and a \`token\` to render the payment page.

```json
{"openapi":"3.0.3","info":{"title":"Checkout Form (CF)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/initialize/auth/ecom":{"post":{"summary":"Checkout Form (CF) Initialize","description":"Starts a Checkout Form session and returns `checkoutFormContent` / `paymentPageUrl` and a `token` to render the payment page.","tags":["CheckoutForm"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (CF initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFInitializeResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with **IYZWSv2** and is a signed hash generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"CFInitializeRequest":{"type":"object","required":["price","paidPrice","currency","callbackUrl","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`. Send `en` to render the form in English.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned unchanged in the response."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Total amount to be charged."},"currency":{"type":"string","description":"Currency. Default is `TRY`.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default is `PRODUCT`.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"callbackUrl":{"type":"string","description":"Merchant URL that iyzico calls to deliver both success and failure results. Must have a valid SSL certificate."},"enabledInstallments":{"type":"array","description":"Available installment options.","items":{"type":"integer"}},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/BuyerCF"},"shippingAddress":{"description":"Shipping address. Required if at least one basket item is `PHYSICAL`. If all items are `VIRTUAL`, it is not required.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Basket items.","items":{"$ref":"#/components/schemas/BasketItem"}}}},"BuyerCF":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Mobile phone number."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD hh:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD hh:mm:ss)."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model. Required only for the marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model. Required only for the marketplace model."}}},"CFInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."},"token":{"type":"string","description":"Unique token generated for the checkout form. Mandatory to retrieve the payment result."},"checkoutFormContent":{"type":"string","description":"HTML content of the payment form (Base64-encoded)."},"paymentPageUrl":{"type":"string","description":"URL of iyzico’s hosted payment page (Common Payment Page)."},"signature":{"type":"string","description":"Signature value that can be used for integrity verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/initialize_checkout_form.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/CheckoutFormSample.java#L21">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/CheckoutFormSample.cs#L12">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L270">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/initialize_checkout_form.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/pxn0vt0/1-initialize-checkout-form">Postman</a></td></tr></tbody></table>


# CF-Retrieve

When the card details are entered in the payment form and the "Pay X TL" button is pressed, iyzico will redirect to the `callbackUrl` address that you specified during the creation of the payment form. At this address, a `token` value will be posted by iyzico. To view additional details about the payment results, a second query must be made using this `token`.

Following service represents the usage of token;

## Checkout Form (CF) Retrieve

> After the CF payment form is completed, queries the result using the \`token\`.

```json
{"openapi":"3.0.3","info":{"title":"Checkout Form (CF)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/auth/ecom/detail":{"post":{"summary":"Checkout Form (CF) Retrieve","description":"After the CF payment form is completed, queries the result using the `token`.","tags":["CheckoutForm"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFRetrieveRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CFRetrieveResponse"}}}},"400":{"description":"Failed response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with **IYZWSv2** and is a signed hash generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"CFRetrieveRequest":{"type":"object","required":["token"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned unchanged in the response."},"token":{"type":"string","description":"Token returned in the CF initialize response."}}},"CFRetrieveResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Number of installments."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is **1**; for **0**, wait for notification.\n - **1**: Approved\n - **0**: In review\n - **-1**: Rejected\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate. For example, if price=100 and paidPrice=110, the rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount. Example; 10 when price=100 and paidPrice=110. Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico processing commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico processing fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Line items corresponding to basket items.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"ID for the payment line item. Must be stored by the merchant. Used for refund/capture/void and when communicating with iyzico (ideally stored together with `itemId`)."},"itemId":{"type":"string","description":"Merchant-provided ID of the item in the basket."},"price":{"type":"decimal","description":"Item amount on the merchant’s side."},"paidPrice":{"type":"decimal","description":"Collected amount distributed per line item. Must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Status of the payment line item.\n- **0**: In fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (in Marketplace, 1 means “Awaiting Merchant Approval”)\n- **2**: Approved (Marketplace approval granted)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for this line item. According to the iyzico–merchant agreement, a per-transaction blockage may be applied to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant. If the blockage exceeds the merchant amount, it is reflected to the sub-merchant as well."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution datetime for this line item. Format **yyyy-MM-dd HH:mm:ss** (e.g., 2015-10-19 14:36:52)."},"iyziCommissionFee":{"type":"decimal","description":"Portion of iyzico processing fee distributed to this line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"Portion of iyzico processing commission distributed to this line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate distributed to this line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount distributed to this line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant for this line item after fees/commissions and blockages."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount per line item (must be stored)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico processing fee distributed to this line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico processing commission distributed to this line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage reflected to the merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/commissions and blockages."},"iyziConversionRate":{"type":"decimal","description":"Conversion rate."},"iyziConversionRateAmount":{"type":"decimal","description":"Amount resulting from the conversion rate."}}}}},"currency":{"type":"string","description":"Currency of the payment."}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Bank-provided host reference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for integrity verification."},"token":{"type":"string","description":"Checkout Form token value."},"callbackUrl":{"type":"string","description":"Callback URL."},"paymentStatus":{"type":"string","description":"Result of the payment."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID that matches the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/retrieve_checkout_form_result.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/CheckoutFormSample.java#L118">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/CheckoutFormSample.cs#L106">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L349">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/retrieve_checkout_form_result.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/j1zgmyj/2-retrieve-checkout-form-result">Postman</a></td></tr></tbody></table>

<br>


# CF Sample Imp.

In this document, we will delve into the comprehensive [Implementation Steps](/en/payment-methods/checkoutform/cf-implementation#implementation-steps) of [CF](/en/payment-methods/checkoutform) with [Redirection Form](https://iyzico-new-documentation.gitbook.io/iyzico-dokuemantasyon/payment-methods/cf-checkout-form/cf-implementation#redirection) and provide sample requests, responses, and best practices for a fast, easy, and secure integration.

### Pre-Requirements;

Before proceeding, please ensure that you have the following pre-requisites in place:

* [A sandbox account](/en/getting-started/preliminaries/sandbox)
* [Pair of API & Secret keys](broken://pages/19BoREI5VXROn8YuzMLc)
* A software tool to manage API calls; [Postman](/en/getting-started/preliminaries/postman-collections), Insonmina, Github clients

If so, keep going.

### Overview

The implementation of [CF](/en/payment-methods/checkoutform) requires two subsequent `POST` requests to be orchestrated one after the other.

In short;

* First, we will illustrate a **CF-Initialize** `POST` request.
* Then, we will cover up with **CF-Retrieve** `POST` section.

### Steps

1. [CF-Initialize](#step-1-cf-initialize)
2. [Token + URL](#step-2-token--url)
3. [Redirection](#step-3-redirection)
4. [CF-Retrieve](#step-4-cf-retrieve)
5. [Webhook](#step-5-webhook)

### Step 1 - CF Initialize

CF implementation begins with [PWI-Initialize](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-initialize) `POST` request.

This step involves sending a POST request and the request body contains various parameters such as locale, conversationId, price, basketId, paymentGroup, callbackUrl, currency, paidPrice, enabledInstallments, buyer details, shipping address, billing address, and basket items.

The following object is a sample C&#x46;**-Initialize** request body.

\
**Sample CF-Initialize Request;**

{% code lineNumbers="true" %}

```json
{
   "locale":"en",
   "conversationId":"sampleConversationId",
   "price":"5.2",
   "basketId":"B67832",
   "paymentGroup":"PRODUCT",
   "buyer":{
      "id":"BY789",
      "name":"Higher",
      "surname":"Faster",
      "identityNumber":"74300864791",
      "email":"stronger@implementation.com",
      "gsmNumber":"+905555434332",
      "registrationAddress":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "city":"Istanbul",
      "country":"Turkey",
      "ip":"85.34.78.112"
   },
   "shippingAddress":{
      "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "contactName":"Jane Doe",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "billingAddress":{
      "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "contactName":"Jane Doe",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "basketItems":[
      {
         "id":"BI101",
         "price":"5.2",
         "name":"Binocular",
         "category1":"Category 1",
         "itemType":"PHYSICAL"
      }
   ],
   "callbackUrl":"YOUR_CALLBACKURL",
   "currency":"TRY",
   "paidPrice":"5.2",
   "paymentSource":"zooz",
   "enabledInstallments":[
       2,3
   ]
}
```

{% endcode %}

Once you have triggered above request, there are 3(three) scenarios you will monitor mostly.\
Happy path includes a variable called, `paymentPageUrl`.

{% code overflow="wrap" lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1687112732811,
    "conversationId": "sampleConversationId",
    "token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
    "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"a5b67652-c24a-4347-b61e-6c957bf30f1b\",price:5.20,locale:\"en\",baseUrl:\"https://sandbox-api.iyzipay.com\", merchantGatewayBaseUrl:\"https://sandbox-merchantgw.iyzipay.com\", registerCardEnabled:true,bkmEnabled:true,bankTransferEnabled:true,bankTransferTimeLimit:{\"value\":5,\"type\":\"day\"},bankTransferRedirectUrl:\"YOUR_CALLBACKURL\",bankTransferCustomUIProps:{},campaignEnabled:false,campaignMarketingUiDisplay:null,paymentSourceName:\"zooz\",plusInstallmentResponseList:null,payWithIyzicoSingleTab:true,payWithIyzicoOneTab:false,mixPaymentEnabled:true,creditCardEnabled:true,bankTransferAccounts:[{\"iban\":\"TR020006200035600006294884\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Garanti Bankası\",\"bankId\":62,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/62.svg\"},{\"iban\":\"TR080006400000111351092786\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"İş Bankası\",\"bankId\":64,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/64.svg\"},{\"iban\":\"TR340004600786888000080896\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Akbank\",\"bankId\":46,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/46.svg\"},{\"iban\":\"TR910006701000000096073759\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Yapı Kredi Bankası\",\"bankId\":67,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/67.svg\"},{\"iban\":\"TR760001001187768823545001\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Ziraat Bankası\",\"bankId\":10,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/10.svg\"}],userCards:[],fundEnabled:true,memberCheckoutOtpData:{},force3Ds:false,isSandbox:true,storeNewCardEnabled:true,paymentWithNewCardEnabled:true,enabledApmTypes:[\"SOFORT\",\"IDEAL\",\"QIWI\",\"GIROPAY\"],payWithIyzicoUsed:false,payWithIyzicoEnabled:true,payWithIyzicoCustomUI:{},buyerName:\"Higher\",buyerSurname:\"Faster\",merchantInfo:\"\",merchantName:\"Sandbox Merchant Name - 3389550\",cancelUrl:\"\",buyerProtectionEnabled:false,hide3DS:false,gsmNumber:\"+905555434332\",email:\"stronger@implementation.com\",checkConsumerDetail:{},subscriptionPaymentEnabled:false,ucsEnabled:false,fingerprintEnabled:false,payWithIyzicoFirstTab:false,creditEnabled:true,payWithIyzicoLead:false,goBackUrl:\"\",metadata : {},createTag:function(){var iyziJSTag = document.createElement('script');iyziJSTag.setAttribute('src','https://sandbox-static.iyzipay.com/checkoutform/v2/bundle.js?v=1687112732810');document.head.appendChild(iyziJSTag);}};iyziInit.createTag();}</script>",
    "tokenExpireTime": 1800,
    "paymentPageUrl": "https://sandbox-cpp.iyzipay.com?token=a5b67652-c24a-4347-b61e-6c957bf30f1b&lang=en",
    "payWithIyzicoPageUrl": "https://sandbox-ode.iyzico.com/?token=a5b67652-c24a-4347-b61e-6c957bf30f1b&lang=en"
}
```

{% endcode %}

### Step 2 - Token + URL

Hereby, `token` and `paymentPageUrl` are essential knots of for the rest of payment journey.&#x20;

In this step, you need to extract the token and `paymentPageUrl` from the response obtained in the previous step. The token should be saved for later validation, and the `paymentPageUrl` is used to redirect the user to the payment page.

* **token;** Its expected that merchants saves `token` parameter to confront and validate payment at the very end of payment journey.
* `paymentPageUrl`**;** where payment page appears briefly. Redirection to `paymentPageUrl` provides an interface to accomplish checkouts safely for end-users.

#### An example of `paymentPageUrl` interface on the browser;

<div align="left"><figure><img src="/files/EPDIiweoWv5nzIzGJWny" alt=""><figcaption></figcaption></figure></div>

### Step 3 - Redirection

Redirection phase ties [CF-Initialize](/en/payment-methods/checkoutform/cf-implementation/cf-initialize) and [CF-Retrieve](/en/payment-methods/checkoutform/cf-implementation/cf-retrieve) steps overall.

Following up end user interact on CF payment page, iyzico will automatically redirect the page to the address given in the "callbackUrl" parameter. Redirection `POST`  includes;

| Input Name | Type   | Description                                                                                          |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| **token**  | String | Unique value created for each checkout form request. This token is used to access the payment result |

{% hint style="info" %}

{% endhint %}

### Step 4 - CF Retrieve

**CF-Retrieve** is the last step of PWI chain.

Basically, we have just accepted a payment on the previous step.\
It is now time to legalize the transaction in this step.\
The following example is a sample **CF-Retrieve** request body.

**Sample CF-Retrieve Request;**

{% code lineNumbers="true" %}

```json
{
    "locale": "en",
    "token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
    "conversationId": "sampleConversationId"
}
```

{% endcode %}

Once you have triggered above request, there are 2(two) scenarios you will monitor mostly.\
Happy path includes `SUCCESS` parameter in the `paymentStatus` variable.

**Sample CF-Retrieve Response;**

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1687113618054,
    "conversationId": "sampleConversationId",
    "price": 5.20000000,
    "paidPrice": 5.20000000,
    "installment": 1,
    "paymentId": "19831123",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.20800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "TROY",
    "cardFamily": "Cardfinans",
    "binNumber": "979203",
    "lastFourDigits": "0000",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "21097896",
            "transactionStatus": 2,
            "price": 5.20000000,
            "paidPrice": 5.20000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.20800000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2023-06-26 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 4.74200000,
            "convertedPayout": {
                "paidPrice": 5.20000000,
                "iyziCommissionRateAmount": 0.20800000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 4.74200000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "104530",
    "phase": "AUTH",
    "mdStatus": 1,
    "hostReference": "mock00037iyzihostrfn",
    "token": "3ee2d355-da4d-47ce-bd3d-13d8c1854128",
    "callbackUrl": "YOUR_CALLBACKURL",
    "paymentStatus": "SUCCESS"
}
```

{% endcode %}

{% hint style="info" %}
`mdStatus` parameter will only appear on 3DS operations.

Please check further details around mdStatus [here](https://iyzico-new-documentation.gitbook.io/iyzico-dokuemantasyon/payment-methods/3ds/3ds-implementation#mdstatuses).
{% endhint %}

### Step 5 - Webhook

Webhooks are tail subject of our implementation streamline.&#x20;

Receiving real-time payment notifications leverages overall CF experience while ensuring that the notifications are coming from trusted sources, preventing any potential tampering or unauthorized access to sensitive data.&#x20;

Each payment event triggers webhooks;&#x20;

* In `15` seconds.&#x20;
* Until your server responds with `200`.
* For every `10` minutes.
* Max `3` times.

**Sample PWI Webhook**

| Parametere                | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| **iyziEventTime**         | long   | Unix timestamp value of first notification.                           |
| **iyziEventType**         | string | Shows the request type. Values: API\_AUTH, THREE\_DS\_AUTH, BKM\_AUTH |
| **iyziReferenceCode**     | string | A unique reference code for the notification                          |
| **paymentId**             | long   | Unique iyzico reference code of related payment                       |
| **paymentConversationId** | string | Merchant's reference id for the related payment                       |
| **status**                | string | Payment status. Values: SUCCESS, FAILURE                              |

Happy path includes `success` parameter in the `status` variable.

#### Confirmation

To finalize payment operations successfully, correlation of certain variables plays significant role;

* `paymentId`
* `status`
* `price`
* Other [Idempotency](file:///iyzico-dokuemantasyon/getting-started/preliminaries/idempotency) parameters optionally

&#x20;

[CF-Retrieve](/en/payment-methods/checkoutform/cf-implementation/cf-retrieve) response and [Webhook](file:///iyzico-dokuemantasyon/advanced/webhook) notification have to authenticate each other.

It is crucial to cross-verify the response received from [CF-Retrieve](/en/payment-methods/api/non-3ds/non-3ds-implementation/retrieve) and the data received in the [Webhook](/en/advanced/webhook) notification. Match the paymentId, status, price, and other relevant parameters to ensure the authenticity and correctness of the transaction.

* `paymentId` on [CF-Retrieve](/en/payment-methods/checkoutform/cf-implementation/cf-retrieve) response should be equal to `paymentId`from Webhook
* Both of the `status` parameters should be `success`
* `price` parameter amounts should be the same
* And lastly, Idempotency parameters should be the same as well.

&#x20;

If so, congratulations! Just finished PWI implementation.

Transaction details could get from merchant panel.

{% hint style="info" %}
Please note that the provided sample requests and responses are for illustration purposes only, and you should adapt them to your specific implementation requirements and API documentation.
{% endhint %}


# PayWithiyzico (PWI)

Those who are without a debit card or bank account, who want to pay for their online shopping effortlessly, who wish to view all their purchases in one app, and those who are waiting for 24/7 live support on their payments…

Meet the easiest way to pay!

By selecting “Pay with iyzico” feature in tens of thousands of websites, youcan securely pay with either using the balance on your iyzico account or your saved card or even by making money/electronic funds transfer.\
\
Moreover, all your shopping made by selecting “Pay with iyzico” are withinthe scope of iyzico Buyer Protection! This means you can get 24/7 live support and benefit from ease in refunds process!

effectively.

### Advantages

<div align="left"><figure><img src="/files/vD0EVvQjpA6BgbPV0eFt" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/pXvglIdNWqh2u9wZXRhd" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/7Z8Gw6S4uCPaxuvsXumV" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/XAT2f595cd0xO5ZD6s3v" alt="" width="188"><figcaption></figcaption></figure></div>

### PWI Payment Flow

<div align="left"><figure><img src="/files/P8ki7LfoZp4gptsNGKgQ" alt=""><figcaption></figcaption></figure> <figure><img src="/files/YalBn3DLhBuVaTmueh9h" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/PtKNDSYOMHnc31FW1U24" alt=""><figcaption></figcaption></figure> <figure><img src="/files/sTraAT3XP4XG9sh68CJY" alt=""><figcaption></figcaption></figure></div>

### Which Products Can It be Used with?

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/Pgl8HExhdPcF1FtoIlMT">/pages/Pgl8HExhdPcF1FtoIlMT</a></td><td></td><td></td></tr><tr><td><a href="/pages/IZR5VcY1BoQ3zPDVajzZ">/pages/IZR5VcY1BoQ3zPDVajzZ</a></td><td></td><td></td></tr><tr><td><a href="/pages/x32YqNIzXEIggyJzagrU">/pages/x32YqNIzXEIggyJzagrU</a></td><td></td><td></td></tr><tr><td><a href="/pages/91l0cOFxOgw6BTmbFtvA">/pages/91l0cOFxOgw6BTmbFtvA</a></td><td></td><td></td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td></td><td></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td></td><td></td></tr></tbody></table>


# PWI Implementation

<figure><img src="/files/QbWuvaYSC3RVTMCItgK6" alt=""><figcaption></figcaption></figure>

PWI technically consists of 2(two) basic steps respectively;

* [PWI - Initialize](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-initialize)
* [PWI - Retrieve](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-retrieve)

**PWI - Initialize** is where we start the payment process.\
While **PWI - Retrieve** step is retrieving payment result, simply.

### Implementation Steps

1. [PWI-Initialize](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-initialize)
2. Token + URL
3. Redirection
4. [PWI-Retrieve](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-retrieve)
5. [Webhook](/en/advanced/webhook)

### Top View

* [ ] Initialize; first `POST` request of managing two-step PWI transactions.
* [ ] Token + URL; To start payment process, Its expected to render `payWithIyzicoPageUrl` parameter on your browser which correlates by `token`.
* [ ] Redirection; Following up consumers' payment, iyzico triggers correlated IPN(Instant Payment Notification) to given callbackUrl.
* [ ] Retrieve; engage step to officialize transaction between Acquirer and Issuer.
* [ ] Webhook; real-time notification of relevant payment.


# PWI-Initialize

After making the request mentioned below, you will receive the payWithIyzicoPageUrl value, which is a unique page where your customers will be directed to Pay with iyzico. Your customers will be automatically redirected to the callBackUrl you specified in the Pay-with-iyzico init request after completing the payment process.

You can display the generated link as a button, link, or div on your payment page. The token received with the link can be stored at this stage or when it is posted to callBackUrl if the customer continues the payment process. Please note that the generated link and token values are valid for 30 minutes. If no payment is received during this period, the token will expire.

{% hint style="info" %}
callBackUrl address should have SSL.
{% endhint %}

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

## Pay with iyzico (PWI) — Initialize

> Starts a PWI session; returns the token and page URL for redirection.

```json
{"openapi":"3.0.3","info":{"title":"Pay with iyzico (PWI)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/pay-with-iyzico/initialize":{"post":{"summary":"Pay with iyzico (PWI) — Initialize","description":"Starts a PWI session; returns the token and page URL for redirection.","tags":["Pay with iyzico"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (PWI initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiInitializeResponse"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; starts with IYZWSv2 and is a signed hash in Base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"}}},"schemas":{"PwiInitializeRequest":{"type":"object","required":["price","basketId","callbackUrl","currency","paidPrice","buyer","billingAddress","shippingAddress","basketItems"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"conversationId":{"type":"string","description":"Request/response correlation ID."},"price":{"type":"decimal","description":"Basket total amount."},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","enum":["PRODUCT","LISTING","SUBSCRIPTION"],"description":"Payment group."},"callbackUrl":{"type":"string","description":"URL to redirect after the transaction."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"],"description":"Currency. Default; TRY."},"paidPrice":{"type":"decimal","description":"Amount to be collected."},"paymentChannel":{"type":"string","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"],"description":"Payment channel."},"enabledInstallments":{"type":"array","items":{"type":"integer","enum":[1,2,3,6,9,12]},"description":"Installment options to offer."},"buyer":{"$ref":"#/components/schemas/PwiBuyer"},"shippingAddress":{"$ref":"#/components/schemas/PwiAddress","description":"Shipping Address. Required if at least one basket item is PHYSICAL. If all items are VIRTUAL, this is not required."},"billingAddress":{"$ref":"#/components/schemas/PwiAddress"},"basketItems":{"type":"array","description":"Basket items.","minItems":1,"items":{"$ref":"#/components/schemas/PwiBasketItem"}}}},"PwiBuyer":{"type":"object","description":"Buyer information","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country","ip"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number (e.g., TR ID)."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"Mobile phone number."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"ip":{"type":"string","description":"IP address."},"zipCode":{"type":"string","description":"Postal code."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD hh:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD hh:mm:ss)."}}},"PwiAddress":{"type":"object","description":"Address information","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Address."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."}}},"PwiBasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key of the service provider. Not used in the standard business model; required only in marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not used in the standard business model; required only in marketplace model."}}},"PwiInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."},"token":{"type":"string","description":"Token generated for Pay with iyzico. Returned per request and required to retrieve the result."},"tokenExpireTime":{"type":"integer","description":"Token validity in seconds; 1800 seconds."},"payWithIyzicoPageUrl":{"type":"string","description":"Payment page URL to redirect to."},"signature":{"type":"string","description":"Response signature (hash)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure indicator."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/initialize_pay_with_iyzico.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/PayWithIyzicoSample.java#L15">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/PayWithIyzicoSample.cs#L13">.Net</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/0xu3ijm/1-pay-with-iyzico-initialize">Postman</a></td></tr></tbody></table>


# PWI-Retrieve

When the card details are entered in the payment form and the "Pay X TL" button is pressed, iyzico will redirect to the `callbackUrl` address that you specified during the creation of the payment form. At this address, a `token` value will be posted by iyzico. To view additional details about the payment results, a second query must be made using this `token`.

Following service represents the usage of token;

## Pay with iyzico (PWI) — Retrieve

> Queries the PWI transaction result by token.

```json
{"openapi":"3.0.3","info":{"title":"Pay with iyzico (PWI)","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/checkoutform/auth/ecom/detail":{"post":{"summary":"Pay with iyzico (PWI) — Retrieve","description":"Queries the PWI transaction result by token.","tags":["Pay with iyzico"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiRetrieveRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PwiPaymentResponse"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; starts with IYZWSv2 and is a signed hash in Base64.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"}}},"schemas":{"PwiRetrieveRequest":{"type":"object","required":["token"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"conversationId":{"type":"string","description":"Request/response correlation ID."},"token":{"type":"string","description":"Token of the PWI session to be retrieved."}}},"PwiPaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Outcome of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en).","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Total collected amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Fraud status of the payment.\n- 1: Approved\n- 0: In review\n- -1: Rejected\n","enum":[1,0,-1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission/deferral rate (informational). For example, if price=100 and paidPrice=110, the rate is 10%."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission/deferral amount (informational). For example, if price=100 and paidPrice=110, the amount is 10."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount for the payment."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","CardFinans"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last four digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment.","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","description":"Transaction items for basket lines.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Payment line ID; must be stored by the merchant (used for refund/capture/void and communication)."},"itemId":{"type":"string","description":"Item ID provided by the merchant."},"price":{"type":"decimal","description":"Amount of the basket item on the merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount distributed to this line; must be stored by the merchant."},"transactionStatus":{"type":"integer","description":"Line status:\n- 0: In fraud check\n- -1: Rejected after fraud check\n- 1: Approved (in marketplace: waiting for merchant approval)\n- 2: Approved (marketplace approved)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for this line (if applicable per agreement)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage resolution date (yyyy-MM-dd HH:mm:ss), e.g., 2015-10-19 14:36:52."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico fee at line level."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount at line level."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission/deferral rate at line level."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission/deferral amount at line level."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant after fees/commissions/blockages."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount distributed to this line; must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico fee at line level."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of blockage amount reflected to the merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid out to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after conversion."},"currency":{"type":"string","description":"Currency."}}}}}},"authCode":{"type":"string","description":"Auth code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"hostReference":{"type":"string","description":"Bank-provided host reference for the payment."},"signature":{"type":"string","description":"Signature value for verification."},"token":{"type":"string","description":"Token associated with the transaction (returned by the retrieval)."},"callbackUrl":{"type":"string","description":"Callback URL sent at initialization."},"paymentStatus":{"type":"string","description":"Payment status.","enum":["SUCCESS","FAILURE"]},"memberEmail":{"type":"string","description":"Email of the member who paid via PWI."},"memberGsmNumber":{"type":"string","description":"GSM number of the member who paid via PWI."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Success/failure indicator."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID of the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/retrieve_pay_with_iyzico_result.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/CheckoutFormSample.java#L118">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/PayWithIyzicoSample.cs#L107">.Net</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/usm3l8q/2-pay-with-iyzico-retrieve">Postman</a></td></tr></tbody></table>


# PWI Sample Imp.

Here at the page, we are going to look closer on [Implementation Steps](/en/payment-methods/paywithiyzico/pwi-implementation#implementation-steps) of [PWI](/en/payment-methods/paywithiyzico) comprehensively while providing sample requests, responses and best practices from fast, ease and secure implementation point of view.

### Pre-Requirements;

Before proceeding, please ensure that you have the following pre-requisites in place:

* [A sandbox account](/en/getting-started/preliminaries/sandbox)
* [Pair of API & Secret keys](broken://pages/19BoREI5VXROn8YuzMLc)
* A software tool to manage API calls; [Postman](/en/getting-started/preliminaries/postman-collections), Insonmina, Github clients

If so, keep going.

### Overview

Implementation requires two subsequent `POST` requests orchestrate one by one.

In short;

* First, we will illustrate a **PWI-Initialize** `POST` request.
* Then, we will cover up with **PWI-Retrieve** `POST` section.

### Adımlar

1. [PWI-Initialize](#step-1-pwi-initialize)
2. [Token + URL](#step-2-token--url)
3. [Redirection](#step-3-redirection)
4. [PWI-Retrieve](#step-4-pwi-retrieve)
5. [Webhook](#step-5-webhook)

### Step 1 - PWI Initialize

PWI implementation begins with [PWI-Initialize](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-initialize) `POST` request.

This step involves sending a POST request to initialize the PWI payment. The request body contains various parameters such as locale, conversationId, price, basketId, paymentGroup, callbackUrl, currency, paidPrice, enabledInstallments, buyer details, shipping address, billing address, and basket items.

The following object is a sample **PWI-Initialize** request body.

\
**Sample PWI-Initialize Request;**

{% code lineNumbers="true" %}

```json
{
    "locale": "en", //tr
    "conversationId": "conversationID",
    "price": "10.91",
    "basketId": "basketID",
    "paymentGroup": "OTHER",
    "callbackUrl": "YOUR_CALLBACKURL",
    "currency": "TRY",
    "paidPrice": "49.91",
    "enabledInstallments": [
        2,
        3,
        6,
        9,
        12
    ],
    "buyer": {
        "id": "buyerID",
        "name": "buyerName",
        "surname": "buyerSurname",
        "identityNumber": "11111111111",
        "email": "email@email.com",
        "gsmNumber": "+905350000000",
        "registrationAddress": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "city": "Istanbul",
        "country": "Turkey",
        "ip": "85.34.78.112"
    },
    "shippingAddress": {
        "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "contactName": "Contact Name",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "billingAddress": {
        "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "contactName": "Contact Name",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "basketItems": [
        {
            "id": "ItemID",
            "price": "10.91",
            "name": "product Name",
            "category1": "Category Name",
            "itemType": "PHYSICAL"
        }
    ]
}
```

{% endcode %}

Once you have triggered above request, there are 3(three) scenarios you will monitor mostly.\
Happy path includes a variable called, `payWithIyzicoPageUrl`.

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en", //tr
    "systemTime": 1619779710035,
    "conversationId": "123456789",
    "token": "a641ab63-0b7b-4a50-bb09-6c7325041acd",
    "tokenExpireTime": 1800,
    "payWithIyzicoPageUrl": "https://sandbox-consumer.iyzico.com/checkout?token=a641ab63-0b7b-4a50-bb09-6c7325041acd&lang=tr"
}
```

{% endcode %}

### Step 2 - Token + URL

Hereby, `token` and `payWithIyzicoPageUrl` are essential knots of for the rest of payment journey.&#x20;

In this step, you need to extract the token and payWithIyzicoPageUrl from the response obtained in the previous step. The token should be saved for later validation, and the payWithIyzicoPageUrl is used to redirect the user to the payment page.

* **token;** Its expected that merchants saves `token` parameter to confront and validate payment at the very end of payment journey.
* **payWithIyzicoPageUrl;** where payment page appears briefly. Redirection to `payWithIyzicoPageUrl` provides an interface to accomplish checkouts safely for end-users.

#### An example of payWithIyzicoPageUrl interface on the browser;

<div align="left"><figure><img src="/files/EiCLedERk1ZHi05NNOHe" alt=""><figcaption></figcaption></figure></div>

### Step 3 - Redirection

Redirection phase ties [PWI-Initialize](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-initialize) and [PWI-Retrieve](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-retrieve) steps overall.

Following up end user interact on PWI payment page, iyzico will automatically redirect the page to the address given in the "callbackUrl" parameter. Redirection `POST`  includes;

| Input Name                | Type   | Description                                                                                          |
| ------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| **status**                | String | Service response result (success / failure)                                                          |
| **iyziPaymentId**         | String | If verification is successful, iyzico will return a paymentid. It must be set in Auth request        |
| **merchantId**            | String | ID of your merchant identification.                                                                  |
| **paymentConversationId** | Long   | If set, conversation ID to match request and response                                                |
| **token**                 | String | Unique value created for each checkout form request. This token is used to access the payment result |
| **iyziReferenceCode**     | String | A unique reference code for the notification                                                         |
| **iyziEventType**         | String | Shows the request type. Exepcted value is CHECKOUT\_FORM\_AUTH                                       |

{% hint style="info" %}
`mdStatus` parameter will only appear on 3DS operations.

Please check further details around mdStatus [here](https://iyzico-new-documentation.gitbook.io/iyzico-dokuemantasyon/payment-methods/3ds/3ds-implementation#mdstatuses).
{% endhint %}

### Step 4 - PWI Retrieve

**PWI-Retrieve** is the last step of PWI chain.

Basically, we have just accepted a payment on the previous step.\
It is now time to legalize the transaction in this step.\
The following example is a sample **PWI-Retrieve** request body.

**Sample PWI-Retrieve Request;**

{% code lineNumbers="true" %}

```json
{
    "locale": "en", //tr
    "conversationId": "YOUR_CONVERSATION_ID",
    "token": "YOUR_TOKEN"
}
```

{% endcode %}

Once you have triggered above request, there are 2(two) scenarios you will monitor mostly.\
Happy path includes `SUCCESS` parameter in the `paymentStatus` variable.

**Sample PWI-Retrieve Response;**

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en", //tr
    "systemTime": 1,
    "conversationId": "YOUR_CONVERSATION_ID",
    "price": 1,
    "paidPrice": 1,
    "installment": 1,
    "paymentId": "GENERIC_PAYMENT_ID",
    "fraudStatus": 1,
    "merchantCommissionRate": 1,
    "merchantCommissionRateAmount": 1,
    "iyziCommissionRateAmount": 1,
    "iyziCommissionFee": 1,
    "binNumber": "000000",
    "lastFourDigits": "0000",
    "basketId": "basketID",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "ItemID",
            "paymentTransactionId": "GENERIC_PAYMENT_TRANSACTION_ID",
            "transactionStatus": 2,
            "price": 1,
            "paidPrice": 1,
            "merchantCommissionRate": 1,
            "merchantCommissionRateAmount": 1,
            "iyziCommissionRateAmount": 1,
            "iyziCommissionFee": 1,
            "blockageRate": 1,
            "blockageRateAmountMerchant": 1,
            "blockageRateAmountSubMerchant": 1,
            "blockageResolvedDate": "GENERIC_DATE",
            "subMerchantPrice": 1,
            "subMerchantPayoutRate": 1,
            "subMerchantPayoutAmount": 1,
            "merchantPayoutAmount": 1,
            "convertedPayout": {
                "paidPrice": 1,
                "iyziCommissionRateAmount": 1,
                "iyziCommissionFee": 1,
                "blockageRateAmountMerchant": 1,
                "blockageRateAmountSubMerchant": 1,
                "subMerchantPayoutAmount": 1,
                "merchantPayoutAmount": 1,
                "iyziConversionRate": 1,
                "iyziConversionRateAmount": 1,
                "currency": "TRY"
            }
        }
    ],
    "phase": "AUTH",
    "token": "YOUR_TOKEN",
    "callbackUrl": "YOUR_CALLBACK_URL",
    "paymentStatus": "SUCCESS"
}
```

{% endcode %}

### Step 5 - Webhook

Webhooks are tail subject of our implementation streamline.&#x20;

Receiving real-time payment notifications leverages overall PWI experience while ensuring that the notifications are coming from trusted sources, preventing any potential tampering or unauthorized access to sensitive data.&#x20;

Each payment event triggers webhooks;&#x20;

* In `15` seconds.&#x20;
* Until your server responds with `200`.
* For every `10` minutes.
* Max `3` times.

**Sample PWI Webhook**

| Parametere                | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| **iyziEventTime**         | long   | Unix timestamp value of first notification.                           |
| **iyziEventType**         | string | Shows the request type. Values: API\_AUTH, THREE\_DS\_AUTH, BKM\_AUTH |
| **iyziReferenceCode**     | string | A unique reference code for the notification                          |
| **paymentId**             | long   | Unique iyzico reference code of related payment                       |
| **paymentConversationId** | string | Merchant's reference id for the related payment                       |
| **status**                | string | Payment status. Values: SUCCESS, FAILURE                              |

Happy path includes `success` parameter in the `status` variable.

#### Confirmation

To finalize payment operations successfully, correlation of certain variables plays significant role;

* `paymentId`
* `status`
* `price`
* Other [Idempotency](file:///iyzico-dokuemantasyon/getting-started/preliminaries/idempotency) parameters optionally

&#x20;

[PWI-Retrieve](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-retrieve) response and [Webhook](file:///iyzico-dokuemantasyon/advanced/webhook) notification have to authenticate each other.

It is crucial to cross-verify the response received from [PWI-Retrieve](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-retrieve) and the data received in the [Webhook](/en/advanced/webhook) notification. Match the paymentId, status, price, and other relevant parameters to ensure the authenticity and correctness of the transaction.

* `paymentId` on [PWI-Retrieve](/en/payment-methods/paywithiyzico/pwi-implementation/pwi-retrieve) response should be equal to `paymentId`from Webhook
* Both of the `status` parameters should be `success`
* `price` parameter amounts should be the same
* And lastly, Idempotency parameters should be the same as well.

&#x20;

If so, congratulations! Just finished PWI implementation.

Transaction details could get from merchant panel.

{% hint style="info" %}
Please note that the provided sample requests and responses are for illustration purposes only, and you should adapt them to your specific implementation requirements and API documentation.
{% endhint %}


# PreAuth & Capture


# Non-3DS

NON-3DS is an invaluable resource for businesses looking to streamline their payment processes and maximize efficiency. By leveraging the NON-3DS functionality offered by iyzico, businesses can easily initiate and manage payment transactions with ease.

{% hint style="info" %}
**IMPORTANT NOTE :** To use NON-3DS, you must have this feature in your iyzico account. To enable this feature, you can create this request by sending an e-mail to <entegrasyon@iyzico.com>.
{% endhint %}

Incorporating NON-3DS into your software solution allows you to provide a seamless and user-friendly payment experience for your customers. With the abilities of NON-3DS, merchants can focus on growing their business while leaving the complexities of payment processing to a trusted and reliable platform.

### Which Products Can It be Used with?

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><a href="/pages/Pgl8HExhdPcF1FtoIlMT">/pages/Pgl8HExhdPcF1FtoIlMT</a></td><td></td><td></td></tr><tr><td><a href="/pages/IZR5VcY1BoQ3zPDVajzZ">/pages/IZR5VcY1BoQ3zPDVajzZ</a></td><td></td><td></td></tr><tr><td><a href="/pages/x32YqNIzXEIggyJzagrU">/pages/x32YqNIzXEIggyJzagrU</a></td><td></td><td></td></tr><tr><td><a href="/pages/91l0cOFxOgw6BTmbFtvA">/pages/91l0cOFxOgw6BTmbFtvA</a></td><td></td><td></td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td></td><td></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td></td><td></td></tr></tbody></table>

### Advantages

* Faster integration
* Simplest form of managing payments
* Easy to plug\&play among other iyzico APIs


# Non-3DS Implementation

<figure><img src="/files/ZNyiaUx5k6gOBKfFquos" alt=""><figcaption></figcaption></figure>

### **Integration Steps** <a href="#integration-steps" id="integration-steps"></a>

1. BIN Check
2. Create PreAuth Payment
3. Create PostAuth Payment
4. [Webhook](https://docs.iyzico.com/v/en/advanced/webhook)

### Top View <a href="#top-view" id="top-view"></a>

* BIN Check; section of identifying issuer details where API returns information about installment options and card details.
* Create PreAuth Payment; essential requirement on managing payment request at two-step flow transactions.
* Create PostAuth Payment; engage step to finalize payment recorded by iyzico.
* Webhook; real-time notification of relevant payment.

### Sample Implementation <a href="#sample-implementation" id="sample-implementation"></a>

PreAuth NON-3DS implementation consists of 2 subsequent `POST` requests in short.

* Create PreAuth Payment
* Create PostAuth Payment

Suggested integration tracks following order;

### 1. BIN Check <a href="#id-1.-bin-check" id="id-1.-bin-check"></a>

Whether 3DS or NON-3DS payment method, It is advised to identify issuer card feature beforehand. BIN detail services provides further details of card type, card scheme, card association which indicates installment and 3DS features.

**Sample Installment Request;**

```javascript
{
"price":"100.0",
"binNumber":"535805"
}
```

**Sample Retrieve Installment Response;**

```javascript
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685905139724,
    "installmentDetails": [
        {
            "binNumber": "535805",
            "price": 100.0,
            "cardType": "DEBIT_CARD",
            "cardAssociation": "MASTER_CARD",
            "cardFamilyName": "iyzico DC",
            "force3ds": 0,
            "bankCode": 864,
            "bankName": "iyzico",
            "forceCvc": 0,
            "commercial": 0,
            "dccEnabled": 0,
            "installmentPrices": [
                {
                    "installmentPrice": 100.0,
                    "totalPrice": 100.0,
                    "installmentNumber": 1
                }
            ]
        }
    ]
}
```

### 2. Create PreAuth Payment <a href="#id-2.-create-payment" id="id-2.-create-payment"></a>

NON-3DS payment journey begins with Create PreAuth Payment `POST` request.

**Sample Create PreAuth Payment Request;**

```javascript
{
   "locale":"en",
   "conversationId":"deviyzico",
   "price":"1.0",
   "paidPrice":"1.2",
   "currency":"TRY",
   "installment":1,
   "paymentChannel":"WEB",
   "basketId":"B67832",
   "paymentGroup":"LISTING",
   "paymentCard":{
      "cardHolderName":"Mehmet Test",
      "cardNumber":"5528790000000008",
      "expireYear":"2030",
      "expireMonth":"12",
      "cvc":"123",
      "registerCard":0
   },
   "buyer":{
      "id":"BY789",
      "name":"John",
      "surname":"Doe",
      "identityNumber":"74300864791",
      "email":"email@email.com",
      "gsmNumber":"+905350000000",
      "registrationDate":"2013-04-21 15:12:09",
      "lastLoginDate":"2015-10-05 12:43:35",
      "registrationAddress":"Altunizade, İnci Çk. No:3 Kat: 3 D: 10, 34662 Üsküdar/İstanbul",
      "city":"Istanbul",
      "country":"Turkey",
      "zipCode":"34732",
      "ip":"85.34.78.112"
   },
   "shippingAddress":{
      "address":"Altunizade, İnci Çk. No:3 Kat: 3 D: 10, 34662 Üsküdar/İstanbul",
      "zipCode":"34742",
      "contactName":"Mehmet Test",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "billingAddress":{
      "address":"Altunizade, İnci Çk. No:3 Kat: 3 D: 10, 34662 Üsküdar/İstanbul",
      "zipCode":"34742",
      "contactName":"Mehmet Test",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "basketItems":[
      {
         "id":"BI101",
         "price":"0.3",
         "name":"Binocular",
         "category1":"Collectibles",
         "category2":"Accessories",
         "itemType":"PHYSICAL"
      },
      {
         "id":"BI102",
         "price":"0.5",
         "name":"Game code",
         "category1":"Game",
         "category2":"Online Game Items",
         "itemType":"VIRTUAL"
      },
      {
         "id":"BI103",
         "price":"0.2",
         "name":"Usb",
         "category1":"Electronics",
         "category2":"Usb / Cable",
         "itemType":"PHYSICAL"
      }
   ]
}
```

**Sample Create PreAuth Payment Response;**

```javascript
{
    "status": "success",
    "locale": "en",
    "systemTime": 1714818438785,
    "conversationId": "deviyzico",
    "price": 1.0,
    "paidPrice": 1.2,
    "installment": 1,
    "paymentId": "22145064",
    "fraudStatus": 1,
    "merchantCommissionRate": 20.00000000,
    "merchantCommissionRateAmount": 0.2,
    "iyziCommissionRateAmount": 0.04800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Paraf",
    "binNumber": "552879",
    "lastFourDigits": "0008",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "24080880",
            "transactionStatus": 2,
            "price": 0.3,
            "paidPrice": 0.36000000,
            "merchantCommissionRate": 20.00000000,
            "merchantCommissionRateAmount": 0.06000000,
            "iyziCommissionRateAmount": 0.01440000,
            "iyziCommissionFee": 0.07500000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2024-05-12 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.27060000,
            "convertedPayout": {
                "paidPrice": 0.36000000,
                "iyziCommissionRateAmount": 0.01440000,
                "iyziCommissionFee": 0.07500000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.27060000,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI102",
            "paymentTransactionId": "24080881",
            "transactionStatus": 2,
            "price": 0.5,
            "paidPrice": 0.60000000,
            "merchantCommissionRate": 20.00000000,
            "merchantCommissionRateAmount": 0.10000000,
            "iyziCommissionRateAmount": 0.02400000,
            "iyziCommissionFee": 0.12500000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2024-05-12 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.45100000,
            "convertedPayout": {
                "paidPrice": 0.60000000,
                "iyziCommissionRateAmount": 0.02400000,
                "iyziCommissionFee": 0.12500000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.45100000,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI103",
            "paymentTransactionId": "24080882",
            "transactionStatus": 2,
            "price": 0.2,
            "paidPrice": 0.24000000,
            "merchantCommissionRate": 20.00000000,
            "merchantCommissionRateAmount": 0.04000000,
            "iyziCommissionRateAmount": 0.00960000,
            "iyziCommissionFee": 0.05000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2024-05-12 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.18040000,
            "convertedPayout": {
                "paidPrice": 0.24000000,
                "iyziCommissionRateAmount": 0.00960000,
                "iyziCommissionFee": 0.05000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.18040000,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "757812",
    "phase": "PRE_AUTH",
    "hostReference": "mock00001iyzihostrfn"
}
```

### 3. Create PostAuth Payment <a href="#id-3.-retrieve-optional" id="id-3.-retrieve-optional"></a>

After having completing all the steps above, Its now time to finalize payment operation between Issuer and Acquirer with PostAuth Payment request.

**Sample PostAuth Payment Request;**

```javascript
{
  "locale": "en",
  "paymentId":"22145064"
}
```

**Sample Retrieve Response;**

```javascript
{
    "status": "success",
    "locale": "en",
    "systemTime": 1714818557440,
    "price": 1.00000000,
    "paidPrice": 1.20000000,
    "installment": 1,
    "paymentId": "22145064",
    "fraudStatus": 1,
    "merchantCommissionRate": 20.00000000,
    "merchantCommissionRateAmount": 0.20000000,
    "iyziCommissionRateAmount": 0.04800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Paraf",
    "binNumber": "552879",
    "lastFourDigits": "0008",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "24080880",
            "transactionStatus": 2,
            "price": 0.30000000,
            "paidPrice": 0.36000000,
            "merchantCommissionRate": 20.00000000,
            "merchantCommissionRateAmount": 0.06000000,
            "iyziCommissionRateAmount": 0.01440000,
            "iyziCommissionFee": 0.07500000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2024-05-12 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 0.27060000,
            "convertedPayout": {
                "paidPrice": 0.36000000,
                "iyziCommissionRateAmount": 0.01440000,
                "iyziCommissionFee": 0.07500000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.27060000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI102",
            "paymentTransactionId": "24080881",
            "transactionStatus": 2,
            "price": 0.50000000,
            "paidPrice": 0.60000000,
            "merchantCommissionRate": 20.00000000,
            "merchantCommissionRateAmount": 0.10000000,
            "iyziCommissionRateAmount": 0.02400000,
            "iyziCommissionFee": 0.12500000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2024-05-12 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 0.45100000,
            "convertedPayout": {
                "paidPrice": 0.60000000,
                "iyziCommissionRateAmount": 0.02400000,
                "iyziCommissionFee": 0.12500000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.45100000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI103",
            "paymentTransactionId": "24080882",
            "transactionStatus": 2,
            "price": 0.20000000,
            "paidPrice": 0.24000000,
            "merchantCommissionRate": 20.00000000,
            "merchantCommissionRateAmount": 0.04000000,
            "iyziCommissionRateAmount": 0.00960000,
            "iyziCommissionFee": 0.05000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2024-05-12 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 0.18040000,
            "convertedPayout": {
                "paidPrice": 0.24000000,
                "iyziCommissionRateAmount": 0.00960000,
                "iyziCommissionFee": 0.05000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.18040000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "510911",
    "phase": "POST_AUTH",
    "hostReference": "mock00001iyzihostrfn"
}
```

### 4.Webhook <a href="#id-4.webhook" id="id-4.webhook"></a>

Webhooks are tail subject of our implementation streamline.

Receiving real-time payment notifications leverages overall 3DS experience while ensuring that the notifications are coming from trusted sources, preventing any potential tampering or unauthorized access to sensitive data.

Each payment event triggers webhooks;

* In `15` seconds.
* Until your server responds with `200`.
* For every `10` minutes.
* Max `3` times.

**Sample PreAuth & Capture Non-3DS Webhook**

| Parametere                | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| **iyziEventTime**         | long   | Unix timestamp value of first notification.                           |
| **iyziEventType**         | string | Shows the request type. Values: API\_AUTH, THREE\_DS\_AUTH, BKM\_AUTH |
| **iyziReferenceCode**     | string | A unique reference code for the notification                          |
| **paymentId**             | long   | Unique iyzico reference code of related payment                       |
| **paymentConversationId** | string | Merchant's reference id for the related payment                       |
| **status**                | string | Payment status. Values: SUCCESS, FAILURE                              |

Happy path includes `success` parameter in the `status` variable.

**Confirmation**

To finalize payment operations successfully, correlation of certain variables plays significant role;

* `paymentId`
* `status`
* `price`
* Other [Idempotency](file:///iyzico-dokuemantasyon/getting-started/preliminaries/idempotency) parameters optionally

Its vital that Create PostAuth Payment response and [Webhook](file:///iyzico-dokuemantasyon/advanced/webhook) notification have to authenticate each other.

* `paymentId` on Create PostAuth Payment response should be equal to `paymentId`from [Webhook](https://docs.iyzico.com/v/en/advanced/webhook)
* Both of the `status` parameters should be `success`
* `price` parameter amounts should be the same
* And lastly, [Idempotency](https://docs.iyzico.com/v/en/getting-started/preliminaries/idempotency) parameters should be the same as well.

If so, congratulations! Just finished PreAuth & Capture NON-3DS implementation.

Transaction details could get from merchant panel.


# Create PreAuth Payment

Create PreAuth Payment API is responsible for processing the customer's card payments. When this service is used, iyzico provides an instant response regarding the success of the transaction.

* It supports transactions made with TROY, MASTERCARD, VISA, and AMEX branded cards.&#x20;
* For cards participating in installment programs such as BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, and ADVANTAGE, we strictly do not advice options for any installments.
* Successful transactions are displayed in green, while failed transactions are displayed in red on the panel.&#x20;
* The merchant can utilize the conversationId and basketId parameters as order numbers on their side.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

## Create PreAuth Payment Request

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/payment/preauth`

#### Request Body

| Name                                                           | Type    | Description                                                                                                                              |
| -------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| price<mark style="color:red;">\*</mark>                        | Decimal | Total amount of basket. The sum of basket items’ amount must be equal to the price of basket                                             |
| contactName(BillingAddress)<mark style="color:red;">\*</mark>  | String  | Contact name of billing address                                                                                                          |
| registrationAddress(Buyer)<mark style="color:red;">\*</mark>   | String  | Registration address of buyer                                                                                                            |
| ip(Buyer)<mark style="color:red;">\*</mark>                    | String  | IP of buyer                                                                                                                              |
| email(Buyer)<mark style="color:red;">\*</mark>                 | String  | Email of buyer                                                                                                                           |
| country(Buyer)<mark style="color:red;">\*</mark>               | String  | Country of buyer                                                                                                                         |
| city(Buyer)<mark style="color:red;">\*</mark>                  | String  | City of buyer                                                                                                                            |
| identityNumber(Buyer)<mark style="color:red;">\*</mark>        | String  | Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants                                              |
| surname(Buyer)<mark style="color:red;">\*</mark>               | String  | Surname of buyer                                                                                                                         |
| name(Buyer)<mark style="color:red;">\*</mark>                  | String  | Name of buyer                                                                                                                            |
| id(Buyer)<mark style="color:red;">\*</mark>                    | String  | ID of buyer.                                                                                                                             |
| cardHolderName<mark style="color:red;">\*</mark>               | String  | Name of the card owner                                                                                                                   |
| cvc<mark style="color:red;">\*</mark>                          | String  | 4 (AMEX) or 3 (VISA, MC, TROY) digits card verification code                                                                             |
| expireMonth<mark style="color:red;">\*</mark>                  | String  | Expiration month of the card (2 digits)                                                                                                  |
| expireYear<mark style="color:red;">\*</mark>                   | String  | Expiration year of the card                                                                                                              |
| cardNumber<mark style="color:red;">\*</mark>                   | String  | 15 (AMEX) or 16 (VISA, MC) digits card number                                                                                            |
| installment<mark style="color:red;">\*</mark>                  | Integer | Installment value. For single installment payments it should be 1 (valid values: 1, 2, 3, 6, 9, 12)                                      |
| currency<mark style="color:red;">\*</mark>                     | String  | Currency (default: TRY). Alternatively, you can set USD, EUR, GBP and IRR                                                                |
| paidPrice<mark style="color:red;">\*</mark>                    | Decimal | Final amount (including installment fee) that will be charged to customer’s card                                                         |
| zipCode(BillingAddress)                                        | String  | Zip code of billing address                                                                                                              |
| zipCode(ShippingAddress)                                       | String  | Zip code of shipping address                                                                                                             |
| zipCode(Buyer)                                                 | String  | Zip code of buyer                                                                                                                        |
| category1(BasketItems)                                         | String  | Category 1 for item in the basket                                                                                                        |
| name(BasketItems)                                              | String  | Name of the item in the basket                                                                                                           |
| price(BasketItems)                                             | Decimal | Price value for each item. Must be greater than zero                                                                                     |
| itemType(BasketItems)                                          | String  | Item Type. Valid values are PHYSICAL,VIRTUAL                                                                                             |
| id(BasketItems)                                                | String  | Basket Item ID                                                                                                                           |
| address(ShippingAddress)<mark style="color:red;">\*</mark>     | String  | Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory                 |
| country(ShippingAddress)<mark style="color:red;">\*</mark>     | String  | Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory                    |
| city(ShippingAddress)<mark style="color:red;">\*</mark>        | String  | City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory                       |
| contactName(ShippingAddress)<mark style="color:red;">\*</mark> | String  | Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory                    |
| address(BillingAddress)<mark style="color:red;">\*</mark>      | String  | Address details of billing address                                                                                                       |
| country(BillingAddress)<mark style="color:red;">\*</mark>      | String  | Country name of billing address                                                                                                          |
| city(BillingAddress)<mark style="color:red;">\*</mark>         | String  | City name of billing address                                                                                                             |
| paymentGroup                                                   | String  | Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION                                                        |
| paymentChannel                                                 | String  | Payment channel. Valid values are WEB, MOBILE, MOBILE\_WEB, MOBILE\_IOS, MOBILE\_ANDROID, MOBILE\_WINDOWS, MOBILE\_TABLET, MOBILE\_PHONE |
| basketId                                                       | String  | Merchant's basket ID                                                                                                                     |
| conversationId                                                 | String  | Conversation ID to match request and response                                                                                            |
| locale                                                         | String  | Language (default: tr)                                                                                                                   |
| lastLoginDate(Buyer)                                           | String  | Last login date of buyer. Format should be “2015-09-17 23:45:06”                                                                         |
| registrationDate(Buyer)                                        | String  | Registration date of buyer. Format should be “2015-09-17 23:45:06”                                                                       |
| cardAlias                                                      | Integer | If registerCard value is 1 cardAlias can send within request.                                                                            |
| registerCard                                                   | Integer | Parameter that shows card details will store or not. Default value is 0 and valid values are 0 or 1                                      |
| subMerchantKey(BasketItem)                                     | String  | Submerchant ID value. Mandatory value for marketplace solution                                                                           |
| subMerchantPrice(BasketItem)                                   | Decimal | Payout amount to subMerchant of each item. Must be greater than zero. Mandatory value for marketplace solution                           |
| gsmNumber(Buyer)                                               | String  | GSM number of buyer                                                                                                                      |
| category2(BasketItems)                                         | String  | Category 2 for item in the basket                                                                                                        |
| paymentSource                                                  | String  | Payment source. Valid values are SHOPIFY, MAGENTO, PRESTASHOP, WOOCOMMERCE, OPENCART                                                     |

#### **Create PreAuth Payment Response**

| **status**                                                        | String  | Service response result (success / failure)                                                                                                                                                                        |
| ----------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **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                                                                                                                                                                  |
| **locale**                                                        | String  | Language (default: tr)                                                                                                                                                                                             |
| **systemTime**                                                    | Long    | Response system timestamp value                                                                                                                                                                                    |
| **conversationId**                                                | String  | If set, conversation ID to match request and response                                                                                                                                                              |
| **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. The sum of basket items’ amount must be equal to the price 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                                                                                |
| **currency**                                                      | String  | Currency of request                                                                                                                                                                                                |
| **installment**                                                   | Integer | Installment number of payment, for single payments it returns 1. Valid values are 1, 2, 3, 6, 9, 12                                                                                                                |
| **basketId**                                                      | String  | Merchant's basket ID                                                                                                                                                                                               |
| **binNumber**                                                     | String  | First 6 digit of card                                                                                                                                                                                              |
| **cardAssociation**                                               | String  | Valid values are VISA, MASTER\_CARD, AMERICAN\_EXPRESS, TROY                                                                                                                                                       |
| **cardFamily**                                                    | String  | Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage                                                                                                                                        |
| **cardType**                                                      | String  | Valid values are CREDIT\_CARD, DEBIT\_CARD, PREPAID\_CARD                                                                                                                                                          |
| **fraudStatus**                                                   | Integer | Fraud risk status for payment request (0 for review / 1 for accept)                                                                                                                                                |
| **iyziCommissionFee**                                             | Decimal | iyzico commission fee for payment transaction                                                                                                                                                                      |
| **iyziCommissionRateAmount**                                      | Decimal | iyzico commission rate amount for payment transaction                                                                                                                                                              |
| **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)                                                                                                        |
| **paymentTransactionId (ItemTransactions)**                       | String  | ID of basket item. Merchants should keep payment ID in their system (this ID will be used for cancel requests)                                                                                                     |
| **itemId(ItemTransactions)**                                      | String  | Item ID of each item in basket                                                                                                                                                                                     |
| **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                                                                                                                      |
| **transactionStatus (ItemTransactions)**                          | Integer | Status of a payment transaction. (0 for waiting / -1 for rejected by fraud / 1 for waiting for approval / 2 for approved                                                                                           |
| **blockageRate(ItemTransactions)**                                | Decimal | Blockage rate based on each item.                                                                                                                                                                                  |
| **blockageRateAmountMerchant(ItemTransactions)**                  | Decimal | Blockage rate amount for merchant based on each item                                                                                                                                                               |
| **blockageResolvedDate(ItemTransactions)**                        | String  | Blockage resolve date based on each item. Date format should be “2015-10-19 14:36:52”                                                                                                                              |
| **iyziCommissionFee(ItemTransactions)**                           | Decimal | iyzico commission fee based on each item                                                                                                                                                                           |
| **iyziCommissionRateAmount(ItemTransactions)**                    | Decimal | iyzico commission rate amount based on each item                                                                                                                                                                   |
| **merchantCommissionRate(ItemTransactions)**                      | Decimal | Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)                                                                                                                      |
| **merchantCommissionRateAmount(ItemTransactions)**                | Decimal | Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)                                                                                                        |
| **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(ItemTransactions)(convertedPayout)**                  | Decimal | Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.                                                                                                              |
| **iyziCommissionFee(ItemTransactions)(convertedPayout)**          | Decimal | Converted iyzico commission fee based on each item                                                                                                                                                                 |
| **iyziCommissionRateAmount(ItemTransactions)(convertedPayout)**   | Decimal | Converted iyzico commission rate amount based on each item                                                                                                                                                         |
| **blockageRateAmountMerchant(ItemTransactions)(convertedPayout)** | Decimal | Converted blockage rate amount for merchant based on each item                                                                                                                                                     |
| **merchantPayoutAmount(ItemTransactions)(convertedPayout)**       | Decimal | Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions) |
| **iyziConversationRate(ItemTransactions)(convertedPayout)**       | Decimal | iyzico conversation rate                                                                                                                                                                                           |
| **iyziConversationRateAmount(ItemTransactions)(convertedPayout)** | Decimal | iyzico conversation rate amount                                                                                                                                                                                    |
| **currency(ItemTransactions)(convertedPayout)**                   | String  | Currency for payout conversion                                                                                                                                                                                     |

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers.

* The `status` parameter provides information about the status of the transaction. `success` indicates that the transaction has been successfully completed and the payment has been processed. `failure` indicates that the transaction has failed, and an error message related to the failure reason is provided.
* The `paymentStatus` parameter is null for this service.
* The `paymentId` and `paymentTransactionId` values should be stored for future reference and tracking.
* In the event of a failed transaction (`failure` status), the `errorCode`, `errorMessage`, and `errorGroup` parameters will be returned with corresponding values, providing details about the error.


# Create PostAuth Payment

Create PostAuth Payment API is responsible for finalizing card payments. When this service is used, iyzico provides an instant response regarding the success of the transaction.

## Create PostAuth Payment Request

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/payment/postauth`

#### Request Body

| Name                                        | Type    | Description                                                                                                    |
| ------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| locale                                      | String  | Language (default: tr)                                                                                         |
| conversationId                              | String  | Conversation ID to match request and response                                                                  |
| paymentId<mark style="color:red;">\*</mark> | Decimal | ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests) |
| currency<mark style="color:red;">\*</mark>  | String  | Currency (default: TRY). Alternatively, you can set USD, EUR, GBP and IRR                                      |
| ip(Buyer)<mark style="color:red;">\*</mark> | String  | IP of buyer                                                                                                    |

#### **Create PostAuth Payment Response**

| **status**                                                        | String  | Service response result (success / failure)                                                                                                                                                                        |
| ----------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **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                                                                                                                                                                  |
| **locale**                                                        | String  | Language (default: tr)                                                                                                                                                                                             |
| **systemTime**                                                    | Long    | Response system timestamp value                                                                                                                                                                                    |
| **conversationId**                                                | String  | If set, conversation ID to match request and response                                                                                                                                                              |
| **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. The sum of basket items’ amount must be equal to the price 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                                                                                |
| **currency**                                                      | String  | Currency of request                                                                                                                                                                                                |
| **installment**                                                   | Integer | Installment number of payment, for single payments it returns 1. Valid values are 1, 2, 3, 6, 9, 12                                                                                                                |
| **basketId**                                                      | String  | Merchant's basket ID                                                                                                                                                                                               |
| **binNumber**                                                     | String  | First 6 digit of card                                                                                                                                                                                              |
| **cardAssociation**                                               | String  | Valid values are VISA, MASTER\_CARD, AMERICAN\_EXPRESS, TROY                                                                                                                                                       |
| **cardFamily**                                                    | String  | Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage                                                                                                                                        |
| **cardType**                                                      | String  | Valid values are CREDIT\_CARD, DEBIT\_CARD, PREPAID\_CARD                                                                                                                                                          |
| **fraudStatus**                                                   | Integer | Fraud risk status for payment request (0 for review / 1 for accept)                                                                                                                                                |
| **iyziCommissionFee**                                             | Decimal | iyzico commission fee for payment transaction                                                                                                                                                                      |
| **iyziCommissionRateAmount**                                      | Decimal | iyzico commission rate amount for payment transaction                                                                                                                                                              |
| **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)                                                                                                        |
| **paymentTransactionId (ItemTransactions)**                       | String  | ID of basket item. Merchants should keep payment ID in their system (this ID will be used for cancel requests)                                                                                                     |
| **itemId(ItemTransactions)**                                      | String  | Item ID of each item in basket                                                                                                                                                                                     |
| **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                                                                                                                      |
| **transactionStatus (ItemTransactions)**                          | Integer | Status of a payment transaction. (0 for waiting / -1 for rejected by fraud / 1 for waiting for approval / 2 for approved                                                                                           |
| **blockageRate(ItemTransactions)**                                | Decimal | Blockage rate based on each item.                                                                                                                                                                                  |
| **blockageRateAmountMerchant(ItemTransactions)**                  | Decimal | Blockage rate amount for merchant based on each item                                                                                                                                                               |
| **blockageResolvedDate(ItemTransactions)**                        | String  | Blockage resolve date based on each item. Date format should be “2015-10-19 14:36:52”                                                                                                                              |
| **iyziCommissionFee(ItemTransactions)**                           | Decimal | iyzico commission fee based on each item                                                                                                                                                                           |
| **iyziCommissionRateAmount(ItemTransactions)**                    | Decimal | iyzico commission rate amount based on each item                                                                                                                                                                   |
| **merchantCommissionRate(ItemTransactions)**                      | Decimal | Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)                                                                                                                      |
| **merchantCommissionRateAmount(ItemTransactions)**                | Decimal | Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)                                                                                                        |
| **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(ItemTransactions)(convertedPayout)**                  | Decimal | Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.                                                                                                              |
| **iyziCommissionFee(ItemTransactions)(convertedPayout)**          | Decimal | Converted iyzico commission fee based on each item                                                                                                                                                                 |
| **iyziCommissionRateAmount(ItemTransactions)(convertedPayout)**   | Decimal | Converted iyzico commission rate amount based on each item                                                                                                                                                         |
| **blockageRateAmountMerchant(ItemTransactions)(convertedPayout)** | Decimal | Converted blockage rate amount for merchant based on each item                                                                                                                                                     |
| **merchantPayoutAmount(ItemTransactions)(convertedPayout)**       | Decimal | Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions) |
| **iyziConversationRate(ItemTransactions)(convertedPayout)**       | Decimal | iyzico conversation rate                                                                                                                                                                                           |
| **iyziConversationRateAmount(ItemTransactions)(convertedPayout)** | Decimal | iyzico conversation rate amount                                                                                                                                                                                    |
| **currency(ItemTransactions)(convertedPayout)**                   | String  | Currency for payout conversion                                                                                                                                                                                     |

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers.

* The `status` parameter provides information about the status of the transaction. `success` indicates that the transaction has been successfully completed and the payment has been processed. `failure` indicates that the transaction has failed, and an error message related to the failure reason is provided.
* The `paymentStatus` parameter is null for this service.
* The `paymentId` and `paymentTransactionId` values should be stored for future reference and tracking.
* In the event of a failed transaction (`failure` status), the `errorCode`, `errorMessage`, and `errorGroup` parameters will be returned with corresponding values, providing details about the error.


# Tokenization

Tokenization is a technology that allows for the secure storage of payment information and enables payment transactions to be completed without the need to re-enter card details.

Thanks to this method, payment details from a user's most recent transaction using the *Pay with iyzico* option are tokenized by iyzico in accordance with PCI DSS standards and a session is generated. This token can then be used in future transactions without requiring the user to re-enter their card information.

{% hint style="info" %}
**IMPORTANT NOTE:** To enable this payment method, please contact your account manager or submit your request via your registered email address to <entegrasyon@iyzico.com>.
{% endhint %}

### Advantages <a href="#avantajlar" id="avantajlar"></a>

<div align="left"><figure><img src="/files/SLIv5ohc6w0izdZvoo3E" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/JNHjS4Y5qK1HKQR3B2e6" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="/files/qjb1S88UovNwNWHnLRXe" alt="" width="188"><figcaption></figcaption></figure></div>

### Suitable Business Models

* Platforms that support recurring payments
* E-commerce companies seeking to provide a fast and seamless checkout experience
* Brands aiming to offer one-click payments through their mobile apps
* Businesses looking to increase customer loyalty and conversion rates

### Which Products Can It be Used with? <a href="#which-products-can-it-be-used-with" id="which-products-can-it-be-used-with"></a>

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="/pages/zcvI9t5xOcaPD19K4CPF">Pay with iyzico</a></td></tr></tbody></table>

You can visit the tokenization Integration page for detailed integration information.


# Tokenization Integration

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

[**Pay with iyzico**](/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)](/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](/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**](/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**](/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**](/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](/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. İ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

```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. İ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

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


# Pay With iyzico

The Pay With iyzico method allows you to complete the transaction by directing the end user to the iyzico wallet account offered by iyzico.

This method is ideal for partners who want to integrate quickly and leave the UI to iyzico. This service should be used for API-API Pay With iyzico.

## Initialize Pay with iyzico

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/pwi/init`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |

### **Request** Parameters

<table><thead><tr><th width="219.78515625">Parametre</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Yes</td><td>Final amount (including installment fee) that will be charged to customer’s card</td></tr><tr><td><code>locale</code></td><td>String</td><td>No</td><td>Language (default: tr)</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Yes</td><td>Total amount of basket. The sum of basket items’ amount must be equal to the price of basket.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>No</td><td>Conversation ID to match request and response</td></tr><tr><td><code>paymentGroup</code></td><td>String</td><td>Yes</td><td>Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>Yes</td><td>Merchant callback URL for payment result notification.<br>callBackUrl address should have SSL.</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>Currency (default: TRY). Alternatively, you can set USD, EUR, GBP </td></tr><tr><td><code>basketId</code></td><td>String</td><td>No</td><td>Merchant's basket ID</td></tr><tr><td><code>buyerId</code></td><td>String</td><td>Yes</td><td>ID of buyer.</td></tr><tr><td><code>buyerName</code></td><td>String</td><td>Yes</td><td>Name of buyer</td></tr><tr><td><code>buyerSurname</code></td><td>String</td><td>Yes</td><td>Surname of buyer</td></tr><tr><td><code>identityNumber</code></td><td>String</td><td>Yes</td><td>Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants</td></tr><tr><td><code>email</code></td><td>String</td><td>Yes</td><td>Email of buyer</td></tr><tr><td><code>gsmNumber</code></td><td>String</td><td>No</td><td>GSM number of buyer</td></tr><tr><td><code>registrationAddress</code></td><td>String</td><td>Yes</td><td>Registration address of buyer</td></tr><tr><td><code>city</code></td><td>String</td><td>Yes</td><td>City of buyer</td></tr><tr><td><code>country</code></td><td>String</td><td>Yes</td><td>Country of buyer</td></tr><tr><td><code>IP</code></td><td>String</td><td>No</td><td>IP of buyer</td></tr><tr><td><code>zipCode</code></td><td>String</td><td>Yes</td><td>Zip code of buyer</td></tr><tr><td><code>address(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory</td></tr><tr><td><code>contactName(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>city(shippingAddress)</code></td><td>String</td><td>Yes</td><td>City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>country(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>zipCode(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Zip code of shipping address.</td></tr><tr><td><code>address(billingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of billing address.</td></tr><tr><td><code>contactName(billingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of billing address.</td></tr><tr><td><code>city(billingAddress)</code></td><td>String</td><td>Yes</td><td>City name of billing address.</td></tr><tr><td><code>country(billingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of billing address.</td></tr><tr><td><code>basketItemId</code></td><td>String</td><td>Yes</td><td><p>Basket Item ID.</p><p>It can take a maximum of 500 characters.</p></td></tr><tr><td><code>basketItemPrice</code></td><td>String</td><td>Yes</td><td>Price value for each item. Must be greater than zero.</td></tr><tr><td><code>basketItemName</code></td><td>String</td><td>Yes</td><td>Name of the item in the basket.</td></tr><tr><td><code>basketItemCategory1</code></td><td>String</td><td>Yes</td><td>Category 1 for item in the basket.</td></tr><tr><td><code>basketItemCategory2</code></td><td>String</td><td>No</td><td>Category 2 for item in the basket.</td></tr><tr><td><code>basketItemItemType</code></td><td>String</td><td>Yes</td><td>Item Type. Valid values are PHYSICAL,VIRTUAL</td></tr></tbody></table>

### INIT PWI Request

```json
{
    "paidPrice": 1.0,
    "locale": "en",
    "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. İ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**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="403" %}

```json
{
    "status": "failure",
    "errorCode": "5062",
    "errorMessage": "Total item price must be equal to price",
    "locale": "en",
    "systemTime": 1750240390554,
    "conversationId": "deviyzico"
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

<table><thead><tr><th>Parameter </th><th valign="middle">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td valign="middle">String</td><td>Service response result. (success / failure)</td></tr><tr><td><code>locale</code></td><td valign="middle">String</td><td>Language (default: tr).</td></tr><tr><td><code>systemTime</code></td><td valign="middle">Long</td><td>Response system unix timestamp value.</td></tr><tr><td><code>conversationId</code></td><td valign="middle">String</td><td>If set, conversation ID to match request and response.</td></tr><tr><td><code>token</code></td><td valign="middle">String</td><td>Unique value created for each pay with iyzico request. This token is also used to access the payment result.</td></tr><tr><td><code>payWithIyzicoPageUrl</code></td><td valign="middle">String</td><td>Unique link of pay with iyzico page. The end user should be directed to this page.</td></tr><tr><td><code>tokenExpireTime</code></td><td valign="middle">Long</td><td>Expiration time of the token and pay with iyzico page.</td></tr><tr><td><code>tokenExpireDate</code></td><td valign="middle">Long</td><td>The date when the token will expire in the Epoch timeframe.</td></tr><tr><td><code>errorCode</code></td><td valign="middle">String</td><td>Error code if service response status is failure.</td></tr><tr><td><code>errorMessage</code></td><td valign="middle">String</td><td>If the operation is erroneous, this is a message detailing the error, with language support according to the locale parameter.</td></tr></tbody></table>


# Retrieve Payment Detail and Session Info

Returns the details of the payments made by the Member within the scope of the session. The payment that starts the session with Pay with iyzico (PWI) is within this scope.

### Payment and Session Retrieve

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/retrieve/payment`

#### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |

### **Request Parameters**

<table><thead><tr><th width="190.3515625">Paremeter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>checkoutFormToken</code></td><td>string</td><td>Evet</td><td>The token value of the transaction.</td></tr><tr><td><code>locale</code></td><td>string</td><td>Hayır</td><td>The language value sent for the request. Can take the value EN and TR.</td></tr><tr><td><code>conversationId</code></td><td>string</td><td>Hayır</td><td>A value that you can send during the request and receive in the result can be used to make a request/response match.</td></tr></tbody></table>

### Request

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

### Response

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "locale": "en",
    "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",
    "fraudStatus": 1,
    "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"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "5126",
    "errorMessage": "Token does not belong to this merchant",
    "locale": "en",
    "systemTime": 1750241113790,
    "conversationId": "8152109759"
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

<table><thead><tr><th>Parametre İsmi</th><th width="103.33333333333331">Tip</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Service response result (success / failure).</td></tr><tr><td><code>locale</code></td><td>String</td><td>Language. Default: TR<br>Can take TR and EN values.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>Response system timestamp value.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>If set, conversation ID to match request and response.</td></tr><tr><td><code>token</code></td><td>String</td><td>The token value of the checkoutform used in the checkout process.</td></tr><tr><td><code>paymentStatus</code></td><td>String</td><td>Payment response result (SUCCESS, FAILURE).</td></tr><tr><td><code>memberEmail</code></td><td>String</td><td>Member's email information.</td></tr><tr><td><code>memberGsmNumber</code></td><td>String</td><td>Member's gsm number information.</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Total amount of basket.</td></tr><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system.</td></tr><tr><td><code>installment</code></td><td>Integer</td><td>Ödemenin taksit bilgisi, tek çekim için 1 döner. Geçerli değerler: 1, 2, 3, 6, 9, 12</td></tr><tr><td><code>paymentId</code></td><td>String</td><td>ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests).</td></tr><tr><td><code>fraudStatus</code></td><td>Integer</td><td><p></p><p>Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is <strong>1</strong>; for <strong>0</strong>, wait for notification.<br></p><ul><li><strong>1</strong>: Approved</li><li><strong>0</strong>: In review</li><li><strong>-1</strong>: Rejected</li></ul></td></tr><tr><td><code>merchantCommissionRate</code></td><td>Decimal</td><td>Merchant commission rate (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate = 10).</td></tr><tr><td><code>merchantCommissionRateAmount</code></td><td>Decimal</td><td>Merchant commission rate amount (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate amount = 10).</td></tr><tr><td><code>iyziCommissionRateAmount</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>basketId</code></td><td>String</td><td>Merchant's basket ID.</td></tr><tr><td><code>errorCode</code></td><td>String</td><td>Error code if service response status is failure.</td></tr><tr><td><code>errorMessage</code></td><td>String</td><td>Error message if service response status is failure.</td></tr><tr><td><code>errorGroup</code></td><td>String</td><td>Error group if service response status is failure.</td></tr><tr><td><code>currency</code></td><td>String</td><td>The currency in which payment is received.</td></tr><tr><td><code>itemId (ItemTransactions)</code></td><td>String</td><td>Item ID of each item in basket.</td></tr><tr><td><code>transactionStatus (ItemTransactions)</code></td><td>Integer</td><td>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.</td></tr><tr><td><code>paymentTransactionId (ItemTransactions)</code></td><td>String</td><td>Ö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.</td></tr><tr><td><code>price (ItemTransactions)</code></td><td>Decimal</td><td>Item price of each item in basket.</td></tr><tr><td><code>paidPrice (ItemTransactions)</code></td><td>Decimal</td><td>Captured amount from card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>merchantCommissionRate (ItemTransactions)</code></td><td>Decimal</td><td>The ratio of the maturity/commission rate applied by the merchant, broken down by segment.</td></tr><tr><td><code>merchantCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>Amount of the maturity/commission amount applied by the merchant, broken down on a breakdown basis.</td></tr><tr><td><code>iyziCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>blockageRate (ItemTransactions)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>blockageRateAmountMerchant (ItemTransactions)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>blockageResolvedDate (ItemTransactions)</code></td><td>String</td><td>Date of unblocking by transaction. yyyy-MM-dd HH:mm:ss format, for example 2015-10-19 14:36:52.</td></tr><tr><td><code>merchantPayoutAmount (ItemTransactions)</code></td><td>Decimal</td><td>Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)</td></tr><tr><td><code>paidPrice(convertedPayout)</code></td><td>Decimal</td><td>Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>iyziCommissionRateAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission rate amount based on each item.</td></tr><tr><td><code>iyziCommissionFee (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission fee based on each item.</td></tr><tr><td><code>blockageRateAmountMerchant (convertedPayout)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>merchantPayoutAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions).</td></tr><tr><td><code>iyziConversationRate (convertedPayout)</code></td><td>Decimal</td><td>iyzico conversation rate.</td></tr><tr><td><code>iyziConversationRateAmount (convertedPayout)</code></td><td>Decimal</td><td>For this breakdown, the amount to be sent to the merchant after deducting iyzico transaction fee, commission amount and blockages.</td></tr><tr><td><code>currency (convertedPayout)</code></td><td>String</td><td>Currency for payout conversion.</td></tr><tr><td><code>mdStatus</code></td><td>String</td><td>It is the value returned from the bank. This value is returned only if the payment failed and the transaction was made with 3ds. It can take the values 0,2,3,4,5,6,7.<br>If the 3D Transaction is Successful, it takes the value 1.</td></tr><tr><td><code>authCode</code></td><td>String</td><td>uniq value produced by iyzico.</td></tr><tr><td><code>phase</code></td><td>String</td><td>Payment phase information. Takes the value AUTH.</td></tr><tr><td><code>signature</code></td><td>String</td><td>The signature value that can be used for signature verification.</td></tr><tr><td><code>cardType</code></td><td>String</td><td>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.</td></tr><tr><td><code>cardAssociation</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the organization to which the card belongs. Valid values: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY</td></tr><tr><td><code>cardFamily</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the family to which the card belongs. Valid values: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage</td></tr><tr><td><code>binNumber</code></td><td>String</td><td>First 6 digit of card.</td></tr><tr><td><code>lastFourDigits</code></td><td>String</td><td>Last 4 digits of the payment card.</td></tr><tr><td><code>sessionToken(sessionInfo)</code></td><td>String</td><td>This is the session key information of the payment transaction made by the Member in the same payment type.</td></tr><tr><td><code>sessionStatus(sessionInfo)</code></td><td>String</td><td>Session status of the user. It takes ACTIVE or PASSIVE values.</td></tr><tr><td><code>memberIdentifier(sessionInfo)</code></td><td>String</td><td>Member unique key information. This key is used for member information in payment transactions.</td></tr><tr><td><code>paymentType(sessionInfo)</code></td><td>String</td><td>Specifies the payment type. It can return FUND or CARD_PAYMENT.<br>FUND Balance Payment<br>CARD_PAYMENT: Card Payment</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>The URL address specified in the request and redirected as a result of the operation.</td></tr></tbody></table>


# Access Token Retrieval

An `accessToken` is required to trigger a tokenization payment and retrieve the details of the latest payment. By making a request to this service, you can obtain the necessary `accessToken`.

{% hint style="info" %}
The generated `accessToken` is valid for **5 minutes**.
{% endhint %}

### Access Token Retrieval

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/retrieve/access-token`<br>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |

### Request Parameters

<table><thead><tr><th width="178.2308349609375">Parameter</th><th>Type</th><th>Required</th><th width="316.64501953125">Description</th></tr></thead><tbody><tr><td><code>sessionToken</code></td><td>String</td><td>Yes</td><td>This is the session key information that the Member pays in the same payment type.</td></tr><tr><td><code>memberIdentifier</code></td><td>String</td><td>Yes</td><td>Member unique key information. This key is used for member information in payment transactions.</td></tr><tr><td><code>locale</code></td><td>String</td><td>No</td><td>Used to set the language of the texts returned as a result of iyzico request. The default value is en. can be used as en.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>No</td><td>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.</td></tr></tbody></table>

### Request

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

### Response

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "260016",
    "errorMessage": "Session token could not be found.",
    "locale": "en",
    "systemTime": 1750250353523
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

| Parameter        | Type   | Description                                                                                                                 |
| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `status`         | String | Refers to the request result. success or failure values can be returned.                                                    |
| `locale`         | String | Refers to the language of the returned response.                                                                            |
| `systemTime`     | Long   | The current unix timestamp of the returned result.                                                                          |
| `conversationId` | String | The value sent during the request is returned.                                                                              |
| `accessToken`    | String | The bearer token information for the Member to trigger payments through services.                                           |
| `errorCode`      | String | If the operation was failed, this is the code that indicates the failure.                                                   |
| `errorMessage`   | String | If the operation is failed, this is a message detailing the error, with language support according to the locale parameter. |


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

## Retrieve Last Payment Info

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/retrieve/last-payment-info`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |
| access-token  | `{{accessToken}}`  |

### **Request Parameter**

| Parameter          | Type   | Required | Description                                                                                                                                                         |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionToken`     | String | Yes      | This is the session key information that the Member pays in the same payment type.                                                                                  |
| `memberIdentifier` | String | Yes      | Member unique key information. This key is used for member information in payment transactions.                                                                     |
| `locale`           | String | No       | Used to set the language of the texts returned as a result of iyzico request. The default value is en. can be used as en.                                           |
| `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. |

### Request

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

### Response

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "locale": "en",
    "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
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "100311",
    "errorMessage": "Access token expired",
    "systemTime": 1750250774313
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

| Parameter         | Type    | Description                                                                                                                                                                                              |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`          | String  | Service response result (success / failure).                                                                                                                                                             |
| `locale`          | String  | Specifies the language of the returned response.                                                                                                                                                         |
| `systemTime`      | Long    | Response system unix timestamp value.                                                                                                                                                                    |
| `conversationId`  | String  | If set, conversation ID to match request and response.                                                                                                                                                   |
| `cardHolderName`  | String  | <p>Name and Surname of the Cardholder.<br>Returns when payment is made with the card.</p>                                                                                                                |
| `cardAssociation` | String  | <p>Returns when payment is made by card.<br>Valid values are VISA, MASTER\_CARD, AMERICAN\_EXPRESS, TROY</p>                                                                                             |
| `errorCode`       | String  | If the operation was failed, this is the code that indicates the error.                                                                                                                                  |
| `errorMessage`    | String  | If the operation is failed, this is a message detailing the error, with language support according to the locale parameter.                                                                              |
| `cardFamily`      | String  | <p>Returns when payment is made by card.<br>Returns card family information.<br>Valid values Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage</p>                                              |
| `binNumber`       | String  | <p>Returns when payment is made by card.<br>First 8 digits of the card.</p>                                                                                                                              |
| `lastFourDigits`  | String  | <p>Returns when payment is made by card.<br>Last 4 digits of the card.</p>                                                                                                                               |
| `cardBankName`    | String  | <p>Returns when payment is made by card.<br>Card Bank Name.</p>                                                                                                                                          |
| `cardType`        | String  | <p>Returns when payment is made by card.<br>If the payment card is a local card, it returns the card type information. It takes the values DEBIT\_CARD and CREDIT\_CARD.</p>                             |
| `expireMonth`     | String  | <p>Returns when payment is made by card.<br>Expiry date is returned on a month basis.</p>                                                                                                                |
| `expireYear`      | String  | <p>Returns when payment is made by card.<br>Returns the expire date in years.</p>                                                                                                                        |
| `expired`         | boolean | <p>Returns when payment is made by card.<br>Card expire information<br>takes true and false values.<br>Returns true if the card has expired.</p>                                                         |
| `willExpireSoon`  | boolean | <p>Returns when payment is made by card.<br>This is the expiration information of the card in this month.<br>takes true and false values.<br>Returns true if the card will expire within this month.</p> |
| `paymentType`     | String  | <p>Specifies the payment type. It can return FUND or CARD\_PAYMENT.<br>FUND Balance Payment<br>CARD\_PAYMENT: Card Payment</p>                                                                           |
| `sessionToken`    | String  | It is the session key information that the Member pays in the same payment type.                                                                                                                         |
| `token`           | String  | Unique value created for checkout form. It is generated for each transaction and returned to the merchant.                                                                                               |
| `paymentId`       | Stirng  | The ID of the payment must be kept by the merchant. It is used for payment cancellation and communication with iyzico.                                                                                   |


# Initialize Payment with Session

Based on the type of the last payment made using the obtained session information, the payment can be processed in two different ways as shown below.

* [Balance Payment](/en/payment-methods/tokenization/tokenization-integration/initialize-payment-with-session/balance-payment)
* [Card Payment](/en/payment-methods/tokenization/tokenization-integration/initialize-payment-with-session/card-payment)

<table><thead><tr><th width="186.734375">Payment Types in Response</th><th>Parameter</th><th width="256.44921875">Description</th><th>Payment Type in Requestu</th></tr></thead><tbody><tr><td>When the last payment is made with the balance, paymentType returns “FUND”.</td><td>FUND</td><td>Means Payment with Balance.</td><td>In this case, paymentType “FUND” should be sent in the next payment request.</td></tr><tr><td>When the last payment is made by Card, paymentType returns as “CARD_PAYMENT”.</td><td>NON3D</td><td>Non-3DS Payment Method</td><td>For 2D Processing, it must be sent as “NON3D”.</td></tr><tr><td>When the last payment is made by Card, paymentType returns as “CARD_PAYMENT”.</td><td>3DS</td><td>3DS Payment Method</td><td>3DS For a 3DS transaction, “3DS” must be sent. Debit cards must be sent as 3DS.</td></tr></tbody></table>


# Balance Payment

This service is used to perform API-to-API balance payments.\
If the `paymentType` value returned from the **Retrieve Last Payment Information** service is `"FUND"`, this service should be used.

## Fund Payment

<mark style="color:green;">`POST`</mark> `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**

<table><thead><tr><th width="219.78515625">Parameter</th><th>Type</th><th>Mandatory</th><th width="193.8878173828125">Açıklama</th></tr></thead><tbody><tr><td><code>conversationId</code></td><td>String</td><td>No</td><td>Conversation ID to match request and response.</td></tr><tr><td><code>locale</code></td><td>String</td><td>No</td><td>Language (default: tr)</td></tr><tr><td><code>paymentType</code></td><td>String</td><td>Yes</td><td>Indicates the payment type. For balance payments, it should be sent as <code>"FUND"</code>.</td></tr><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Yes</td><td>Final amount (including installment fee) that will be charged to customer’s card.</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Yes</td><td>Total amount of basket. The sum of basket items’ amount must be equal to the price of basket.</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>Yes</td><td>Merchant callback URL for payment result notification.<br>callBackUrl address should have SSL.</td></tr><tr><td><code>paymentGroup</code></td><td>String</td><td>No</td><td>Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION.</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>Currency (default: TRY). Alternatively, you can set USD, EUR, GBP .</td></tr><tr><td><code>basketId</code></td><td>String</td><td>No</td><td>Merchant's basket ID.</td></tr><tr><td><code>buyerId</code></td><td>String</td><td>Yes</td><td>ID of buyer.</td></tr><tr><td><code>buyerName</code></td><td>String</td><td>Yes</td><td>Name of buyer.</td></tr><tr><td><code>buyerSurname</code></td><td>String</td><td>Yes</td><td>Surname of buyer.</td></tr><tr><td><code>identityNumber</code></td><td>String</td><td>Yes</td><td>Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants.</td></tr><tr><td><code>email</code></td><td>String</td><td>Yes</td><td>Email of buyer.</td></tr><tr><td><code>gsmNumber</code></td><td>String</td><td>No</td><td>GSM Number of buyer.</td></tr><tr><td><code>registrationAddress</code></td><td>String</td><td>Yes</td><td>Registration address of buyer.</td></tr><tr><td><code>city</code></td><td>String</td><td>Yes</td><td>City of buyer.</td></tr><tr><td><code>country</code></td><td>String</td><td>Yes</td><td>Country of buyer.</td></tr><tr><td><code>IP</code></td><td>String</td><td>No</td><td>IP of buyer.</td></tr><tr><td><code>zipCode</code></td><td>String</td><td>Yes</td><td>Zip code of buyer.</td></tr><tr><td><code>address(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory</td></tr><tr><td><code>contactName(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>city(shippingAddress)</code></td><td>String</td><td>Yes</td><td>City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>country(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>zipCode(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Zip code of shipping address.</td></tr><tr><td><code>address(billingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of billing address.</td></tr><tr><td><code>contactName(billingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of billing address.</td></tr><tr><td><code>city(billingAddress)</code></td><td>String</td><td>Yes</td><td>City name of billing address.</td></tr><tr><td><code>country(billingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of billing address.</td></tr><tr><td><code>basketItemId</code></td><td>String</td><td>Yes</td><td>Basket Item ID. It can take a maximum of 500 characters.</td></tr><tr><td><code>basketItemPrice</code></td><td>String</td><td>Yes</td><td>Price value for each item. Must be greater than zero.</td></tr><tr><td><code>basketItemName</code></td><td>String</td><td>Yes</td><td>Name of the item in the basket.</td></tr><tr><td><code>basketItemCategory1</code></td><td>String</td><td>Yes</td><td>Category 1 for item in the basket.</td></tr><tr><td><code>basketItemCategory2</code></td><td>String</td><td>No</td><td>Category 2 for item in the basket.</td></tr><tr><td><code>basketItemItemType</code></td><td>String</td><td>Yes</td><td>Item Type. Valid values are PHYSICAL,VIRTUAL</td></tr><tr><td><code>sessionToken</code></td><td>String</td><td>Yes</td><td>This is the session key information that the Member pays in the same payment type.</td></tr><tr><td><code>memberIdentifier</code></td><td>String</td><td>Yes</td><td>Member unique key information. This key is used for member information in payment transactions.</td></tr></tbody></table>

### Request

```javascript
{
    "sessionToken": "{{sessionToken}}",
    "memberIdentifier": "{{memberIdentifier}}",
    "conversationId": "conversationId",
    "locale": "en",
    "paymentType": "FUND",
    "paidPrice": 1.0,
    "price": 1.0,
    "callbackUrl": "callbackUrl",
    "paymentGroup": "PRODUCT",
    "currency": "TRY",
    "basketId": "B67832",
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864111",
        "email": "sandboxtest0@gmail.com",
        "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

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1748553300302,
    "conversationId": "conversationId",
    "sessionToken": "16f60166-74ba-4e5c-ac52-31b5762652d4",
    "paymentId": 24233528,
    "paymentStatus": "SUCCESS",
    "checkoutToken": "7ce32610-9851-4b16-939a-5d4beae75475",
    "price": 1.00000000,
    "paidPrice": 1.00000000,
    "installment": 1,
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.01750000,
    "iyziCommissionFee": 0E-8,
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "26241258",
            "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-05-31 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"
            }
        }
    ],
    "phase": "AUTH",
    "signature": "096cf80a59d611f1702803b91bc073300e9a57a5ab47e4a839e598fc13af3d5b"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "260018",
    "errorMessage": "Session payment type is not matched.",
    "locale": "en",
    "systemTime": 1751956747198
}
```

{% endtab %}
{% endtabs %}

### Response Parameters

<table><thead><tr><th>Parametre İsmi</th><th width="103.33333333333331">Tip</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Service response result (success / failure).</td></tr><tr><td><code>locale</code></td><td>String</td><td>Language. Default: TR<br>Can take TR and EN values.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>Response system timestamp value.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>If set, conversation ID to match request and response.</td></tr><tr><td><code>checkoutToken</code></td><td>String</td><td>The token value of the checkoutform used in the checkout process.</td></tr><tr><td><code>paymentStatus</code></td><td>String</td><td>Payment response result (SUCCESS, FAILURE).</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Total amount of basket.</td></tr><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system.</td></tr><tr><td><code>installment</code></td><td>Integer</td><td><p>The installment information of the payment.<br>Returns <strong>1</strong> for single-payment transactions.<br></p><p>Valid values: <strong>1, 2, 3, 6, 9, 12</strong>.</p></td></tr><tr><td><code>fraudStatus</code></td><td>Integer</td><td><p>Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is <strong>1</strong>; for <strong>0</strong>, wait for notification.<br></p><ul><li><strong>1</strong>: Approved</li><li><strong>0</strong>: In review</li><li><strong>-1</strong>: Rejected</li></ul></td></tr><tr><td><code>paymentId</code></td><td>String</td><td>ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests).</td></tr><tr><td><code>merchantCommissionRate</code></td><td>Decimal</td><td>Merchant commission rate (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate = 10).</td></tr><tr><td><code>merchantCommissionRateAmount</code></td><td>Decimal</td><td>Merchant commission rate amount (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate amount = 10).</td></tr><tr><td><code>iyziCommissionRateAmount</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>basketId</code></td><td>String</td><td>Merchant's basket ID.</td></tr><tr><td><code>errorCode</code></td><td>String</td><td>Error code if service response status is failure.</td></tr><tr><td><code>errorMessage</code></td><td>String</td><td>Error message if service response status is failure.</td></tr><tr><td><code>errorGroup</code></td><td>String</td><td>Error group if service response status is failure.</td></tr><tr><td><code>currency</code></td><td>String</td><td>The currency in which payment is received.</td></tr><tr><td><code>itemId (ItemTransactions)</code></td><td>String</td><td>Item ID of each item in basket.</td></tr><tr><td><code>transactionStatus (ItemTransactions)</code></td><td>Integer</td><td>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.</td></tr><tr><td><code>paymentTransactionId (ItemTransactions)</code></td><td>String</td><td>Ö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.</td></tr><tr><td><code>price (ItemTransactions)</code></td><td>Decimal</td><td>Item price of each item in basket.</td></tr><tr><td><code>paidPrice (ItemTransactions)</code></td><td>Decimal</td><td>Captured amount from card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>merchantCommissionRate (ItemTransactions)</code></td><td>Decimal</td><td>The ratio of the maturity/commission rate applied by the merchant, broken down by segment.</td></tr><tr><td><code>merchantCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>Amount of the maturity/commission amount applied by the merchant, broken down on a breakdown basis.</td></tr><tr><td><code>iyziCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>blockageRate (ItemTransactions)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>blockageRateAmountMerchant (ItemTransactions)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>blockageResolvedDate (ItemTransactions)</code></td><td>String</td><td>Date of unblocking by transaction. yyyy-MM-dd HH:mm:ss format, for example 2015-10-19 14:36:52.</td></tr><tr><td><code>merchantPayoutAmount (ItemTransactions)</code></td><td>Decimal</td><td>Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)</td></tr><tr><td><code>paidPrice(convertedPayout)</code></td><td>Decimal</td><td>Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>iyziCommissionRateAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission rate amount based on each item.</td></tr><tr><td><code>iyziCommissionFee (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission fee based on each item.</td></tr><tr><td><code>blockageRateAmountMerchant (convertedPayout)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>merchantPayoutAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions).</td></tr><tr><td><code>iyziConversationRate (convertedPayout)</code></td><td>Decimal</td><td>iyzico conversation rate.</td></tr><tr><td><code>iyziConversationRateAmount (convertedPayout)</code></td><td>Decimal</td><td>For this breakdown, the amount to be sent to the merchant after deducting iyzico transaction fee, commission amount and blockages.</td></tr><tr><td><code>currency (convertedPayout)</code></td><td>String</td><td>Currency for payout conversion.</td></tr><tr><td><code>authCode</code></td><td>String</td><td>uniq value produced by iyzico.</td></tr><tr><td><code>phase</code></td><td>String</td><td>Payment phase information. Takes the value AUTH.</td></tr><tr><td><code>signature</code></td><td>String</td><td>The signature value that can be used for signature verification.</td></tr><tr><td><code>cardType</code></td><td>String</td><td>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.</td></tr><tr><td><code>cardAssociation</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the organization to which the card belongs. Valid values: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY</td></tr><tr><td><code>cardFamily</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the family to which the card belongs. Valid values: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage</td></tr><tr><td><code>binNumber</code></td><td>String</td><td>First 6 digit of card.</td></tr><tr><td><code>lastFourDigits</code></td><td>String</td><td>Last 4 digits of the payment card.</td></tr><tr><td><code>sessionToken</code></td><td>String</td><td>This is the session key information of the payment transaction made by the Member in the same payment type.</td></tr></tbody></table>


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

{% 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, and the `threeDSHtmlContent` field may be returned in the response schema.
{% endhint %}

## Card Payment Service

<mark style="color:green;">`POST`</mark> `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**

<table><thead><tr><th width="219.78515625">Parameter</th><th>Type</th><th>Mandatory</th><th width="193.8878173828125">Description</th></tr></thead><tbody><tr><td><code>sessionToken</code></td><td>String</td><td>Yes</td><td>This is the session key information of the payment transaction made by the Member in the same payment type.</td></tr><tr><td><code>memberIdentifier</code></td><td>String</td><td>Yes</td><td>Member unique key information. This key is used for member information in payment transactions.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>No</td><td>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.</td></tr><tr><td><code>locale</code></td><td>String</td><td>No</td><td>Language (default: tr)</td></tr><tr><td><code>paymentType</code></td><td>String</td><td>Yes</td><td>Indicates the type of payment to be performed. For card payments, it should be sent as either <code>"3DS"</code> or <code>"NON3D"</code>.</td></tr><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Yes</td><td>Final amount (including installment fee) that will be charged to customer’s card</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Yes</td><td>Total amount of basket. The sum of basket items’ amount must be equal to the price of basket.</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>Yes</td><td>Merchant callback URL for payment result notification.<br>callBackUrl address should have SSL.</td></tr><tr><td><code>paymentGroup</code></td><td>String</td><td>No</td><td>Payment group (default: PRODUCT). Valid values are PRODUCT, LISTING, SUBSCRIPTION</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>Currency (default: TRY). Alternatively, you can set USD, EUR, GBP </td></tr><tr><td><code>basketId</code></td><td>String</td><td>No</td><td>Merchant's basket ID</td></tr><tr><td><code>buyerId</code></td><td>String</td><td>Yes</td><td>ID of buyer.</td></tr><tr><td><code>buyerName</code></td><td>String</td><td>Yes</td><td>Name of buyer.</td></tr><tr><td><code>buyerSurname</code></td><td>String</td><td>Yes</td><td>Surname of buyer</td></tr><tr><td><code>identityNumber</code></td><td>String</td><td>Yes</td><td>Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants</td></tr><tr><td><code>email</code></td><td>String</td><td>Yes</td><td>Email of buyer.</td></tr><tr><td><code>gsmNumber</code></td><td>String</td><td>No</td><td>GSM number of buyer.</td></tr><tr><td><code>registrationAddress</code></td><td>String</td><td>Yes</td><td>Registration address of buyer.</td></tr><tr><td><code>city</code></td><td>String</td><td>Yes</td><td>City of buyer.</td></tr><tr><td><code>country</code></td><td>String</td><td>Yes</td><td>Country of buyer.</td></tr><tr><td><code>IP</code></td><td>String</td><td>No</td><td>IP of buyer.</td></tr><tr><td><code>zipCode</code></td><td>String</td><td>Yes</td><td>Zip code of buyer.</td></tr><tr><td><code>address(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory</td></tr><tr><td><code>contactName(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>city(shippingAddress)</code></td><td>String</td><td>Yes</td><td>City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>country(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory.</td></tr><tr><td><code>zipCode(shippingAddress)</code></td><td>String</td><td>Yes</td><td>Zip code of shipping address.</td></tr><tr><td><code>address(billingAddress)</code></td><td>String</td><td>Yes</td><td>Address details of billing address.</td></tr><tr><td><code>contactName(billingAddress)</code></td><td>String</td><td>Yes</td><td>Contact name of billing address.</td></tr><tr><td><code>city(billingAddress)</code></td><td>String</td><td>Yes</td><td>City name of billing address.</td></tr><tr><td><code>country(billingAddress)</code></td><td>String</td><td>Yes</td><td>Country name of billing address.</td></tr><tr><td><code>basketItemId</code></td><td>String</td><td>Yes</td><td><p>Basket Item ID.</p><p>It can take a maximum of 500 characters.</p></td></tr><tr><td><code>basketItemPrice</code></td><td>String</td><td>Yes</td><td>Price value for each item. Must be greater than zero.</td></tr><tr><td><code>basketItemName</code></td><td>String</td><td>Yes</td><td>Name of the item in the basket.</td></tr><tr><td><code>basketItemCategory1</code></td><td>String</td><td>No</td><td>Category 1 for item in the basket.</td></tr><tr><td><code>basketItemCategory2</code></td><td>String</td><td>No</td><td>Category 2 for item in the basket.</td></tr><tr><td><code>basketItemItemType</code></td><td>String</td><td>Yes</td><td>Item Type. Valid values are PHYSICAL,VIRTUAL</td></tr></tbody></table>

### 3DS Request Body

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

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "100302",
    "errorMessage": "An unexpected error occurred",
    "locale": "en",
    "systemTime": 1751972867366
}
```

{% endtab %}
{% endtabs %}

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

### 3DS Response

<table><thead><tr><th width="193.64630126953125">Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Returns the result of the request. It can return either the value <code>"success"</code> or <code>"failure"</code>.</td></tr><tr><td><code>locale</code></td><td>String</td><td>The request is sent, the response is returned in the language.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>Unix time value at the time of the request.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>The value sent during the request is transmitted back exactly as it was.</td></tr><tr><td><code>sessionToken</code></td><td>String</td><td>This is the session key information that the Member pays in the same payment type.</td></tr><tr><td><code>paymentId</code></td><td>Long</td><td>The uniq payment number generated by iyzico.</td></tr><tr><td><code>paymentStatus</code></td><td>String</td><td>Payment status information. It can take <code>"success"</code> and <code>"failure"</code></td></tr><tr><td><code>threeDSHtmlContent</code></td><td>String</td><td>3D verification screen in HTML format.</td></tr><tr><td><code>checkoutFormToken</code></td><td>String</td><td>The checkoutform token value of the transaction.</td></tr><tr><td><code>signature</code></td><td>String</td><td>It is the signature value that can be signature verified.</td></tr></tbody></table>

### NON3D Request Body

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

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="401" %}

```python
{
    "status": "failure",
    "errorCode": "100303",
    "errorMessage": "Unauthorised access attempt occurred",
    "locale": "en",
    "systemTime": 1751974036714
}
```

{% endtab %}
{% endtabs %}

### NON3D Response Parameter

<table><thead><tr><th>Parametre İsmi</th><th width="103.33333333333331">Tip</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Service response result (success / failure).</td></tr><tr><td><code>locale</code></td><td>String</td><td>Language. Default: TR<br>Can take TR and EN values.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>Response system timestamp value.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>If set, conversation ID to match request and response.</td></tr><tr><td><code>sessionToken</code></td><td>String</td><td>This is the session key information of the payment transaction made by the Member in the same payment type.</td></tr><tr><td><code>paymentStatus</code></td><td>String</td><td>Payment response result (SUCCESS, FAILURE).</td></tr><tr><td><code>checkoutToken</code></td><td>String</td><td>The token value of the checkoutform used in the checkout process.</td></tr><tr><td><code>paymentId</code></td><td>String</td><td>ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests).</td></tr><tr><td><code>price</code></td><td>Decimal</td><td>Total amount of basket.</td></tr><tr><td><code>paidPrice</code></td><td>Decimal</td><td>Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system.</td></tr><tr><td><code>installment</code></td><td>Integer</td><td><p>The installment information of the payment.<br>Returns <strong>1</strong> for single-payment transactions.<br></p><p>Valid values: <strong>1, 2, 3, 6, 9, 12</strong>.</p></td></tr><tr><td><code>fraudStatus</code></td><td>Integer</td><td><p>Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is <strong>1</strong>; for <strong>0</strong>, wait for notification.<br></p><ul><li><strong>1</strong>: Approved</li><li><strong>0</strong>: In review</li><li><strong>-1</strong>: Rejected</li></ul></td></tr><tr><td><code>merchantCommissionRate</code></td><td>Decimal</td><td>Merchant commission rate (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate = 10).</td></tr><tr><td><code>merchantCommissionRateAmount</code></td><td>Decimal</td><td>Merchant commission rate amount (e.g. price=100 &#x26; paidPrice=110, then merchant commission rate amount = 10).</td></tr><tr><td><code>iyziCommissionRateAmount</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>basketId</code></td><td>String</td><td>Merchant's basket ID.</td></tr><tr><td><code>errorCode</code></td><td>String</td><td>Error code if service response status is failure.</td></tr><tr><td><code>errorMessage</code></td><td>String</td><td>Error message if service response status is failure.</td></tr><tr><td><code>errorGroup</code></td><td>String</td><td>Error group if service response status is failure.</td></tr><tr><td><code>currency</code></td><td>String</td><td>The currency in which payment is received.</td></tr><tr><td><code>itemId (ItemTransactions)</code></td><td>String</td><td>Item ID of each item in basket.</td></tr><tr><td><code>transactionStatus (ItemTransactions)</code></td><td>Integer</td><td>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.</td></tr><tr><td><code>paymentTransactionId (ItemTransactions)</code></td><td>String</td><td>Ö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.</td></tr><tr><td><code>price (ItemTransactions)</code></td><td>Decimal</td><td>Item price of each item in basket.</td></tr><tr><td><code>paidPrice (ItemTransactions)</code></td><td>Decimal</td><td>Captured amount from card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>merchantCommissionRate (ItemTransactions)</code></td><td>Decimal</td><td>The ratio of the maturity/commission rate applied by the merchant, broken down by segment.</td></tr><tr><td><code>merchantCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>Amount of the maturity/commission amount applied by the merchant, broken down on a breakdown basis.</td></tr><tr><td><code>iyziCommissionRateAmount (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission rate amount for payment transaction.</td></tr><tr><td><code>iyziCommissionFee (ItemTransactions)</code></td><td>Decimal</td><td>iyzico commission fee for payment transaction.</td></tr><tr><td><code>blockageRate (ItemTransactions)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>blockageRateAmountMerchant (ItemTransactions)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>blockageResolvedDate (ItemTransactions)</code></td><td>String</td><td>Date of unblocking by transaction. yyyy-MM-dd HH:mm:ss format, for example 2015-10-19 14:36:52.</td></tr><tr><td><code>merchantPayoutAmount (ItemTransactions)</code></td><td>Decimal</td><td>Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)</td></tr><tr><td><code>paidPrice(convertedPayout)</code></td><td>Decimal</td><td>Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.</td></tr><tr><td><code>iyziCommissionRateAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission rate amount based on each item.</td></tr><tr><td><code>iyziCommissionFee (convertedPayout)</code></td><td>Decimal</td><td>Converted iyzico commission fee based on each item.</td></tr><tr><td><code>blockageRateAmountMerchant (convertedPayout)</code></td><td>Decimal</td><td>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.</td></tr><tr><td><code>merchantPayoutAmount (convertedPayout)</code></td><td>Decimal</td><td>Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions).</td></tr><tr><td><code>iyziConversationRate (convertedPayout)</code></td><td>Decimal</td><td>iyzico conversation rate.</td></tr><tr><td><code>iyziConversationRateAmount (convertedPayout)</code></td><td>Decimal</td><td>For this breakdown, the amount to be sent to the merchant after deducting iyzico transaction fee, commission amount and blockages.</td></tr><tr><td><code>currency (convertedPayout)</code></td><td>String</td><td>Currency for payout conversion.</td></tr><tr><td><code>authCode</code></td><td>String</td><td>uniq value produced by iyzico.</td></tr><tr><td><code>phase</code></td><td>String</td><td>Payment phase information. Takes the value AUTH.</td></tr><tr><td><code>signature</code></td><td>String</td><td>The signature value that can be used for signature verification.</td></tr><tr><td><code>cardType</code></td><td>String</td><td>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.</td></tr><tr><td><code>cardAssociation</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the organization to which the card belongs. Valid values: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY</td></tr><tr><td><code>cardFamily</code></td><td>String</td><td>Returns only for card payments.<br>If the payment card is a local card, the family to which the card belongs. Valid values: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage</td></tr><tr><td><code>binNumber</code></td><td>String</td><td>First 6 digit of card.</td></tr><tr><td><code>lastFourDigits</code></td><td>String</td><td>Last 4 digits of the payment card.</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>Merchant callback URL for payment result notification.<br>callBackUrl address should have SSL.</td></tr></tbody></table>


# Session Expire

This service is used to terminate an active session. To finalize the session termination, the `sessionToken` and the corresponding `memberIdentifier` must be provided.

After the service call, the session is set to a passive (`PASSIVE`) status. Following this, any checks performed via the session retrieval service will return the session status as `PASSIVE`.

Once the session is marked as passive, no further payment transactions can be performed using that session. This ensures that incomplete or abandoned sessions are properly managed and that the payment flow remains secure and controlled.

### Session Expire

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/invalidate/session`

#### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |

### Request

```json
{
    "locale": "tr",
    "conversationId": "123456789",
    "sessionToken": "f2f06a82-6480-4d2b-811d-93168ddce577",
    "memberIdentifier": "702831f3-1cc6-4b25-ad2b-878afc64f408"
}
```

### **Request Parameters**

<table><thead><tr><th width="190.3515625">Paremetre</th><th>Tip</th><th>Zorunluluk</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>sessionToken</code></td><td>string</td><td>Evet</td><td>Token value of the session to be expired.</td></tr><tr><td><code>memberIdentifier</code></td><td>string</td><td>Evet</td><td>Unique key information of the member associated with the session.</td></tr><tr><td><code>locale</code></td><td>string</td><td>Hayır</td><td>Language value sent in the request. Can be <code>EN</code> or <code>TR</code>.</td></tr><tr><td><code>conversationId</code></td><td>string</td><td>Hayır</td><td>A value sent within the request and returned in the response, used to match request and response.</td></tr></tbody></table>

### **Response**&#x20;

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1775484679584,
    "conversationId": "test",
    "sessionToken": "0636d0cf-b54e-4896-b3f2-91f69e9c6b11",
    "memberIdentifier": "702831f3-1cc6-4b25-ad2b-878afc64f408"
}

```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "260030",
    "errorMessage": "Session is already invalidated at 4/6/26, 5:11 PM.",
    "locale": "en",
    "systemTime": 1775484702256,
    "conversationId": "test"
}
```

{% endtab %}
{% endtabs %}

### **Response Parameters**

<table><thead><tr><th>Parametre İsmi</th><th width="103.33333333333331">Tip</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>status</code></td><td>String</td><td>Indicates the result of the request. Returns <code>success</code> if successful, <code>failure</code> if unsuccessful.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>The Unix timestamp of the response time.</td></tr><tr><td><code>errorCode</code></td><td>String</td><td>The error code returned if the transaction fails.</td></tr><tr><td><code>errorMessage</code></td><td>String</td><td>The error message returned if the transaction fails. It is localized based on the <code>locale</code> parameter.</td></tr><tr><td><code>conversationId</code></td><td>String</td><td>If sent in the request, it is returned in the response unchanged. It is only returned in failed responses.</td></tr><tr><td><code>locale</code></td><td>String</td><td>The locale value sent in the request is returned. The default value is <code>tr</code>. It is only returned in failed responses.</td></tr></tbody></table>


# Retrieve Session

This service is used to retrieve the current status of the session created after the payment process. To query a session, the `checkoutFormToken` of the payment form and the `paymentId` of the related transaction must be provided.

Instead of returning direct payment details, the service response includes session-related information. In this context, fields such as `sessionToken`, `memberIdentifier`, `sessionStatus`, and `paymentType` can be used to track the session status and user-related information.

It is recommended to use this service after the payment flow is completed to verify the final state of the session and obtain user session details. This ensures that the payment process can be securely monitored without relying on client-side redirects.

### Retrieve Session

<mark style="color:green;">`POST`</mark> `https://api.iyzipay.com/v1/pay-with-iyzico/third-party-session/retrieve/session`

#### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Authorization`    |

### Request

```json
{
  "locale": "tr",
  "conversationId": "123456789",
  "checkoutFormToken": "ab468ec8-c4ab-4449-b15b-69782f7786c6",
  "paymentId": "29414275"
}
```

### **Request Parameters**

<table><thead><tr><th width="190.3515625">Paremetre</th><th>Tip</th><th>Zorunluluk</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>checkoutFormToken</code></td><td>string</td><td>Evet</td><td>Token value of the payment form associated with the transaction.</td></tr><tr><td><code>locale</code></td><td>string</td><td>Hayır</td><td>Language value sent in the request. Can be <code>EN</code> or <code>TR</code>.</td></tr><tr><td><code>conversationId</code></td><td>string</td><td>Hayır</td><td>A value sent within the request and returned in the response, used to match request and response.</td></tr><tr><td><code>paymentId</code></td><td>string</td><td>Evet</td><td>The payment identifier of the completed transaction.</td></tr></tbody></table>

### Response

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1775471642206,
    "sessionInfo": {
        "sessionToken": "f2f06a82-6480-4d2b-811d-93168ddce577",
        "sessionStatus": "PASSIVE",
        "memberIdentifier": "702831f3-1cc6-4b25-ad2b-878afc64f408",
        "paymentType": "CARD_PAYMENT"
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "status": "failure",
    "errorCode": "260016",
    "errorMessage": "Session token bulunamadı.",
    "systemTime": 1775471996773
}
```

{% endtab %}
{% endtabs %}

### **Response Parameters**

<table><thead><tr><th width="190.3515625">Paremetre</th><th>Tip</th><th>Açıklama</th></tr></thead><tbody><tr><td><code>status</code></td><td>string</td><td>Result of the request.</td></tr><tr><td><code>locale</code></td><td>string</td><td>The locale value sent in the request.</td></tr><tr><td><code>systemTime</code></td><td>Long</td><td>Transaction time (epoch ms).</td></tr><tr><td><code>sessionToken</code></td><td>string</td><td>Session key information of the payment transaction performed by the member.</td></tr><tr><td><code>sessionStatus</code></td><td>string</td><td>Status of the session. Can be <code>ACTIVE</code> or <code>PASSIVE</code>.</td></tr><tr><td><code>memberIdentifier</code></td><td>string</td><td>Unique key of the member.</td></tr><tr><td><code>paymentType</code></td><td>string</td><td><p></p><p>Indicates the payment type. Can be <code>FUND</code> or <code>CARD_PAYMENT</code>.</p><ul><li><code>FUND</code>: Wallet balance payment</li><li><code>CARD_PAYMENT</code>: Card payment</li></ul></td></tr></tbody></table>


# Online Payment

{% embed url="<https://www.youtube.com/watch?v=DiQKba0m-qc>" %}

Following payment methods will delve into the advantages and capabilities of iyzico online payments. Let's break down these payment methods in simple terms:

<table data-card-size="large" data-view="cards"><thead><tr><th data-type="content-ref"></th><th></th></tr></thead><tbody><tr><td><a href="/pages/vtS18CXkjJn7lSzez2Am">/pages/vtS18CXkjJn7lSzez2Am</a></td><td>NON-3DS payment methods, in other words direct payment, refer to transactions where customers do not need to go through the additional security verification process. In this case, customers can make payments quickly without being redirected to another page for authentication.</td></tr><tr><td><a href="/pages/8w7DlEFOTrCcdOXOkx0y">/pages/8w7DlEFOTrCcdOXOkx0y</a></td><td>3DS payment methods involve an additional layer of security. When customers choose this method, they will be redirected to a secure page provided by their card issuer to verify their identity. This extra step helps prevent fraud and ensures a secure payment process.</td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td>The checkout form is a user interface component where customers enter their payment details, such as credit card information, to complete a purchase. It typically includes fields for card number, expiration date, CVV code, and customer billing details.</td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td>"Pay with iyzico" is a payment option that allows customers to pay directly using their Iyzico account. Customers can log in to their iyzico account during the checkout process and make a payment from their available balance or among alternative payment methods.</td></tr></tbody></table>

In summary, integrating iyzico's payment methods into your application means providing customers with a user-friendly checkout form where they can enter their payment details where they can choose any payment feature for a seamless payment experience.


# Marketplace

{% embed url="<https://www.youtube.com/watch?v=j0UB2R_C5ao>" %}

### Marketplace Product: What is it?

The Marketplace Payment Solution provides a robust payment infrastructure for platform-based e-commerce websites. When an end user makes a payment with a card on the marketplace, the funds are initially directed to the iyzico account. Subsequently, iyzico deducts the commission payable by the platform's member seller from this amount and facilitates separate payments to the seller and the platform. This seamless payment flow ensures efficient financial transactions within platform-based e-commerce websites.

Moreover, the Marketplace product enables you to accept payments and conduct sales in multiple currencies, including Turkish Lira (TL). Additionally, it offers the flexibility to receive payments in foreign currencies using alternative payment methods from international sources.

### What Can You Do with the Marketplace Product?

With the Marketplace product, you have the ability to seamlessly manage the cash flow between your sub-sellers, automate earnings and commission calculations, transfer payments to their iyzico accounts, and effortlessly generate a wide range of financial reports. This enables you to efficiently monitor the performance of your sub-sellers through iyzico merchant panel and optimize your business processes with utmost effectiveness.

<div><figure><img src="/files/Tv5mHgtC0KMWVcTgTEsb" alt=""><figcaption></figcaption></figure> <figure><img src="/files/uv2haMXyEwdhLXKJb7YH" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Jf57WzHW7jy5fzaqgVxM" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/XkCUM0SeU0kjtfxysCEL" alt=""><figcaption></figcaption></figure> <figure><img src="/files/y4KIfdUiRYMWIBH8yDLX" alt=""><figcaption></figcaption></figure> <figure><img src="/files/ZdCz10XNXQ0PFquyKQCE" alt=""><figcaption></figcaption></figure></div>

### **Frequently Asked Questions**

<details>

<summary>Who can benefit from the marketplace product?</summary>

The Marketplace product is specifically tailored for companies operating in the field of marketplaces or platform-based e-commerce. If your company falls into this category, whether you own a marketplace or manage a platform-based e-commerce website, you can leverage the benefits of this solution. To get started, simply reach out to us by sending a message through the "Contact Us" section, where you can provide details about your company and its business model. Our dedicated team will evaluate your request promptly and provide you with the necessary information and guidance.

</details>

<details>

<summary>Are my sellers required to be business owners?</summary>

It is not mandatory for sellers on your e-commerce marketplace platform to be business owners. Your platform can accommodate sub-members operating under three different business models:&#x20;

* Individual
* Sole Proprietorship
* Limited/Incorporated Company.&#x20;

With the marketplace product, you can seamlessly process payments from sub-members operating under these business models.

</details>

<details>

<summary>Will my marketplace sellers be required to sign up with iyzico? If so, where should they apply?</summary>

Your marketplace sellers do not need to go through a separate registration process with iyzico. Since you have all the required information about your sellers, you can simply onboard them into the system.

</details>

<details>

<summary>Will my sellers incur additional charges such as commission fees, system access fees, or integration fees?</summary>

No, iyzico does not deduct any service fees separately from your sellers. There are no charges for system access or integration either.

</details>

<details>

<summary>Will the commission fee be deducted from the total transaction fee or will it be charged separately from the service fee requested from the seller?</summary>

iyzico commission fee is calculated based on the total transaction fee and is deducted from the share of the marketplace that has a sufficient balance.

</details>

<details>

<summary>How will the sellers receive their payments?</summary>

When registering your sellers in the system, it is necessary to provide iyzico with their IBAN information along with other relevant details. The transfer of funds occurs once the buyer completes the transaction. As a marketplace, while your commission earnings are transferred to you, the payments are also disbursed to the sub-member businesses (your sellers).

</details>


# Marketplace Implementation

<figure><img src="/files/9GFpkjhqPKWaIyNabJit" alt=""><figcaption></figcaption></figure>

### Steps

The iyzico marketplace solution primarily encompasses the collection and settlement processes. The integration involves three key steps, as outlined below:

1. [Submerchant](/en/products/marketplace/marketplace-implementation/submerchant)
2. [Online Payment](/en/products/marketplace/marketplace-implementation/online-payment)
3. [Approval](/en/products/marketplace/marketplace-implementation/approval)

To facilitate fund transfers to sellers (submerchants), it is necessary to register these sellers with iyzico API through a one-time registration process. Upon registering the submerchant seller with iyzico, the merchant receives a unique **subMerchantKey** in the response.&#x20;

During the payment process, the corresponding **subMerchantKey** for each product's seller in the shopping cart must be provided, along with the specific amount to be transferred to the seller (**subMerchantPrice**).


# Submerchant

After the approval of the marketplace transaction, submerchants are required to have records at iyzico APIs to facilitate the money transfer. Since the merchant already has access to the submerchant details such like, email, address, name, taxoffice, it can be seamlessly transmitted to the iyzico Onboarding API for submerchant account creation and updates.

### Submerchant Services

* [Submerchant Creation](/en/products/marketplace/marketplace-implementation/submerchant#post-onboarding-submerchant)
* [Submerchant Update](/en/products/marketplace/marketplace-implementation/submerchant/submerchant-update)
* [Submerchant Details](/en/products/marketplace/marketplace-implementation/submerchant/alt-uye-sorgulama)
* [Submerchant Price / Item Update](/en/products/marketplace/marketplace-implementation/submerchant/alt-uye-sorgulama-1)

### Submerchant Creation

Possible submerchants can be one of the following 3 types: &#x20;

1. **PERSONAL**
2. **PRIVATE COMPANY**
3. **LIMITED OR JOINT STOCK COMPANY**

The parameters sent during the sub-merchant registration process may vary depending on the specific transaction type. Upon the completion of a sub-merchant registration, the response will include a unique **subMerchantKey** assigned to that particular seller. It is **essential** to securely store this value within your system, as you will need to provide the `subMerchantKey` when identifying the seller during the payment process.

{% hint style="info" %}
When transmitting parameters to iyzico, it is crucial to ensure that all values are genuine and accurately reflect the required information. Please refrain from sending random, test, or non-authentic data.
{% endhint %}

## Create Submerchant

> Creates a submerchant for the marketplace model. Supported types are \*\*PERSONAL\*\*, \*\*PRIVATE\_COMPANY\*\*, and \*\*LIMITED\_OR\_JOINT\_STOCK\_COMPANY\*\*. The subme rchant type is selected via the \*\*subMerchantType\*\* parameter.<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant":{"post":{"summary":"Create Submerchant","description":"Creates a submerchant for the marketplace model. Supported types are **PERSONAL**, **PRIVATE_COMPANY**, and **LIMITED_OR_JOINT_STOCK_COMPANY**. The subme rchant type is selected via the **subMerchantType** parameter.\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantCreateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantCreateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantCreateRequest":{"oneOf":[{"$ref":"#/components/schemas/SubmerchantPersonalRequest"},{"$ref":"#/components/schemas/SubmerchantPrivateCompanyRequest"},{"$ref":"#/components/schemas/SubmerchantLimitedJointRequest"}],"discriminator":{"propertyName":"subMerchantType","mapping":{"PERSONAL":"#/components/schemas/SubmerchantPersonalRequest","PRIVATE_COMPANY":"#/components/schemas/SubmerchantPrivateCompanyRequest","LIMITED_OR_JOINT_STOCK_COMPANY":"#/components/schemas/SubmerchantLimitedJointRequest"}},"description":"The request body varies depending on **subMerchantType**."},"SubmerchantPersonalRequest":{"description":"Personal Submerchant","type":"object","required":["subMerchantType","email","gsmNumber","address","contactName","contactSurname","subMerchantExternalId","identityNumber"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use PERSONAL for personal accounts."},"name":{"type":"string","description":"Submerchant (store) name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone."},"address":{"type":"string","description":"Submerchant address."},"iban":{"type":"string","description":"Submerchant IBAN. Must be consistent with **contactName/contactSurname**. If not sent during creation, it must be provided before product approval for payouts.\n"},"contactName":{"type":"string","description":"Contact first name."},"contactSurname":{"type":"string","description":"Contact last name."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant to map your Submerchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"conversationId":{"type":"string","description":"Correlation id for request/response."}}},"SubmerchantPrivateCompanyRequest":{"description":"Private Company","type":"object","required":["subMerchantType","email","gsmNumber","address","taxOffice","legalCompanyTitle","subMerchantExternalId"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use \"PRIVATE_COMPANY\" for private companies."},"name":{"type":"string","description":"Submerchant name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone (E.164)."},"address":{"type":"string","description":"Submerchantt address."},"iban":{"type":"string","description":"Submerchant IBAN. Must match **legalCompanyTitle**. If not sent during creation, it must be provided before product approval for payouts.\n"},"taxOffice":{"type":"string","description":"Tax office."},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string","description":"Registered company title."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantLimitedJointRequest":{"description":"Limited/Joint-Stock Company","type":"object","required":["subMerchantType","email","gsmNumber","address","taxOffice","taxNumber","legalCompanyTitle","subMerchantExternalId"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use \"LIMITED_OR_JOINT_STOCK_COMPANY\" for LTD/JSC companies."},"name":{"type":"string","description":"Submerchant name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone."},"address":{"type":"string","description":"Submerchant address."},"iban":{"type":"string","description":"Submerchant IBAN. Must match **legalCompanyTitle**. If not sent during creation, it must be provided before product approval for payouts.\n"},"taxOffice":{"type":"string","description":"Tax office."},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string","description":"Registered company title."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantCreateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent in the request."},"subMerchantKey":{"type":"string","description":"Generated Submerchant key."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/create_sub_merchant.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/SubMerchantSample.java">Java</a></td></tr><tr><td></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L1185">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/tree/master/samples">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/folder/chsu7gd/1-1-create-submerchant">Postman</a></td></tr></tbody></table>


# Submerchant Update

This service allows you to update submerchant accounts by providing their necessary details.

{% hint style="info" %}
In the process of updating submerchants, it's important to note that you **cannot** change the submerchant type. Once a submerchant is created with a specific type, it cannot be modified to a different type. Therefore, it's crucial to ensure that the correct submerchant type is selected during the initial setup.
{% endhint %}

All of the submerchant types are capable of update operations;

* **PERSONAL**
* **PRIVATE COMPANY**
* **LIMITED OR JOINT STOCK COMPANY**

## Update Submerchant

> Updates an existing submerchant. The request body shape varies by submerchant type; \*\*one of three variants\*\* must be sent. The \*\*subMerchantType\*\* field is \*\*not\*\* included in the update body.<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant":{"put":{"summary":"Update Submerchant","description":"Updates an existing submerchant. The request body shape varies by submerchant type; **one of three variants** must be sent. The **subMerchantType** field is **not** included in the update body.\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantUpdateRequest":{"oneOf":[{"$ref":"#/components/schemas/SubmerchantPersonalUpdateRequest"},{"$ref":"#/components/schemas/SubmerchantPrivateCompanyUpdateRequest"},{"$ref":"#/components/schemas/SubmerchantLimitedJointUpdateRequest"}],"description":"Update fields vary by submerchant type. **Do not send subMerchantType** in update."},"SubmerchantPersonalUpdateRequest":{"description":"Personal Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","contactName","contactSurname","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string","description":"Store name."},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"contactName":{"type":"string"},"contactSurname":{"type":"string"},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"subMerchantKey":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantPrivateCompanyUpdateRequest":{"description":"Private Company Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","legalCompanyTitle","taxOffice","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"taxOffice":{"type":"string"},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string"},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"subMerchantKey":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantLimitedJointUpdateRequest":{"description":"Limited/Joint-Stock Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","legalCompanyTitle","taxOffice","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"taxOffice":{"type":"string"},"legalCompanyTitle":{"type":"string"},"taxNumber":{"type":"string","description":"Tax number."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"subMerchantKey":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent in the request."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/update_sub_merchant.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/SubMerchantSample.java#L111">Java</a></td></tr><tr><td><a href="http://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubMerchantSample.cs#L98">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L1250">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/tree/master/samples">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/folder/15x0r6x/1-2-update-submerchant">Postman</a></td></tr></tbody></table>


# Retrieve Submerchant

In the marketplace solution, you can use the following services to query the documents of your members.

## Get Submerchant Detail

> Returns submerchant details by external ID (\*\*subMerchantExternalId\*\*).

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant/detail":{"post":{"summary":"Get Submerchant Detail","description":"Returns submerchant details by external ID (**subMerchantExternalId**).","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantDetailRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantDetailRequest":{"type":"object","required":["subMerchantExternalId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"subMerchantExternalId":{"type":"string","description":"ExternalId of the submerchant to query."}}},"SubmerchantDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"bankCountry":{"type":"string"},"currency":{"type":"string"},"taxOffice":{"type":"string"},"legalCompanyTitle":{"type":"string"},"subMerchantExternalId":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"subMerchantType":{"type":"string"},"subMerchantKey":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/retrieve_sub_merchant.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/SubMerchantSample.java#L198">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubMerchantSample.cs#L182">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L1310">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/retrieve_sub_merchant.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/folder/x6mo1gg/1-3-retrieve-submerchant">Postman</a></td></tr></tbody></table>


# Submerchant Price / Item Update

Marketplace product offers;

* change the submerchant of the product in an order whose payment has been completed
* or update the amount to be transferred to the submerchant

with in the help of following API.

## Submerchant Item/Price Update

> This service is used to modify the payout amount of the submerchant or update the submerchant information based on a single paymentTransaction<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/item":{"put":{"summary":"Submerchant Item/Price Update","description":"This service is used to modify the payout amount of the submerchant or update the submerchant information based on a single paymentTransaction\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPayoutUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPayoutUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemPayoutUpdateRequest":{"type":"object","required":["paymentTransactionId","subMerchantPrice","subMerchantKey"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Payment split id."},"subMerchantKey":{"type":"string","description":"Submerchant key."},"subMerchantPrice":{"type":"number","description":"Amount to be transferred to the submerchant."}}},"ItemPayoutUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"itemId":{"type":"string"},"paymentTransactionId":{"type":"string"},"transactionStatus":{"type":"integer"},"price":{"type":"number"},"paidPrice":{"type":"number"},"merchantCommissionRate":{"type":"number"},"merchantCommissionRateAmount":{"type":"number"},"iyziCommissionRateAmount":{"type":"number"},"iyziCommissionFee":{"type":"number"},"blockageRate":{"type":"number"},"blockageRateAmountMerchant":{"type":"number"},"blockageRateAmountSubMerchant":{"type":"number"},"blockageResolvedDate":{"type":"string"},"subMerchantKey":{"type":"string"},"subMerchantPrice":{"type":"number"},"subMerchantPayoutRate":{"type":"number"},"subMerchantPayoutAmount":{"type":"number"},"merchantPayoutAmount":{"type":"number"},"convertedPayout":{"type":"object","properties":{"paidPrice":{"type":"number"},"iyziCommissionRateAmount":{"type":"number"},"iyziCommissionFee":{"type":"number"},"blockageRateAmountMerchant":{"type":"number"},"blockageRateAmountSubMerchant":{"type":"number"},"subMerchantPayoutAmount":{"type":"number"},"merchantPayoutAmount":{"type":"number"},"iyziConversionRate":{"type":"number"},"iyziConversionRateAmount":{"type":"number"},"currency":{"type":"string"}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/submerchant_payment_item_update.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/PaymentItemUpdateSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/PaymentItemSample.cs">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L1024">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/jh4wgb5/1-4-1-submerchant-item-update">Postman</a></td></tr></tbody></table>


# Online Payment

Marketplace product offer multiple online payment methods. Followings are 4 different payment methods;

### Payment Method Decision

<table data-card-size="large" data-view="cards"><thead><tr><th data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/vtS18CXkjJn7lSzez2Am">/pages/vtS18CXkjJn7lSzez2Am</a></td></tr><tr><td><a href="/pages/8w7DlEFOTrCcdOXOkx0y">/pages/8w7DlEFOTrCcdOXOkx0y</a></td></tr><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td></tr></tbody></table>

{% hint style="info" %}
If you also wish to sell as a submerchant or a marketplace owner, there are two methods available:

1. Either create a submerchant under your account and assign yourself to this submerchant as well as your products.
2. If you prefer to sell without creating a submerchant, you can use the `paymentGroup` parameter with the value `LISTING`. (Please note that when using this approach, the subMerchantKey parameter cannot be utilized.)
   {% endhint %}

After choosing one of the four payment types, you will need to include two additional parameters: **subMerchantKey** and **subMerchantPrice**. It is essential to assign these parameters to each product in the payment request.

<table><thead><tr><th width="194">Input Name</th><th width="77">Type</th><th width="115">Require</th><th>Description</th></tr></thead><tbody><tr><td><strong>subMerchantKey</strong></td><td>string</td><td>yes</td><td>Returned value from submerchant create request</td></tr><tr><td><strong>subMerchantPrice</strong></td><td>string</td><td>yes</td><td>Amount that needs to be transferred for sub merchant</td></tr></tbody></table>

## Marketplace Payment (Non3D)

> Example shows the \*\*Non3D\*\* method. In a marketplace flow, each basket split \*\*must\*\*\
> include sub-merchant fields.<br>

```json
{"openapi":"3.0.3","info":{"title":"Non3D Payment (Marketplace)","version":"1.0.4"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/auth":{"post":{"summary":"Marketplace Payment (Non3D)","description":"Example shows the **Non3D** method. In a marketplace flow, each basket split **must**\ninclude sub-merchant fields.\n","tags":["Payment Methods"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Non3DMarketplaceRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Non3DMarketplaceResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"Non3DMarketplaceRequest":{"type":"object","required":["price","paidPrice","shippingAddress","billingAddress","paymentCard","basketItems","buyer"],"description":"Non3D payment request. In the marketplace model, each basket split **must** include\nsub-merchant fields.\n","properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"conversationId":{"type":"string","description":"Correlation value that is echoed back in the response."},"price":{"type":"decimal","description":"Basket (cart) total. **Sum of basket item prices must equal `price`.**"},"paidPrice":{"type":"decimal","description":"Final amount to be charged at POS; can be less than, greater than, or equal to `price`."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP"],"description":"Payment currency (default TRY)."},"installment":{"type":"integer","enum":[1,2,3,6,9,12],"description":"Installment count. Default; 1"},"paymentChannel":{"type":"string","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"],"description":"Payment channel. Default; \"WEB\""},"basketId":{"type":"string","description":"Basket/order identifier on the merchant side."},"paymentGroup":{"type":"string","enum":["PRODUCT","LISTING","SUBSCRIPTION","OTHER"],"description":"Payment group."},"paymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireMonth","expireYear","cvc"],"description":"Card details.","properties":{"cardHolderName":{"type":"string","description":"Name on card."},"cardNumber":{"type":"string","description":"PAN."},"expireYear":{"type":"string","description":"Expiration year (YYYY)."},"expireMonth":{"type":"string","description":"Expiration month (MM)."},"cvc":{"type":"string","description":"Security code."},"registerCard":{"type":"integer","enum":[0,1],"description":"Send 1 to store the card (card storage feature must be enabled)."}}},"buyer":{"type":"object","description":"Buyer information.","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Merchant-side user ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID (TR)."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"GSM number (prefer E.164)."},"registrationDate":{"type":"string","description":"Registration date."},"lastLoginDate":{"type":"string","description":"Last login date."},"registrationAddress":{"type":"string","description":"Registration address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"ip":{"type":"string","description":"Client IP address."}}},"shippingAddress":{"$ref":"#/components/schemas/Address"},"billingAddress":{"$ref":"#/components/schemas/BillingAddress"},"basketItems":{"type":"array","minItems":1,"description":"Basket items. **For marketplace**, sub-merchant fields are required.","items":{"$ref":"#/components/schemas/BasketItemMarketplace"}}}},"Address":{"type":"object","description":"Shipping Address. Required if at least one basket item has itemType = \"PHYSICAL\". Not required if all items are \"VIRTUAL\".\n","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BillingAddress":{"type":"object","description":"Billing Address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItemMarketplace":{"type":"object","description":"Basket item definition for marketplace payments.","required":["id","price","name","category1","itemType","subMerchantKey","subMerchantPrice"],"properties":{"id":{"type":"string","description":"Item ID per split on merchant side."},"name":{"type":"string","description":"Split name."},"price":{"type":"decimal","description":"Split amount; cannot be 0. Sum of splits must equal `price` (basket total)."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category."},"itemType":{"type":"string","enum":["PHYSICAL","VIRTUAL"],"description":"Item type."},"subMerchantKey":{"type":"string","description":"Sub-merchant **key** (required for marketplace)."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant’s payable amount (required for marketplace)."},"withholdingTax":{"type":"decimal","description":"Withholding tax amount. If the marketplace withholds tax from the sub-merchant payout and wants it to appear in the payment result and **Payout Report**, `withholdingTax` must be sent. (Recorded for information only; iyzico does not calculate it.)\n"}}},"Non3DMarketplaceResponse":{"type":"object","description":"Successful Non3D payment response.","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID."},"price":{"type":"decimal","description":"Basket total."},"paidPrice":{"type":"decimal","description":"Charged total amount (via POS)."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"iyzico payment ID."},"fraudStatus":{"type":"integer","enum":[0,-1,1],"description":"Fraud filter result:\n- **1**: Approved — merchant may proceed (ship).\n- **0**: Under review — wait for a later notification.\n- **-1**: Rejected.\n"},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fixed fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme."},"cardFamily":{"type":"string","description":"Card family/brand."},"binNumber":{"type":"string","description":"First 6 digits of the card."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency."},"itemTransactions":{"type":"array","description":"Per-item split results.","items":{"type":"object","properties":{"itemId":{"type":"string","description":"Split ID."},"paymentTransactionId":{"type":"string","description":"Split transaction ID."},"transactionStatus":{"type":"integer","enum":[0,-1,1,2],"description":"Split status:\n- **0**: In fraud check\n- **-1**: Rejected after fraud check\n- **1**: Approved (**Marketplace meaning:** Waiting for merchant approval)\n- **2**: Approved (**Marketplace meaning:** Merchant-approved)\n"},"price":{"type":"decimal","description":"Split amount."},"paidPrice":{"type":"decimal","description":"Charged amount for the split."},"merchantCommissionRate":{"type":"decimal","description":"Merchant commission rate on split."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant commission amount on split."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount on split."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fixed fee on split."},"blockageRate":{"type":"integer","description":"Blockage rate."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant blockage amount."},"blockageRateAmountSubMerchant":{"type":"decimal","description":"Sub-merchant blockage amount."},"withholdingTax":{"type":"decimal","description":"Withholding tax amount."},"blockageResolvedDate":{"type":"string","description":"Blockage resolve date (YYYY-MM-DD hh:mm:ss)."},"subMerchantKey":{"type":"string","description":"Sub-merchant key."},"externalSubMerchantId":{"type":"string","description":"Merchant’s external ID for the sub-merchant."},"subMerchantPrice":{"type":"decimal","description":"Amount payable to the sub-merchant."},"subMerchantPayoutRate":{"type":"decimal","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to sub-merchant."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to merchant."},"convertedPayout":{"type":"object","description":"Summary (in converted currency).","properties":{"paidPrice":{"type":"decimal","description":"Charged amount (converted)."},"iyziCommissionRateAmount":{"type":"decimal","description":"Commission rate amount (converted)."},"iyziCommissionFee":{"type":"decimal","description":"Fixed commission (converted)."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant blockage (converted)."},"blockageRateAmountSubMerchant":{"type":"decimal","description":"Sub-merchant blockage (converted)."},"subMerchantPayoutAmount":{"type":"decimal","description":"Sub-merchant payable (converted)."},"merchantPayoutAmount":{"type":"decimal","description":"Merchant payable (converted)."},"iyziConversionRate":{"type":"decimal","description":"FX conversion rate."},"iyziConversionRateAmount":{"type":"decimal","description":"FX conversion amount."},"currency":{"type":"string","description":"Converted currency."}}}}}},"authCode":{"type":"string","description":"Bank authorization code."},"phase":{"type":"string","description":"Transaction phase (AUTH/PREAUTH etc.)."},"hostReference":{"type":"string","description":"Host reference."},"signature":{"type":"string","description":"Response signature (for verification)."}}},"ErrorResponse":{"type":"object","description":"Error response.","properties":{"status":{"type":"string","enum":["failure"],"description":"Operation result."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/create_marketplace_payment.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/PaymentSample.java#L128">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/PaymentSample.cs#L206">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L653">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/create_marketplace_payment.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/folder/m5s7knc/1-2-create-marketplace-payment">Postman</a></td></tr></tbody></table>


# Approval

PRODUCTS

In the marketplace solution, once the payment has been processed by iyzico, the funds are securely held in a protected pool until the submerchant grants approval for the payment breakdown or specific product. During this period, the submerchant has the flexibility to cancel the payment, issue a refund for a particular item, or provide approval for the fund transfer if the product has been successfully delivered to the buyer and the transaction has been completed without any issues. Additionally, the submerchant can withdraw their approval for the transaction if necessary.&#x20;

For such usages iyzico offers 2 ways of finalize the payment;

* [Approve](#approve)
* [Disapprove](#disapprove)

{% hint style="info" %}
Please note that iyzico does not have the capability to grant product approvals. Since there is no corresponding function available in the control panel, these approvals must be sent programmatically at the code level.
{% endhint %}

## Approve Item

> To approve an item, provide the split id (\*\*paymentTransactionId\*\*). The id is returned by the payment service.

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/item/approve":{"post":{"summary":"Approve Item","description":"To approve an item, provide the split id (**paymentTransactionId**). The id is returned by the payment service.","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemApproveRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemActionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemApproveRequest":{"type":"object","required":["paymentTransactionId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Split id to be approved."}}},"ItemActionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/approve.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/ApproveSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/ApproveSample.cs">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L38">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/approve.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/ic384ys/1-3-1-approve-payment">Postman</a></td></tr></tbody></table>

## Dissapprove

> To disapprove a product, the related paymentTransactionId must be provided in the request. The id (paymentTransactionId) of the disapproved payment transaction will be returned in the response.

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/iyzipos/item/disapprove":{"post":{"summary":"Dissapprove","description":"To disapprove a product, the related paymentTransactionId must be provided in the request. The id (paymentTransactionId) of the disapproved payment transaction will be returned in the response.","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemDisapproveRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemActionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemDisapproveRequest":{"type":"object","required":["paymentTransactionId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Split id whose approval will be revoked."}}},"ItemActionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/disapprove.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/DisapproveSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/DisapproveSample.cs">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySamples.js#L52">Node.Js</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/disapprove.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/h2qa3i2/1-3-2-disapprove-payment">Postman</a></td></tr></tbody></table>


# Subscription

{% embed url="<https://www.youtube.com/watch?v=TAAlKATYiXg>" %}

Subscription product offers the ability to quickly create subscriptions for online payment-enabled merchant members. It allows for receiving recurring payments without the need for additional resources and development processes such as card storage and payment tracking. If your business model is suitable for recurring payments, such as offering premium, gold membership services, gym services, magazine subscriptions, etc., the subscription API provides you with a fast and reliable solution

{% hint style="info" %}
Subscription product subjects to a fee. It is free for the first 3 months, and after that, it is priced at 199TL. If you want to use Subscription product, you can quickly purchase it from the 'Add-ons' section in your iyzico panel.
{% endhint %}

### How Does the iyzico Subscription Method Work?

With Subscription product, businesses can offer their customers various payment plans, including daily, weekly, monthly, yearly, and many other options. Payment plans can be easily defined both through the iyzico Control Panel and via the API.

Member businesses that wish to receive payments using the Subscription product can start receiving regular payments after a single integration and can track all their transactions through the iyzico Control Panel.

Another feature of the Subscription Method is the trial period that can be added to a payment plan. This allows for a trial period to be defined for any payment plan. Since credit card information is stored at the beginning of the trial period, the subscription automatically starts at the end of the defined trial period.

<div><figure><img src="/files/hlZQa7geaa0D4Ji9l2Tw" alt=""><figcaption></figcaption></figure> <figure><img src="/files/tT4zlMYT5W3zVcbi4uWM" alt=""><figcaption></figcaption></figure> <figure><img src="/files/KGjXBPxce4zNYhqahWrY" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/93N7Fm24bSehFZhv69a4" alt=""><figcaption></figcaption></figure> <figure><img src="/files/RZyNLA99MROTzaq1G4Y3" alt=""><figcaption></figcaption></figure> <figure><img src="/files/GyFFhBkGGm097d7eVmFR" alt=""><figcaption></figcaption></figure></div>


# Subscription Implementation

<figure><img src="/files/V5NsaN9BD7ZlFkR92rTX" alt=""><figcaption></figcaption></figure>

### Steps

Subscription product consists of four main steps; the steps are as follows:

1. [Product Creation](/en/products/subscription/subscription-implementation/subscription-product#create-product)
2. [Payment Plan Creation](/en/products/subscription/subscription-implementation/payment-plan#create-payment-plan)
3. [Subscription](/en/products/subscription/subscription-implementation/subscription-transactions#initialize-subscription)
4. [Webhook](/en/advanced/webhook#subscription-format)

{% hint style="info" %}
**Subscription can only be used with credit cards.**
{% endhint %}

For example, if you want to initiate a subscription process for two different magazines you publish, you simply need to create two products, A Magazine and B Magazine, and create payment plans based on the publication frequency of the magazines. Assuming that A Magazine is published every month and B Magazine is published every week, you can set the plan for A Magazine at 50 TL per month and the plan for B Magazine at 30 TL per week. iyzico provides you with a reference code for each plan. Sending this reference code in a payment request is sufficient to subscribe the end user to that specific plan.

Products and plans can be created, updated, or deleted in seconds through the iyzico merchant panel or API requests. To initiate a subscription, a payment request must be sent via the API. Payment can be made through a checkout form or directly via API request.


# Subscription Product

The subscription primarily built around plans, and plans must be associated with products. To create a product, it is sufficient to provide only the name parameter.

A product can have multiple payment plans, and it is possible to perform all these operations both through the API and the iyzico merchant panel.

The product name is a unique value, and it is possible to create unlimited products that will be distinct from each other.

There are five different methods that can be used on products.

1. [Create Product](#post-v2-subscription-products)
2. [Update Product](#post-v2-subscription-products-productreferencecode)
3. [Get Product](#get-v2-subscription-products-productreferencecode)
4. [List Products](#get-v2-subscription-products)
5. [Delete Product](#delete-v2-subscription-products-productreferencecode)

{% hint style="info" %}
A product can be deleted only if it does not have an associated plan. If a product associated with a plan needs to be deleted, the associated plan must be deleted first.
{% endhint %}

## Create Product

> Creates a new subscription product. The Subscription API charges on a recurring basis according to pricing plans, and each plan is linked to at least one product. There is no limit on the number of products; a product can be created by providing only a name.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products":{"post":{"summary":"Create Product","operationId":"createSubscriptionProduct","description":"Creates a new subscription product. The Subscription API charges on a recurring basis according to pricing plans, and each plan is linked to at least one product. There is no limit on the number of products; a product can be created by providing only a name.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductCreateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductCreateSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductCreateRequest":{"type":"object","properties":{"locale":{"type":"string","description":"Language of iyzico response messages. Default **en**; **tr** is supported."},"conversationId":{"type":"string","description":"A reference value that can be used to match request and response."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."}},"required":["name"]},"SubscriptionProductCreateSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"$ref":"#/components/schemas/ProductResource"}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_product.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionProductSample.java#L18">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionProductSample.cs#L13">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L16">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/85w60e9/1-1-create-product">Postman</a></td></tr></tbody></table>

## Update Product

> Updates a subscription product. Product name and description can be edited via API or the iyzico merchant panel. Use the product’s unique reference code for API updates.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}":{"post":{"summary":"Update Product","operationId":"updateSubscriptionProduct","description":"Updates a subscription product. Product name and description can be edited via API or the iyzico merchant panel. Use the product’s unique reference code for API updates.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Unique reference code of the product."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductGetSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductUpdateRequest":{"type":"object","properties":{"locale":{"type":"string","description":"Response language (**en**/**tr**)."},"conversationId":{"type":"string","description":"Value used for request/response matching."},"name":{"type":"string","description":"New product name."},"description":{"type":"string","description":"New product description."}},"required":["name"]},"SubscriptionProductGetSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"$ref":"#/components/schemas/ProductResource"}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/update_product.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionProductSample.java#L36">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionProductSample.cs#L36">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L32">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/3l501m2/1-4-update-product">Postman</a></td></tr></tbody></table>

## Get Product

> Retrieves details of a single product. Provide the product reference code in the request.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}":{"get":{"summary":"Get Product","operationId":"getSubscriptionProduct","description":"Retrieves details of a single product. Provide the product reference code in the request.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Unique reference code of the product."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductGetSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductGetSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"$ref":"#/components/schemas/ProductResource"}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_product.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionProductSample.java#L54">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionProductSample.cs#L78">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L58">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/5jm9v3w/1-3-retrieve-product">Postman</a></td></tr></tbody></table>

## List Products

> Lists subscription products. Use this to fetch all products and their linked plans. To reduce latency and payload size, pagination is used so you can retrieve the product list page by page.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products":{"get":{"summary":"List Products","operationId":"listSubscriptionProducts","description":"Lists subscription products. Use this to fetch all products and their linked plans. To reduce latency and payload size, pagination is used so you can retrieve the product list page by page.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductListRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductListSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductListRequest":{"type":"object","properties":{"page":{"type":"integer","description":"Returns products for the specified page."},"count":{"type":"integer","description":"Number of products per page."}}},"SubscriptionProductListSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","description":"Pagination results.","properties":{"totalCount":{"type":"string","description":"Total number of results returned."},"currentPage":{"type":"integer","description":"Page number returned."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Product list.","items":{"$ref":"#/components/schemas/ProductResource"}}}}}},"ProductResource":{"type":"object","description":"Product details.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the product."},"createdDate":{"type":"string","description":"Product creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"status":{"type":"string","description":"Product status (default ACTIVE)."},"pricingPlans":{"type":"array","description":"List of plans linked to the product.","items":{"$ref":"#/components/schemas/PricingPlanBrief"}}}},"PricingPlanBrief":{"type":"object","description":"Summary view of the plan linked to the product.","properties":{"referenceCode":{"type":"string","description":"Unique reference code of the plan."},"createdDate":{"type":"string","description":"Plan creation date (`YYYY-MM-DD hh:mm:ss`)."},"name":{"type":"string","description":"Plan name."},"price":{"type":"decimal","description":"Plan price (Decimal)."},"paymentInterval":{"type":"string","enum":["WEEKLY","MONTHLY","DAILY","YEARLY"],"description":"Payment frequency."},"paymentIntervalCount":{"type":"integer","description":"Number of repeats for the payment interval."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"currencyCode":{"type":"string","description":"Currency (e.g., TRY)."},"productReferenceCode":{"type":"string","description":"Reference code of the product the plan belongs to."},"planPaymentType":{"type":"string","description":"Plan payment type (RECURRING)."},"status":{"type":"string","description":"Plan status (e.g., ACTIVE)."},"recurrenceCount":{"type":"integer","description":"Total number of recurrences (if any)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/list_products.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionProductListSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionProductSample.cs#L98">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L69">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/227m43b/1-2-list-products">Postman</a></td></tr></tbody></table>

## Delete Product

> Deletes a subscription product. Products can be deleted via API or the iyzico merchant panel only when there are no plans linked to the product.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Product","version":"1.0.0"},"tags":[{"name":"Subscription Product","description":"Subscription product management services."}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}":{"delete":{"summary":"Delete Product","operationId":"deleteSubscriptionProduct","description":"Deletes a subscription product. Products can be deleted via API or the iyzico merchant panel only when there are no plans linked to the product.","tags":["Subscription Product"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Unique reference code of the product."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionProductDeleteSuccess"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content type of the request body.","schema":{"type":"string"}}},"schemas":{"SubscriptionProductDeleteSuccess":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/delete_product.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionProductSample.java#L61">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionProductSample.cs#L60">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L47">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/47010871-0a348c6b-e48b-4c6e-9511-ca8992041cb6?tab=overview">Postman</a></td></tr></tbody></table>


# Payment Plan

The subscription system operates by default according to the specified plan. The payment plan is the step where all the necessary features for recurring payments are specified.

Plans have unique names, and one plan can only be associated with one product. If a plan is actively linked to a subscription, it cannot be deleted.

There are five different methods that can be used on plans.

1. [Create Payment Plan](#post-v2-subscription-products-productreferencecode-pricing-plans)
2. [Update Payment Plan](#post-v2-subscription-pricing-plans-pricingplanreferencecode)
3. [List Pricing Plans](#get-v2-subscription-products-productreferencecode-pricing-plans)
4. [Get Payment Plan Detail](#get-v2-subscription-pricing-plans-pricingplanreferencecode)
5. [Delete Payment Plan](#delete-v2-subscription-pricing-plans-pricingplanreferencecode)

### Create Payment Plan

To create a plan, the following details must be provided: product reference number, name, price, currency, payment interval, and other parameters as detailed below.

If a trial period is desired for a subscription, the trialPeriodDays parameter can be used. If this parameter is sent, no subscription will be initiated and no payment will be collected from the card during the specified period.

The Payment Interval parameter specified in the request indicates the payment period. When sending the "WEEKLY" parameter when creating a plan, iyzico will deduct the specified amount from the card every week. Customizing this period is also possible. For example, if you want payments to be collected every 2 weeks, you should send the PaymentInterval value as "WEEKLY" and the paymentIntervalCount value as 2.

{% hint style="info" %}
The planPaymentType parameter is mandatory and can currently only take the value RECURRING.
{% endhint %}

## Create Pricing Plan

> Creates a new pricing plan for a specific product.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}/pricing-plans":{"post":{"summary":"Create Pricing Plan","description":"Creates a new pricing plan for a specific product.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the product the plan will be attached to."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePricingPlanRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"CreatePricingPlanRequest":{"type":"object","required":["name","price","currencyCode","paymentInterval","planPaymentType"],"properties":{"name":{"type":"string","description":"Pricing plan name."},"price":{"type":"decimal","description":"Amount to charge on each billing period."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency. (For foreign currency, only non-TRY cards are allowed.)"},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Recurrence interval for the subscription charge."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"paymentIntervalCount":{"type":"integer","description":"Frequency multiplier for the interval. For example, if you set a weekly plan and send **2**, the charge occurs every 2 weeks."},"recurrenceCount":{"type":"integer","description":"Total number of repeats (e.g., **12** → 12 months). If omitted, it continues until the subscription is canceled."},"trialPeriodDays":{"type":"integer","description":"Free trial length in days. If provided, the first charge happens after this period."},"locale":{"type":"string","enum":["tr","en"],"description":"Language of the response and error messages."},"conversationId":{"type":"string","description":"Custom identifier for request tracking."}}},"CreatePricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the operation."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Plan name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"price":{"type":"decimal","description":"Subscription price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"recurrenceCount":{"type":"integer","description":"Number of repeats."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_pricing_plan.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionPricingPlanSample.java#L23">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionPlanSample.cs#L13">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L85">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/uxl6d4z/2-1-create-pricing-plan">Postman</a></td></tr></tbody></table>

## Update Pricing Plan

> This method allows updating \*\*only\*\* the \*\*name\*\* and \*\*trialPeriodDays\*\* fields.   The plan's reference code must be provided as a path parameter.   Updates can be performed via API or the iyzico merchant panel. Active subscriptions are not affected.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/pricing-plans/{pricingPlanReferenceCode}":{"post":{"summary":"Update Pricing Plan","description":"This method allows updating **only** the **name** and **trialPeriodDays** fields.   The plan's reference code must be provided as a path parameter.   Updates can be performed via API or the iyzico merchant panel. Active subscriptions are not affected.\n","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"pricingPlanReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the pricing plan to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePricingPlanRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"UpdatePricingPlanRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Updated plan name."},"trialPeriodDays":{"type":"integer","description":"Updated trial period (days)."}}},"UpdatePricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the operation."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the updated plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Updated plan name."},"price":{"type":"decimal","description":"Plan price."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"trialPeriodDays":{"type":"integer","description":"Updated trial period (days)."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"productReferenceCode":{"type":"string","description":"Product reference code."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."},"recurrenceCount":{"type":"integer","description":"Number of repeats."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/update_pricing_plan.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionPricingPlanSample.java#L53">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionPlanSample.cs#L51">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L107">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/8h7wmj4/2-2-update-pricing-plan">Postman</a></td></tr></tbody></table>

## List Pricing Plans

> Lists all pricing plans for a given product. The response is paginated.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/products/{productReferenceCode}/pricing-plans":{"get":{"summary":"List Pricing Plans","description":"Lists all pricing plans for a given product. The response is paginated.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"productReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Product reference code."},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number to list."},{"name":"count","in":"query","schema":{"type":"integer"},"description":"Number of records per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"ListPricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"},"data":{"type":"object","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer"},"pageCount":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatePricingPlanResponse/properties/data"}}}}}},"CreatePricingPlanResponse":{"properties":{"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Plan name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"price":{"type":"decimal","description":"Subscription price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"recurrenceCount":{"type":"integer","description":"Number of repeats."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/list_pricing_plan.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionPricingPlanListSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionPlanSample.cs#L116">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L144">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/mfeq6b3/2-4-list-pricing-plans">Postman</a></td></tr></tbody></table>

## Get Pricing Plan Detail

> Returns details of a pricing plan. Merchants can see all details both in the merchant panel and via API.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/pricing-plans/{pricingPlanReferenceCode}":{"get":{"summary":"Get Pricing Plan Detail","description":"Returns details of a pricing plan. Merchants can see all details both in the merchant panel and via API.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"pricingPlanReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Pricing plan reference code."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingPlanDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"PricingPlanDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"},"data":{"$ref":"#/components/schemas/CreatePricingPlanResponse/properties/data"}}},"CreatePricingPlanResponse":{"properties":{"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created plan."},"createdDate":{"type":"integer","description":"Plan creation time (epoch ms)."},"name":{"type":"string","description":"Plan name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"price":{"type":"decimal","description":"Subscription price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency code."},"paymentInterval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","YEARLY"],"description":"Billing interval."},"paymentIntervalCount":{"type":"integer","description":"Interval multiplier."},"planPaymentType":{"type":"string","enum":["RECURRING"],"description":"Subscription type."},"recurrenceCount":{"type":"integer","description":"Number of repeats."},"trialPeriodDays":{"type":"integer","description":"Trial period (days)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Plan status."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_pricing_plan.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionPricingPlanSample.java#L76">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionPlanSample.cs#L95">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L133">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/q6nanss/2-3-retrieve-pricing-plan">Postman</a></td></tr></tbody></table>

## Delete Pricing Plan

> Deletes the specified pricing plan by reference code. Plans with active subscriptions or pending updates cannot be deleted.

```json
{"openapi":"3.0.3","info":{"title":"Subscription Pricing Plan","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/pricing-plans/{pricingPlanReferenceCode}":{"delete":{"summary":"Delete Pricing Plan","description":"Deletes the specified pricing plan by reference code. Plans with active subscriptions or pending updates cannot be deleted.","tags":["Pricing Plan"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"pricingPlanReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the pricing plan to delete."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePricingPlanResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Format of the request payload."}},"schemas":{"DeletePricingPlanResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"systemTime":{"type":"integer"}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/delete_pricing_plan.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionPricingPlanSample.java#L84">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionPlanSample.cs#L77">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L122">Node.Js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/47010871-a51b486e-7872-43e7-92fe-d23678600f86">Postman</a></td></tr></tbody></table>


# Subscription Transactions

The services included in the subscription transactions are listed below.

1. [Initialize Subscription](#initialize-subscription)
2. [Activate Subscription](#post-v2-subscription-subscriptions-subscriptionreferencecode-activate)
3. [Retry Subscription Payment](#post-v2-subscription-operation-retry)
4. [Upgrade Subscription](#post-v2-subscription-subscriptions-subscriptionreferencecode-upgrade)
5. [Cancel Subscription](#post-v2-subscription-subscriptions-subscriptionreferencecode-cancel)
6. [Get Subscription Details](#get-v2-subscription-subscriptions-subscriptionreferencecode)
7. [Search Subcriptions](#get-v2-subscription-subscriptions)
8. [Subscription Card Update](#post-v2-subscription-card-update-checkoutform-initialize)

### Initialize Subscription

If you have completed all the steps, you can now start the subscription process.

Subscription can be started in 2 different ways.

1. [Checkout Form](#initializing-subscription-via-checkout-form)
2. [NON-3DS](#post-v2-subscription-initialize)

Both methods above give the same result, but there is a difference in the way they are used.&#x20;

The subscription process always starts with an ACTIVE or PENDING status. If the status is PENDING or the status is ACTIVE but a trial period is specified in the payment plan, iyzico only validates the card in the subscription request. Card validation takes place with a 1 TL withdrawal and subsequent refund. Apart from this, no transaction or payment takes place.&#x20;

If the subscription status is ACTIVE and no trial period is specified in the planning, the payment specified in the plan is taken from the card and the subscription is started.&#x20;

Each subscription requires a card information. Your customers can start a subscription with the cards they have stored in the iyzico environment or with a new card. When requesting a card update, the `subscriptionReferenceCode` of the relevant subscription must be sent. In this case, only the card information of the relevant subscription will be updated.

#### Table of Subscription Status

<table><thead><tr><th width="140">DURUMU</th><th>AÇIKLAMA</th></tr></thead><tbody><tr><td><strong>ACTIVE</strong></td><td>Bir abonelik aktif ise ve ödemeler düzenli olarak alınıyorsa status active olur.</td></tr><tr><td><strong>PENDING</strong></td><td>Bir abonelik durdurulmuşsa status pending olur.</td></tr><tr><td><strong>UNPAID</strong></td><td>Abonelik sırasında ödeme alınamamış ise status unpaid olur.</td></tr><tr><td><strong>UPGRADED</strong></td><td>Abonelik başka bir plan ile güncellenmişse status upgraded olur.</td></tr><tr><td><strong>CANCELED</strong> </td><td>Abonelik iptal edilmişse status cancelled olur.</td></tr><tr><td><strong>EXPIRED</strong></td><td>Abonelik periyodu bitmişse status expired olur. Karttan başka bir ödeme alınmaz.</td></tr></tbody></table>

#### Initializing Subscription via Checkout Form

To create a checkout form, merchants must submit the following information.&#x20;

* Payment Plan Reference Code
* Customer information
* Subscription Status
* CallBackURL (the address where the Checkout Form result will be posted)

`CallBackUrl` is given by member merchants during the request and determines the page to which the end user will be directed after payment. Redirection occurs as soon as the customer makes the payment. At this point, the payment request was sent to the bank and the result was processed by iyzico. The member business must check whether the payment has been received with a separate request. If the card validation or first payment is successful, all other processes are carried out by iyzico.

{% hint style="info" %}
If your customer has a card stored in the iyzico environment, the option to pay with a stored card will appear on the checkout form. In this case, our member businesses do not need to send an additional request.
{% endhint %}

Via iyzico Checkout Form, an `htmlContent` parameter is returned as a result of the form creation request. When this javascript code snippet is printed on the page, the iyzico library is ready to be loaded into any of the “divs” mentioned below. The checkout form will appear when the page is completely loaded.

The divs where the checkout form will be loaded can be responsive or popup. Examples are given below.

```html
<div id="iyzipay-checkout-form" class="responsive"></div>
```

```html
<div id="iyzipay-checkout-form" class="popup"></div>
```

## Initialize Subscription (iyzico Checkout Form)

> Used to start a subscription with iyzico Checkout Form. Returns the form content and token.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/checkoutform/initialize":{"post":{"summary":"Initialize Subscription (iyzico Checkout Form)","description":"Used to start a subscription with iyzico Checkout Form. Returns the form content and token.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormInitializeRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormInitializeResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionCheckoutFormInitializeRequest":{"type":"object","required":["callbackUrl","pricingPlanReferenceCode","subscriptionInitialStatus","customer"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`. Send `\"en\"` to create the checkout form in English.","enum":["tr","en"]},"callbackUrl":{"type":"string","description":"Callback URL to which the payment result will be sent."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"conversationId":{"type":"string","description":"Optional correlation value to match request/response pairs."},"customer":{"$ref":"#/components/schemas/SubscriptionCustomer"}}},"SubscriptionCustomer":{"description":"Buyer information.","type":"object","required":["name","surname","email","gsmNumber","identityNumber","billingAddress"],"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer E.164 when possible (e.g., +905555555555)."},"identityNumber":{"type":"string","description":"National ID (string)."},"billingAddress":{"$ref":"#/components/schemas/SubscriptionBillingAddress"},"shippingAddress":{"$ref":"#/components/schemas/SubscriptionShippingAddress"}}},"SubscriptionBillingAddress":{"type":"object","description":"Billing address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Billing address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"SubscriptionShippingAddress":{"type":"object","description":"Shipping address.","properties":{"address":{"type":"string","description":"Shipping address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"StartSubscriptionCheckoutFormInitializeResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Echoes the value you sent in the request."},"token":{"type":"string","description":"Token of the checkout form."},"checkoutFormContent":{"type":"string","description":"HTML content of the checkout form."},"tokenExpireTime":{"type":"integer","description":"Token validity time in seconds."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_subscription_with_checkout_form.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCheckoutFormInitializeSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L14">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L377">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/luswnz6/3-1-1-1-initialize-checkoutform">Postman</a></td></tr></tbody></table>

## Initialize Subscription (NON3D)

> Start a subscription without the hosted checkout form, using your own payment form via NON3D service.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/initialize":{"post":{"summary":"Initialize Subscription (NON3D)","description":"Start a subscription without the hosted checkout form, using your own payment form via NON3D service.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionNon3DRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionNon3DResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionNon3DRequest":{"type":"object","required":["pricingPlanReferenceCode","customer","paymentCard","subscriptionInitialStatus"],"properties":{"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"conversationId":{"type":"string","description":"Optional correlation value to match request/response pairs."},"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"customer":{"$ref":"#/components/schemas/SubscriptionCustomer"},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard"}}},"SubscriptionCustomer":{"description":"Buyer information.","type":"object","required":["name","surname","email","gsmNumber","identityNumber","billingAddress"],"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer E.164 when possible (e.g., +905555555555)."},"identityNumber":{"type":"string","description":"National ID (string)."},"billingAddress":{"$ref":"#/components/schemas/SubscriptionBillingAddress"},"shippingAddress":{"$ref":"#/components/schemas/SubscriptionShippingAddress"}}},"SubscriptionBillingAddress":{"type":"object","description":"Billing address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Billing address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"SubscriptionShippingAddress":{"type":"object","description":"Shipping address.","properties":{"address":{"type":"string","description":"Shipping address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"PaymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireMonth","expireYear","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder name."},"cardNumber":{"type":"string","description":"Card number."},"expireMonth":{"type":"string","description":"Expiry month."},"expireYear":{"type":"string","description":"Expiry year."},"cvc":{"type":"string","description":"CVC/CVV."}}},"StartSubscriptionNon3DResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the request result; `success` if the operation succeeded."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Unique code used to match updates on the merchant side."},"customerReferenceCode":{"type":"string","description":"Unique customer code created from user info (based on email and gsmNumber)."},"subscriptionStatus":{"type":"string","description":"Subscription status.","enum":["ACTIVE","PENDING"]},"pricingPlanReferenceCode":{"type":"string"},"trialDays":{"type":"integer","description":"Trial period defined in the plan."},"trialStartDate":{"type":"integer","description":"Start time of the trial period (epoch ms)."},"trialEndDate":{"type":"integer","description":"End time of the trial period (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_subscription_api.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionInitializeSample.java#L22">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L62">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L426">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/iag178u/3-1-2-1-initialize-subscription-payment">Postman</a></td></tr></tbody></table>

## Retrieve Checkout Form Result

> After the checkout form flow completes, query the subscription creation result with the returned token.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/checkoutform/{token}":{"get":{"summary":"Retrieve Checkout Form Result","description":"After the checkout form flow completes, query the subscription creation result with the returned token.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token returned by checkout form initialize for this operation."},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional correlation value you send in the request to match with the response."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormResultResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionCheckoutFormResultResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."},"conversationId":{"type":"string","description":"Echoes the value you sent in the request."},"token":{"type":"string","description":"Token of the checkout form."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Unique code used to match updates on the merchant side."},"customerReferenceCode":{"type":"string","description":"Unique customer code created from user info (based on email and gsmNumber)."},"subscriptionStatus":{"type":"string","description":"Subscription status.","enum":["ACTIVE","PENDING"]},"pricingPlanReferenceCode":{"type":"string"},"trialDays":{"type":"integer","description":"Trial period defined in the plan. No charge during this period."},"trialStartDate":{"type":"integer","description":"Start time of the trial period (epoch ms)."},"trialEndDate":{"type":"integer","description":"End time of the trial period (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_subscription_checkout_form_result.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCheckoutFormSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L415">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/fdkvoby/3-1-1-2-retrieve-subscription-after-completed-checkoutform">Postman</a></td></tr></tbody></table>

## Initialize Subscription (Existing Customer)

> If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/initialize/with-customer":{"post":{"summary":"Initialize Subscription (Existing Customer)","description":"If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionWithCustomerRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionWithCustomerResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionWithCustomerRequest":{"type":"object","required":["subscriptionInitialStatus","pricingPlanReferenceCode","customerReferenceCode"],"properties":{"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"customerReferenceCode":{"type":"string","description":"Reference code of the existing customer. Must already have an active subscription to start a new one with this flow."}}},"StartSubscriptionWithCustomerResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Reference code to correlate subscription updates on the merchant side."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan linked to the created subscription."},"customerReferenceCode":{"type":"string","description":"Reference code of the related customer."},"subscriptionStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Subscription status."},"trialDays":{"type":"integer","description":"Trial period (days)."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"startDate":{"type":"integer","description":"Start time (epoch ms)."},"endDate":{"type":"integer","description":"End time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_subscription_with_customer_reference_code.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionInitializeSample.java#L75">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L516">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/224cvf3/3-1-2-2-initialize-subscription-payment-for-existing-customer">Postman</a></td></tr></tbody></table>

## Activate Subscription

> A subscription that was started as pending can be activated via this service.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Activate Subscription","version":"1.0.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/activate":{"post":{"summary":"Activate Subscription","description":"A subscription that was started as pending can be activated via this service.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription that was started as pending."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a Base64-encoded signed hash value that begins with IYZWSv2."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ActivateSubscriptionRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Reference code of the subscription that was started as pending."}}},"ActivateSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the result of the request. Returns `success` if the operation succeeds."},"systemTime":{"type":"integer","description":"Unix timestamp (milliseconds) of the response."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the result of the request (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Unix timestamp (milliseconds) of the response."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/activate_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L38">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L123">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L315">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/xswkakr/7-1-activate-subscription">Postman</a></td></tr></tbody></table>

## Retry Subscription Payment

> If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/operation/retry":{"post":{"summary":"Retry Subscription Payment","description":"If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrySubscriptionPaymentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrySubscriptionPaymentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"RetrySubscriptionPaymentRequest":{"type":"object","required":["referenceCode"],"properties":{"referenceCode":{"type":"string","description":"Reference code of the failed payment. This is the **orderReferenceCode** value provided in the webhook notification for the failed subscription payment.\n"}}},"RetrySubscriptionPaymentResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retry_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L84">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L141">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L291">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/krob5w3/7-2-retry-subscription">Postman</a></td></tr></tbody></table>

## Cancel Subscription

> Cancels an active subscription.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/cancel":{"post":{"summary":"Cancel Subscription","description":"Cancels an active subscription.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to cancel."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"CancelSubscriptionRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Subscription reference code. Can optionally be sent in the request body."}}},"CancelSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/cancel_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L19">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L181">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L304">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/0xuvqlz/7-3-cancel-subscription">Postman</a></td></tr></tbody></table>

## Upgrade Subscription

> You can change or upgrade the plan during the subscription, provided that the \*\*new plan belongs to the same product\*\* and the billing interval (\*\*paymentInterval\*\* and \*\*paymentIntervalCount\*\*) remains the same. Use this service for price changes.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/upgrade":{"post":{"summary":"Upgrade Subscription","description":"You can change or upgrade the plan during the subscription, provided that the **new plan belongs to the same product** and the billing interval (**paymentInterval** and **paymentIntervalCount**) remains the same. Use this service for price changes.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to upgrade."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"UpgradeSubscriptionRequest":{"type":"object","required":["upgradePeriod","newPricingPlanReferenceCode"],"properties":{"upgradePeriod":{"type":"string","enum":["NOW","NEXT_PERIOD"],"description":"When the upgrade will take effect.\nValues:\n- **NOW**: Apply the change immediately.\n- **NEXT_PERIOD**: Apply the change at the next billing period.\n"},"newPricingPlanReferenceCode":{"type":"string","description":"Reference code of the target pricing plan."},"useTrial":{"type":"boolean","description":"If **true**, includes the trial period of the upgraded plan."},"resetRecurrenceCount":{"type":"boolean","description":"- **true**: Recalculates the subscription end date according to the new plan’s **recurrenceCount**.  \n- **false**: Keeps the current plan’s end date and transfers it to the new plan.\n"}}},"UpgradeSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the newly created subscription."},"parentReferenceCode":{"type":"string","description":"Reference code used by the merchant to correlate subscription updates."},"pricingPlanReferenceCode":{"type":"string"},"customerReferenceCode":{"type":"string"},"subscriptionStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Subscription status."},"trialDays":{"type":"integer","description":"Trial period of the plan (days)."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"startDate":{"type":"date","description":"Start time (epoch ms)."},"endDate":{"type":"date","description":"End time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/upgrade_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L57">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L159">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L326">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/o6rygn3/7-4-upgrade-subscription">Postman</a></td></tr></tbody></table>

## Get Subscription Detail

> Returns full details of a subscription by its reference code.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}":{"get":{"summary":"Get Subscription Detail","description":"Returns full details of a subscription by its reference code.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to query."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubscriptionDetailOptionalRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubscriptionDetailResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"GetSubscriptionDetailOptionalRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Subscription reference code. Can optionally be sent in the request body."}}},"GetSubscriptionDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","description":"Pagination information and subscription records.","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer","description":"Current page number."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Detailed subscription records.","items":{"$ref":"#/components/schemas/SubscriptionDetailItem"}}}}}},"SubscriptionDetailItem":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Subscription reference code."},"parentReferenceCode":{"type":"string","description":"Reference used by the merchant to correlate subscription updates."},"pricingPlanName":{"type":"string","description":"Name of the pricing plan linked to the subscription."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the pricing plan linked to the subscription."},"productName":{"type":"string","description":"Product name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"customerEmail":{"type":"string","description":"Customer email address."},"customerGsmNumber":{"type":"string","description":"Customer GSM number."},"customerReferenceCode":{"type":"string","description":"Customer reference code."},"subscriptionStatus":{"type":"string","description":"Subscription status.\n\nValues:\n- **ACTIVE**: Subscription is active and payments are being collected regularly.\n- **PENDING**: Subscription is paused.\n- **UNPAID**: Payment could not be collected during the subscription.\n- **UPGRADED**: Subscription has been updated to another plan.\n- **CANCELED**: Subscription is canceled.\n- **EXPIRED**: Subscription period ended; no further charges are attempted.\n","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"trialDays":{"type":"integer","description":"Trial period (days) of the pricing plan."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."},"orders":{"type":"array","description":"List of periods (orders) within the subscription.","items":{"$ref":"#/components/schemas/SubscriptionOrder"}}}},"SubscriptionOrder":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the subscription period (order)."},"price":{"type":"decimal","description":"Period price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency."},"startPeriod":{"type":"integer","description":"Start time of the period (epoch ms)."},"endPeriod":{"type":"integer","description":"End time of the period (epoch ms)."},"orderStatus":{"type":"string","description":"Period status.","enum":["WAITING","SUCCESS","FAILED"]},"paymentAttempts":{"type":"array","description":"Payment attempts made for this period.","items":{"$ref":"#/components/schemas/SubscriptionPaymentAttempt"}}}},"SubscriptionPaymentAttempt":{"type":"object","description":"A single payment attempt for a subscription period.","properties":{"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"createdDate":{"type":"integer","description":"Creation time of the attempt (epoch ms)."},"paymentStatus":{"type":"string","description":"Result of the payment attempt.","enum":["SUCCESS","FAILED"]},"paymentId":{"type":"integer","description":"Payment ID for a successful payment. Present only when **SUCCESS**."},"errorCode":{"type":"string","description":"Error code for a failed payment. Present only when **FAILED**."},"errorMessage":{"type":"string","description":"Error message for a failed payment. Present only when **FAILED**."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L199">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L342">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/7go66rr/3-2-3-retrieve-subscription">Postman</a></td></tr></tbody></table>

## Search Subscriptions

> Retrieve subscription and payment details by filtering with various parameters, or without any parameters. For example, by sending only \*\*subscriptionStatus\*\*, you can list subscriptions with that status.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions":{"get":{"summary":"Search Subscriptions","description":"Retrieve subscription and payment details by filtering with various parameters, or without any parameters. For example, by sending only **subscriptionStatus**, you can list subscriptions with that status.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Reference code of the subscription to query."},{"name":"customerReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Customer reference code."},{"name":"pricingPlanReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Reference code of the pricing plan used in the subscription."},{"name":"parent","in":"path","required":false,"schema":{"type":"string"},"description":"Parent reference code used for matching in subscription updates."},{"name":"subscriptionStatus","in":"path","required":false,"schema":{"type":"string","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"description":"Subscription status filter."},{"name":"startDate","in":"path","required":false,"schema":{"type":"integer"},"description":"Subscription start date."},{"name":"endDate","in":"path","required":false,"schema":{"type":"integer"},"description":"Subscription end date (epoch ms)."},{"name":"page","in":"path","required":false,"schema":{"type":"integer"},"description":"Page number."},{"name":"count","in":"path","required":false,"schema":{"type":"integer"},"description":"Number of records per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSubscriptionsResponse"}}}},"404":{"description":"Example response for a wrong endpoint (e.g., typo).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"SearchSubscriptionsResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","description":"Pagination information and subscription records.","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer","description":"Current page number."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Detailed subscription records.","items":{"$ref":"#/components/schemas/SubscriptionDetailItem"}}}}}},"SubscriptionDetailItem":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Subscription reference code."},"parentReferenceCode":{"type":"string","description":"Reference used by the merchant to correlate subscription updates."},"pricingPlanName":{"type":"string","description":"Name of the pricing plan linked to the subscription."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the pricing plan linked to the subscription."},"productName":{"type":"string","description":"Product name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"customerEmail":{"type":"string","description":"Customer email address."},"customerGsmNumber":{"type":"string","description":"Customer GSM number."},"customerReferenceCode":{"type":"string","description":"Customer reference code."},"subscriptionStatus":{"type":"string","description":"Subscription status.\n\nValues:\n- **ACTIVE**: Subscription is active and payments are being collected regularly.\n- **PENDING**: Subscription is paused.\n- **UNPAID**: Payment could not be collected during the subscription.\n- **UPGRADED**: Subscription has been updated to another plan.\n- **CANCELED**: Subscription is canceled.\n- **EXPIRED**: Subscription period ended; no further charges are attempted.\n","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"trialDays":{"type":"integer","description":"Trial period (days) of the pricing plan."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."},"orders":{"type":"array","description":"List of periods (orders) within the subscription.","items":{"$ref":"#/components/schemas/SubscriptionOrder"}}}},"SubscriptionOrder":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the subscription period (order)."},"price":{"type":"decimal","description":"Period price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency."},"startPeriod":{"type":"integer","description":"Start time of the period (epoch ms)."},"endPeriod":{"type":"integer","description":"End time of the period (epoch ms)."},"orderStatus":{"type":"string","description":"Period status.","enum":["WAITING","SUCCESS","FAILED"]},"paymentAttempts":{"type":"array","description":"Payment attempts made for this period.","items":{"$ref":"#/components/schemas/SubscriptionPaymentAttempt"}}}},"SubscriptionPaymentAttempt":{"type":"object","description":"A single payment attempt for a subscription period.","properties":{"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"createdDate":{"type":"integer","description":"Creation time of the attempt (epoch ms)."},"paymentStatus":{"type":"string","description":"Result of the payment attempt.","enum":["SUCCESS","FAILED"]},"paymentId":{"type":"integer","description":"Payment ID for a successful payment. Present only when **SUCCESS**."},"errorCode":{"type":"string","description":"Error code for a failed payment. Present only when **FAILED**."},"errorMessage":{"type":"string","description":"Error message for a failed payment. Present only when **FAILED**."}}},"NotFoundErrorResponse":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server time (epoch ms)."},"status":{"type":"integer","description":"HTTP status code."},"error":{"type":"string","description":"Short error description."},"path":{"type":"string","description":"Requested path."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/search_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionSearchSample.java#L17">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L218">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L353">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/5onz787/3-2-4-search-subscriptions">Postman</a></td></tr></tbody></table>

## Subscription Card Update (Checkout Form)

> Updates the credit card used in a subscription. In cases like payment failure or card expiry, merchants can prompt customers to update their card. \*\*The update can only be performed through the iyzico Checkout Form.\*\*\
> A \*\*₺1\*\* validation charge is taken and immediately refunded to validate the updated card.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/card-update/checkoutform/initialize":{"post":{"summary":"Subscription Card Update (Checkout Form)","description":"Updates the credit card used in a subscription. In cases like payment failure or card expiry, merchants can prompt customers to update their card. **The update can only be performed through the iyzico Checkout Form.**\nA **₺1** validation charge is taken and immediately refunded to validate the updated card.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCardUpdateCheckoutFormRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCardUpdateCheckoutFormResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"InitializeCardUpdateCheckoutFormRequest":{"type":"object","required":["callbackUrl","customerReferenceCode"],"properties":{"callbackUrl":{"type":"string","description":"Callback URL where the update result will be posted."},"customerReferenceCode":{"type":"string","description":"Reference code of the customer whose card will be updated."},"subscriptionReferenceCode":{"type":"string","description":"If updating on a specific subscription, the subscription reference code (optional).\n"},"locale":{"type":"string","enum":["tr","en"],"description":"Response language preference."}}},"InitializeCardUpdateCheckoutFormResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"token":{"type":"string","description":"Token of the card update checkout form."},"checkoutFormContent":{"type":"string","description":"HTML content for the checkout form where card information is updated."},"tokenExpireTime":{"type":"integer","description":"Token validity period (seconds)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/card_update_customer.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCardUpdateCheckoutFormInitializeSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L246">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L259">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/aoe23xd/4-1-1-initialize-checkoutform">Postman</a></td></tr></tbody></table>

{% hint style="info" %}
Merchants can send the locale and conversationId parameters in all requests, but this is not mandatory. The locale parameter determines the language of the response. If specified as “EN”, error messages will be received in English. Conversation id is a value that software developers can use to match requests and responses. If this parameter is sent, the same value will be received in the response.
{% endhint %}

With this request, a checkout form is created and when the customer makes the payment, token information is sent to the specified `callBackUrl` address. In this case, the card has been updated successfully.


# Subscriber Transactions

After each subscription payment, a default customerReferenceCode is generated for the customer whose details are provided. Currently, this reference code can only be used to retrieve and update customer information.

Customers are created or updated based on the email parameter. For example, a unique reference code, let's say 'A', is generated for a customer when a subscription is created with email address 'X'. If the email address 'X' is used in another subscription, the customer details sent in the request are updated, and once again, a unique reference code 'A' is generated.

There are 3 different methods that can be used on subscribers.

1. [Update Subscriber](#post-v2-subscription-customers-customerreferencecode)
2. [Get Subscriber](#get-v2-subscription-customers-customerreferencecode)
3. [List of Subscribers](#get-v2-subscription-customers)

## Update Subscriber

> Update all details of a subscriber via API. Provide the subscriber's \*\*customerReferenceCode\*\* as a path parameter and include the fields to be updated in the request body. At least \*\*one field\*\* in the body is required; only the provided fields will be updated.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Subscriber Management","version":"1.1.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/customers/{customerReferenceCode}":{"post":{"summary":"Update Subscriber","description":"Update all details of a subscriber via API. Provide the subscriber's **customerReferenceCode** as a path parameter and include the fields to be updated in the request body. At least **one field** in the body is required; only the provided fields will be updated.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"customerReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Subscriber reference code."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request content type."}},"schemas":{"CustomerUpdateRequest":{"type":"object","description":"Fields to update. All fields are **optional**, but the body must contain at least one property.\n","minProperties":1,"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer **+90** format."},"identityNumber":{"type":"string","description":"Turkish National ID Number (11 digits)."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}},"CustomerAddress":{"type":"object","description":"Address information.","properties":{"address":{"type":"string","description":"Address line."},"zipCode":{"type":"string","description":"Postal/ZIP code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"district":{"type":"string","description":"District (if any)."},"country":{"type":"string","description":"Country."}}},"CustomerUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the result of the request."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."},"data":{"type":"object","description":"Updated subscriber information.","properties":{"referenceCode":{"type":"string","description":"Subscriber reference code."},"createdDate":{"type":"integer","description":"Subscriber creation time (epoch ms)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Record status."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Turkish National ID Number."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number."},"contactEmail":{"type":"string","description":"Contact email."},"contactGsmNumber":{"type":"string","description":"Contact GSM number."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/update_customer.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCustomerSample.java#L54">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionCustomerSample.cs#L68">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L197">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/hxware5/5-3-update-customer">Postman</a></td></tr></tbody></table>

## Subscriber Detail

> Retrieve all details of a subscriber by its reference code.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Subscriber Management","version":"1.1.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/customers/{customerReferenceCode}":{"get":{"summary":"Subscriber Detail","description":"Retrieve all details of a subscriber by its reference code.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"customerReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Subscriber reference code."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request content type."}},"schemas":{"CustomerDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."},"data":{"type":"object","description":"Subscriber (customer) details.","properties":{"referenceCode":{"type":"string","description":"Subscriber reference code."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Record status."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Turkish National ID Number."},"email":{"type":"string","description":"Subscriber email."},"gsmNumber":{"type":"string","description":"Subscriber GSM number."},"contactEmail":{"type":"string","description":"Contact email."},"contactGsmNumber":{"type":"string","description":"Contact GSM number."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}}}},"CustomerAddress":{"type":"object","description":"Address information.","properties":{"address":{"type":"string","description":"Address line."},"zipCode":{"type":"string","description":"Postal/ZIP code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"district":{"type":"string","description":"District (if any)."},"country":{"type":"string","description":"Country."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_customer.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCustomerSample.java#L89">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionCustomerSample.cs#L122">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L233">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/t0if1ge/5-4-retrieve-customer">Postman</a></td></tr></tbody></table>

## List Subscribers

> List all subscribers with basic details.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Subscriber Management","version":"1.1.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/customers":{"get":{"summary":"List Subscribers","description":"List all subscribers with basic details.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number to fetch."},{"name":"count","in":"query","required":false,"schema":{"type":"integer"},"description":"Number of subscribers per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request content type."}},"schemas":{"CustomerListResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."},"data":{"type":"object","description":"Pagination info and subscriber list.","properties":{"totalCount":{"type":"integer","description":"Total number of records."},"currentPage":{"type":"integer","description":"Current page."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Subscriber records.","items":{"type":"object","allOf":[{"$ref":"#/components/schemas/CustomerDetailResponse/properties/data"}]}}}}}},"CustomerDetailResponse":{"properties":{"data":{"type":"object","description":"Subscriber (customer) details.","properties":{"referenceCode":{"type":"string","description":"Subscriber reference code."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"status":{"type":"string","enum":["ACTIVE"],"description":"Record status."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Turkish National ID Number."},"email":{"type":"string","description":"Subscriber email."},"gsmNumber":{"type":"string","description":"Subscriber GSM number."},"contactEmail":{"type":"string","description":"Contact email."},"contactGsmNumber":{"type":"string","description":"Contact GSM number."},"billingAddress":{"$ref":"#/components/schemas/CustomerAddress"},"shippingAddress":{"$ref":"#/components/schemas/CustomerAddress"}}}}},"CustomerAddress":{"type":"object","description":"Address information.","properties":{"address":{"type":"string","description":"Address line."},"zipCode":{"type":"string","description":"Postal/ZIP code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"district":{"type":"string","description":"District (if any)."},"country":{"type":"string","description":"Country."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the request result (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"The current epoch time in milliseconds at the moment of the response."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/list_customers.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCustomerListSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionCustomerSample.cs#L141">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L244">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/aa7ianc/5-2-list-customers">Postman</a></td></tr></tbody></table>


# Bank Transfer

{% embed url="<https://www.youtube.com/watch?v=OUCo1A9Sryw>" %}

Online retailers who sell products or services can greatly benefit from offering a variety of payment methods, and one important factor that can impact the success of their e-commerce business is the diversity of payment methods available. In Turkey and worldwide, bank transfers and electronic fund transfers (EFT) play a significant role as payment options, and they can be easily integrated into our merchants' websites.

To accept payments via bank transfers and EFT, you simply need to place the link created with the iyzipay API on your website. For merchants who have integrated the iyzico payment form, you can request the activation of the bank transfer/EFT payment option by sending an email to <integration@iyzico.com>. In this case, the Secure Bank Transfer/EFT tab will be visible on the payment form, allowing customers to choose this payment method.

### Advantages

* Don't need to open different bank accounts because the iyzico Secure Bank Transfer/EFT system is integrated with İş Bankası, Garanti Bankası, and Akbank. Additional banks can be added by iyzico without disrupting your processes or requiring any extra development on your end.
* There's no need for manual control processes by your finance and accounting teams. The payment matching and reporting process, which can be a significant burden for your company, is fully automated by iyzico where iyzico checks bank accounts every 15 minutes.
* Users and merchants are informed at every stage of the process. Merchants and customers are notified via SMS and email as soon as the bank transfer process begins. When the payment is matched, the transaction status is marked as successful, and another notification is sent. Customers have 3 business days to make the transfer.
* Payment cancellation and refund processes are managed by iyzico on your behalf. Your customers can benefit from iyzico's secure shopping, live support, and 24/7 communication.
* Reports are available in a single format. Transaction details can be quickly accessed through the API and iyzico merchant panel. For each transaction, the transaction details are sent to the specified URL via post notification, allowing you to update your system accordingly.
* iyzico's secure shopping increases customer satisfaction.

### Bank Transfer Payment Flow

Bank Transfer/EFT process starts with you first selecting the bank account to which you will make the Bank Transfer/EFT. After you enter and confirm the account information to which you will send the payment, your bank accounts are checked every 15 minutes. When information about the payment comes from the bank accounts, iyzico confirms the payment.

<div><figure><img src="/files/i91FuFedpr3D50Rpuzrc" alt=""><figcaption></figcaption></figure> <figure><img src="/files/tx1KerDIfKGPp8HTDYmy" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Jm4OI9xAjoDZsMWLkGL2" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/Gd80CyA4XP95yq1TJ67s" alt=""><figcaption></figcaption></figure> <figure><img src="/files/siy4E4Lv32JceUypPTDK" alt=""><figcaption></figcaption></figure> <figure><img src="/files/a7HkyLBNDPUVoJXhLahs" alt=""><figcaption></figcaption></figure></div>


# Bank Transfer Implementation

<figure><img src="/files/mWGvX7Iopr8J3tpawVni" alt=""><figcaption><p>Pazaryeri Entegrasyon Akışı</p></figcaption></figure>

### Steps

Bank Transfer consists of two steps.

1. [Bank Transfer Init](/en/products/bank-transfer/bank-transfer-implementation/banka-transferi-baslatma)
2. [Bank Transfer Retrieve](/en/products/bank-transfer/bank-transfer-implementation/banka-transferi-sorgulama)

### How does the iyzico Bank Transfer work?

1. Customers are provided with various bank options to make bank transfers payments.

<figure><img src="/files/dgu56OOG0XUlEcl9enOU" alt=""><figcaption></figcaption></figure>

2. iyzico sends the bank details preferred by your customers to them via SMS and email.

<figure><img src="/files/hBXglSqK815NB2dzHShM" alt=""><figcaption></figcaption></figure>

\
3\. Your customer is expected to make a transfer from their own bank within 3 business days using the account details provided.

<figure><img src="/files/gW6TmAN4kVxixFfX8Zqb" alt=""><figcaption></figcaption></figure>

<br>


# Bank Transfer Init

To activate Bank Transfer payment method immediately, send an email to <destek@iyzico.com>

### Bank Transfer Init Formats

Bank Transfer processes under [Checkoutform](/en/payment-methods/checkoutform) or [PWI](/en/payment-methods/paywithiyzico) products of iyzico, simply.

<table data-card-size="large" data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td><td><a href="/pages/9img6la4fJokKFfD7KbV">/pages/9img6la4fJokKFfD7KbV</a></td></tr><tr><td><a href="/pages/ugoJJmTz1rRzSg3mK7Tm">/pages/ugoJJmTz1rRzSg3mK7Tm</a></td><td></td></tr></tbody></table>


# Bank Transfer Retrieve

When customers who have completed the Bank Transfer process click on the "Complete Purchase" button, they will be directed to the callbackUrl address that you specified during the initiation of the bank transfer.&#x20;

A token value will be posted to this address. You can use this token value to make a second inquiry. The returned response should be checked for the paymentStatus value. If you want to systematically check the payment status, you can repeat this request at specific intervals. This request provides detailed information about the transaction result.&#x20;

You can obtain the token value to be used in this inquiry either when you create the bank transfer form or when it is posted to your callbackUrl address by iyzico. Additionally, a notification will be sent to the webhookURL address when the payment is matched.

{% hint style="info" %}
**NOTE**: The product/service should only be delivered to the customer when the paymentStatus is "SUCCESS". In other payment statuses, the payment is not considered successful.
{% endhint %}

### Sample Webhook Notification

```json
{
  "iyziEventTime": "1569325868970",
  "iyziEventType": "BANK_TRANSFER_AUTH",
  "iyziReferenceCode": "028246012345",
  "status": "SUCCESS",
  "token": "04de1234-32b9-6907-bf06-0987ae260e35"
}
```


# Bank Transfer FAQ

<details>

<summary>When will your customer's order be completed?</summary>

When your customer completes the money transfer/EFT transaction by entering all the correct information through the bank he has chosen, iyzico matches the money transfer/EFT transaction with the payment request and confirms the payment within the same business day. Once the payment is confirmed, the order process is completed when the product is shipped.

</details>

<details>

<summary>When should I ship the product?</summary>

When you receive an e-mail informing you that payment has been received, you can ship the product. You can also follow your transactions in the "Successful Bank Transfer Payments" section under the "All Transactions" heading on your iyzico Control Panel.

</details>

<details>

<summary>How should I answer my customers' questions about  Bank Transfer?</summary>

Your customers can reach our 24/7 live support service via SMS, e-mail or iyzico App for all their questions about the Protected Transfer/EFT Method.

</details>


# Mass Payout

The **Mass Payout** service allows merchants to send payments to multiple recipients in a single transaction.\
This service is designed especially for marketplaces, freelance platforms, financial technology solutions, and systems where multiple payments are processed regularly.

With the **Mass Payout API**, you can make payments to several recipients in one request instead of initiating separate transactions for each payment.

***

### &#x20;Features

* **Bulk payment management:** Create dozens or even hundreds of payments in a single request.
* **Status tracking:** Monitor the status of each payment in real time.
* **Reporting:** Query all transactions and access payment results through the API.

***

### &#x20;Use Cases

* Partner or affiliate payouts
* Commission or bonus distributions
* Insurance claim payments
* Revenue or profit share distributions, etc.

***

### &#x20;Advantages

* Reduces operational workload and eliminates the need for manual processing.
* Automates bulk transfers through a single API integration.
* Provides a fast, secure, and scalable payment solution.


# Mass Payout Integration

The **Mass Payout** service allows merchants to send payments to multiple recipients in a single transaction.\
This service is designed especially for marketplaces, freelance platforms, financial technology solutions, and systems where multiple payments are processed regularly.

With the **Mass Payout API**, you can make payments to several recipients in one request instead of initiating separate transactions for each payment.

### Pre-Integration Requirements

{% hint style="info" %}
Internal control and approval are required to use this feature.\
You can contact the iyzico Support Team to perform the necessary checks and activate the feature.
{% endhint %}

## Integration Steps

1. [Mass Payout Initialize](/en/products/mass-payout/mass-payout-integration/mass-payout-initalize)
2. [Mass Payout Auth](/en/products/mass-payout/mass-payout-integration/mass-payout-auth)
3. [Retrieve Mass Payout](/en/products/mass-payout/mass-payout-integration/retrieve-mass-payout)

## Sample Case

### Initialize Mass Payout

#### Example Request

```json
{
    "externalId": "massPayoutId-323ddd",
    "conversationId": "conversationId-323f",
    "purpose" : "SALARY",
    "items": [
        {
            "itemExternalId": "ext-65656",
            "recipientType": "IBAN",
            "recipientInfo": "TR920086402100002353983528",
            "amount": {
                "value": 100,
                "currency": "TRY"
            },
            "description": "Payment for services",
            "recipientName": "John Doe"
        },
        {
            "itemExternalId": "ext-9545455",
            "recipientType": "MEMBER_ID",
            "recipientInfo": "2228853",
            "amount": {
                "value": 8000,
                "currency": "TRY"
            }
        },
        {
            "itemExternalId": "ext-545454542",
            "recipientType": "IDENTITY_NUMBER",
            "recipientInfo": "2222222817",
            "amount": {
                "value": 20000,
                "currency": "TRY"
            }
        },
         {
            "itemExternalId": "ext-50070945",
            "recipientType": "PHONE",
            "recipientInfo": "+905555856935",
            "amount": {
                "value": 7000,
                "currency": "TRY"
            }
        }

    ]
}
```

#### Example Response

```json
{
    "status": "success",
    "systemTime": 1759231970716,
    "conversationId": "conversationId-894",
    "requestId": "79cdefc1-3ce6-4f51-bdd9-0c050274db64"
}
```

### Auth Mass Payout

#### Example Request

```json
{
    "requestId" : "79cdefc1-3ce6-4f51-bdd9-0c050274db64"
}
```

#### Example Response

```json
{
    "status": "success",
    "systemTime": 1759231995145
}
```

### Retrieve Mass Payout

#### Example Request

```json
{
    "requestId": "c95e344a-c7c9-4605-91b8-3f48ee9dece6",
    "externalMassPayoutId": "massPayoutId-323",
    "page": 0,
    "size": 40
}
```

#### Example Response

```json
{
    "status": "success",
    "systemTime": 1759155442830,
    "massPayout": {
        "externalId": "massPayoutId-323",
        "merchantId": 000000,
        "totalAmount": 201.00,
        "totalSuccessfulAmount": 0,
        "massPayoutStatus": "PUBLISHED_TO_QUEUE",
        "totalCommissionAmount": 0,
        "currency": "TRY"
    },
    "massPayoutItems": {
        "items": [
            {
                "itemExternalId": "ext-0077",
                "referenceCode": "a97b142a-1e22-4ceb-bafb-38d6c1c4a4f7",
                "recipientType": "IBAN",
                "recipientInfo": "TR920086402100002353983528",
                "recipientName": "John Doe",
                "description": "Payment for services",
                "itemStatus": "INIT",
                "errorMessages": [],
                "totalAmount": 100.50,
                "commissionAmount": 20.00000000,
                "currencyCode": "TRY"
            },
            {
                "itemExternalId": "ext-0099",
                "referenceCode": "050b8f81-aaf7-400d-80fa-21bbed27a816",
                "recipientType": "IBAN",
                "recipientInfo": "TR920086402100002353983528",
                "recipientName": "John Doe",
                "description": "Payment for services",
                "itemStatus": "INIT",
                "errorMessages": [],
                "totalAmount": 100.50,
                "commissionAmount": 20.00000000,
                "currencyCode": "TRY"
            }
        ],
        "page": 0,
        "size": 40,
        "total": 2
    }
}
```


# Mass Payout Initalize

## Initialize Mass Payout

> Creates a new \*\*Mass Payout\*\*. Each valid payout item is stored with status \`INIT\`.\
> \
> \*\*Resulting States\*\*\
> \- Mass Payout → \`INIT\`\
> \- Mass Payout Items → \`INIT\` (if valid) or \`INVALID\` (if invalid)<br>

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/init":{"post":{"tags":["Mass Payout"],"summary":"Initialize Mass Payout","description":"Creates a new **Mass Payout**. Each valid payout item is stored with status `INIT`.\n\n**Resulting States**\n- Mass Payout → `INIT`\n- Mass Payout Items → `INIT` (if valid) or `INVALID` (if invalid)\n","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutInitializeRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutInitializeResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutInitializeRequest":{"type":"object","description":"Mass payout initialization request.","required":["externalId","conversationId","items"],"properties":{"externalId":{"type":"string","description":"Unique identifier for the mass payout request (idempotency)."},"conversationId":{"type":"string","description":"Correlation ID for the mass payout."},"purpose":{"type":"string","description":"Business purpose of the payout.","enum":["SALARY","BONUS","SETTLEMENT","GOODS","SERVICES","CASHBACK","REBATES","DONATIONS"]},"items":{"type":"array","description":"Payout items.","minItems":1,"items":{"$ref":"#/components/schemas/MassPayoutItem"}}}},"MassPayoutItem":{"type":"object","description":"Mass payout item.","required":["itemExternalId","recipientType","recipientInfo","amount","description"],"properties":{"itemExternalId":{"type":"string","description":"ID per payout item."},"recipientType":{"type":"string","description":"Type of recipient identifier.","enum":["PHONE","IBAN","IDENTITY_NUMBER","MEMBER_ID"]},"recipientInfo":{"type":"string","description":"Identifier matching the recipientType (phone, IBAN, etc.)."},"amount":{"$ref":"#/components/schemas/Amount"},"description":{"type":"string","description":"Item description."},"recipientName":{"type":"string","description":"Recipient name. **Required if** `recipientType` is `IBAN`."},"nonWithdrawable":{"type":"boolean","description":"iyzico ensures that the fee sent to your wallet cannot be withdrawn."}}},"Amount":{"type":"object","description":"Amount information.","required":["value","currency"],"properties":{"value":{"type":"decimal","description":"Amount to send."},"currency":{"type":"string","description":"Currency code."}}},"MassPayoutInitializeResponse":{"type":"object","description":"Mass payout initialization response.","properties":{"requestId":{"type":"string","description":"Correlation / tracking identifier for the mass payout."},"conversationId":{"type":"string","description":"Correlation ID inherited from the base request if present."},"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","description":"Language/region setting such as `tr` or `en`."},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"invalidItems":{"type":"array","description":"Collection of order-level error details.","items":{"$ref":"#/components/schemas/InvalidItem"}}}},"InvalidItem":{"type":"object","description":"Invalid payout item detail.","properties":{"externalId":{"type":"string","description":"External ID of the specific item that failed."},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}}}}}}
```


# Mass Payout Auth

## Auth Mass Payout

> Second step of the two-phase process. Transitions valid mass payout items from \`INIT\` to \`PROCESSING\`.\
> Messages to be processed are queued (for fund reservation/transfer). Invalid orders remain unchanged. An audit trail is recorded.<br>

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/auth":{"post":{"tags":["Mass Payout"],"summary":"Auth Mass Payout","description":"Second step of the two-phase process. Transitions valid mass payout items from `INIT` to `PROCESSING`.\nMessages to be processed are queued (for fund reservation/transfer). Invalid orders remain unchanged. An audit trail is recorded.\n","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutAuthRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutAuthResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutAuthRequest":{"type":"object","description":"Mass payout authorization request.","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation / tracking identifier returned from the initialization step."}}},"MassPayoutAuthResponse":{"type":"object","description":"Mass payout authorization response.","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"locale":{"type":"string","description":"Language/region setting such as `tr` or `en`."}}}}}}
```


# Mass Payout Cancel

## Cancel Mass Payout

> Cancels the mass payout request and its items that are in \`INIT\` status.

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/cancel/{requestId}":{"post":{"tags":["Mass Payout"],"summary":"Cancel Mass Payout","description":"Cancels the mass payout request and its items that are in `INIT` status.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"},{"name":"requestId","in":"path","required":true,"description":"Correlation / tracking identifier of the mass payout.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutAuthResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutAuthResponse":{"type":"object","description":"Mass payout authorization response.","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"locale":{"type":"string","description":"Language/region setting such as `tr` or `en`."}}}}}}
```


# Retrieve Mass Payout

## Retrieve Mass Payout and Items Detail

> Retrieves the details of a \*\*Mass Payout\*\* and its contained payout items.\
> You must provide \*\*either\*\* \`requestId\` \*\*or\*\* \`externalMassPayoutId\` (or both), along with pagination parameters.<br>

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/retrieve":{"post":{"tags":["Mass Payout"],"summary":"Retrieve Mass Payout and Items Detail","description":"Retrieves the details of a **Mass Payout** and its contained payout items.\nYou must provide **either** `requestId` **or** `externalMassPayoutId` (or both), along with pagination parameters.\n","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutRetrieveRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutRetrieveResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutRetrieveRequest":{"type":"object","description":"Retrieve mass payout and item details.","required":["page","size"],"anyOf":[{"required":["requestId"]},{"required":["externalMassPayoutId"]}],"properties":{"requestId":{"type":"string","description":"Correlation / tracking identifier for the mass payout."},"externalMassPayoutId":{"type":"string","description":"Unique id for the mass payout request (idempotency)."},"page":{"type":"integer","description":"Page number to retrieve."},"size":{"type":"integer","description":"Number of results per page."}}},"MassPayoutRetrieveResponse":{"type":"object","description":"Mass payout and items detail response.","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"locale":{"type":"string"},"massPayout":{"$ref":"#/components/schemas/MassPayoutSummary"},"massPayoutItems":{"$ref":"#/components/schemas/MassPayoutItemsPage"},"page":{"type":"integer"},"size":{"type":"integer"},"total":{"type":"integer"}}},"MassPayoutSummary":{"type":"object","description":"Summary information for a mass payout.","properties":{"externalId":{"type":"string"},"merchantId":{"type":"integer"},"totalAmount":{"type":"decimal"},"totalSuccessfulAmount":{"type":"decimal"},"massPayoutStatus":{"type":"string","description":"Mass payout lifecycle status (enum).","enum":["INIT","IN_PROGRESS","PUBLISHED_TO_QUEUE","COMPLETED","FAIL","INSUFFICIENT_BALANCE","CANCELED"]},"totalCommissionAmount":{"type":"decimal"},"currency":{"type":"string"}}},"MassPayoutItemsPage":{"type":"object","description":"Paged list of mass payout items.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MassPayoutItemDetail"}}}},"MassPayoutItemDetail":{"type":"object","description":"Mass payout item detail.","properties":{"itemExternalId":{"type":"string"},"referenceCode":{"type":"string"},"recipientType":{"type":"string","enum":["PHONE","IBAN","IDENTITY_NUMBER","MEMBER_ID"]},"recipientInfo":{"type":"string"},"recipientName":{"type":"string"},"description":{"type":"string"},"itemStatus":{"type":"string","description":"Mass payout item lifecycle status (enum).","enum":["FAILED","SUCCESS","INIT","INVALID","PROCESSING","MASS_PAYOUT_CANCELED","QUEUED","DEPOSIT_SUCCESS","DEPOSIT_FAIL"]},"errorMessages":{"type":"array","items":{"type":"string"}},"totalAmount":{"type":"decimal"},"commissionAmount":{"type":"decimal"},"currencyCode":{"type":"string"}}}}}}
```

### Mass Payout Status List <a href="#masspayoutapidoc-masspayoutstatuslist" id="masspayoutapidoc-masspayoutstatuslist"></a>

<table data-full-width="true"><thead><tr><th>Status	</th><th>Description</th></tr></thead><tbody><tr><td>INIT</td><td>Mass payout request received but not yet authorized.</td></tr><tr><td>IN_PROGRESS</td><td>Request has been authorized and marked as in progress with a valid requestId.</td></tr><tr><td>PUBLISHED_TO_QUEUE </td><td>Request published to iyzico internal queue. At least one payment has been sent to the bank.</td></tr><tr><td>COMPLETED</td><td>All items related to the mass payout have been successfully processed.</td></tr><tr><td>FAIL</td><td>All items within the mass payout failed at the bank.</td></tr><tr><td>INSUFFICIENT_BALANCE</td><td>Insufficient merchant mass payout balance to execute the request.</td></tr><tr><td>CANCELED </td><td>Mass payout request has been canceled.</td></tr></tbody></table>

### Mass Payout Item Status List

<table data-full-width="true"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody><tr><td>FAILED</td><td>Item was sent to the bank but failed. Includes errors returned from the bank or general processing errors. Validation errors will also result in this status.</td></tr><tr><td>SUCCESS</td><td>Item was sent to the bank and completed successfully.</td></tr><tr><td>INIT</td><td>When the mass payout is created, items are stored in waiting state before auth</td></tr><tr><td>INVALID</td><td>Parameter(s) are invalid, missing, or inconsistent.</td></tr><tr><td>PROCESSING</td><td>Item has been sent to the bank and is being processed.</td></tr><tr><td>MASS_PAYOUT_CANCELED</td><td>Item was canceled because the parent mass payout was canceled.</td></tr><tr><td>QUEUED</td><td>Item has been queued (for both bank transfer and wallet/deposit flows)</td></tr><tr><td>DEPOSIT_SUCCESS</td><td>Failed item and its commission amount were successfully refunded to the merchant mass payout balance</td></tr><tr><td>DEPOSIT_FAIL</td><td>Failed payment amount and commission amount could not be refunded to the mass payout balance. An error was returned.</td></tr></tbody></table>


# Mass Payout Reporting

## Retrieve Mass Payout Item Detail

> Retrieves the details of an item contained within a mass payout.

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/retrieve/items/{referenceCode}":{"get":{"tags":["Mass Payout"],"summary":"Retrieve Mass Payout Item Detail","description":"Retrieves the details of an item contained within a mass payout.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"},{"name":"referenceCode","in":"path","required":true,"description":"Unique reference code of the mass payout item.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutItemRetrieveResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutItemRetrieveResponse":{"type":"object","description":"Mass payout single item detail response.","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"},"locale":{"type":"string"},"item":{"$ref":"#/components/schemas/MassPayoutItemDetail"}}},"MassPayoutItemDetail":{"type":"object","description":"Mass payout item detail.","properties":{"itemExternalId":{"type":"string"},"referenceCode":{"type":"string"},"recipientType":{"type":"string","enum":["PHONE","IBAN","IDENTITY_NUMBER","MEMBER_ID"]},"recipientInfo":{"type":"string"},"recipientName":{"type":"string"},"description":{"type":"string"},"itemStatus":{"type":"string","description":"Mass payout item lifecycle status (enum).","enum":["FAILED","SUCCESS","INIT","INVALID","PROCESSING","MASS_PAYOUT_CANCELED","QUEUED","DEPOSIT_SUCCESS","DEPOSIT_FAIL"]},"errorMessages":{"type":"array","items":{"type":"string"}},"totalAmount":{"type":"decimal"},"commissionAmount":{"type":"decimal"},"currencyCode":{"type":"string"}}}}}}
```

### Mass Payout Item Status List

<table data-full-width="true"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody><tr><td>FAILED</td><td>Item was sent to the bank but failed. Includes errors returned from the bank or general processing errors. Validation errors will also result in this status.</td></tr><tr><td>SUCCESS</td><td>Item was sent to the bank and completed successfully.</td></tr><tr><td>INIT</td><td>When the mass payout is created, items are stored in waiting state before auth</td></tr><tr><td>INVALID</td><td>Parameter(s) are invalid, missing, or inconsistent.</td></tr><tr><td>PROCESSING</td><td>Item has been sent to the bank and is being processed.</td></tr><tr><td>MASS_PAYOUT_CANCELED</td><td>Item was canceled because the parent mass payout was canceled.</td></tr><tr><td>QUEUED</td><td>Item has been queued (for both bank transfer and wallet/deposit flows)</td></tr><tr><td>DEPOSIT_SUCCESS</td><td>Failed item and its commission amount were successfully refunded to the merchant mass payout balance</td></tr><tr><td>DEPOSIT_FAIL</td><td>Failed payment amount and commission amount could not be refunded to the mass payout balance. An error was returned.</td></tr></tbody></table>


# Retrieve Mass Payout Balance

## Retrieve Mass Payout Balance

> Displays the mass payout balance of the merchant.

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/balance":{"get":{"tags":["Mass Payout"],"summary":"Retrieve Mass Payout Balance","description":"Displays the mass payout balance of the merchant.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"}],"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutBalanceResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutBalanceResponse":{"type":"object","description":"Merchant mass payout balance response.","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer"},"balance":{"type":"decimal","description":"Available balance amount for mass payout transactions."}}}}}}
```


# iyzico Link

{% embed url="<https://www.youtube.com/watch?v=bWLjNv6kFYY>" %}

iyzilink is a product that allows you to quickly accept payments without requiring integration. You can easily create iyzilinks from your **merchant panel** or the **iyzico İşim İçin** mobile application.

Once you have created the link, you can easily share it with your customers through social media, email, SMS, and other channels. This enables a convenient way for your customers to make payments.

<div><figure><img src="/files/oaGtwKRT7wNRcy3RHivI" alt=""><figcaption></figcaption></figure> <figure><img src="/files/EdMdXeCuNsQ76xW3f9aP" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/HW2b0uFU4XqKHIkSJ3dq" alt=""><figcaption></figcaption></figure> <figure><img src="/files/L8lfwwobBLUgpxRWRel0" alt=""><figcaption></figcaption></figure></div>

## Merchant Panel - iyzico Link

By clicking on the iyzilink menu in your merhcnat panel, you can view your existing iyzilinks and easily add new ones. This provides you with a convenient way to manage and create iyzilinks directly from the merchant panel.

<figure><img src="/files/irWG3FARI7Xh2jvUOKn9" alt=""><figcaption></figcaption></figure>

## **iyzico APP -** iyzico Link

By clicking on the iyzilink menu in your iyzico İşim İçin panel, you can view your existing iyzilinks and easily add new ones.

<div><figure><img src="/files/dglzcyJmwMhTG34q2fDk" alt=""><figcaption></figcaption></figure> <figure><img src="/files/IclW3GFxDdomwKl2qPzT" alt=""><figcaption></figcaption></figure> <figure><img src="/files/1glK5HtK35MqH2iCngIS" alt=""><figcaption></figcaption></figure></div>


# iyzico Link API

The services included in the iyzico Link API are listed below.

1. [Create iyzico Link](#post-v2-iyzilink-products)
2. [Create Fast Link](#post-v2-iyzilink-fast-link-products)
3. [Update iyzico Link](#put-v2-iyzilink-products-token)
4. [Get Details iyzico Link](#get-v2-iyzilink-products-token)
5. [List of iyzico Link](#get-v2-iyzilink-products)
6. [Update Link Status](#patch-v2-iyzilink-products-token-status-status)
7. [Delete Update iyzico Link](#delete-v2-iyzilink-products-token)

## Create iyzico Link

> Used to create a new iyzico Link. On success, returns the link URL. You can share the returned URL with your customers.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products":{"post":{"tags":["iyzilink"],"summary":"Create iyzico Link","description":"Used to create a new iyzico Link. On success, returns the link URL. You can share the returned URL with your customers.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateRequest"}}}},"responses":{"200":{"description":"Successful creation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateOrUpdateResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkCreateRequest":{"type":"object","required":["name","description","price","currencyCode","encodedImageFile"],"properties":{"conversationId":{"type":"string","description":"Value sent for request/response correlation."},"locale":{"type":"string","description":"Response language. Default **tr**.","enum":["en","tr"]},"name":{"type":"string","description":"The product name that will be visible to the customer."},"description":{"type":"string","description":"The product description that will be visible to the customer."},"price":{"type":"string","format":"decimal","description":"Product price."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"encodedImageFile":{"type":"string","description":"Base64-encoded product image."},"addressIgnorable":{"type":"boolean","description":"Do not request address at checkout (true) / request address (false).","enum":[true,false]},"installmentRequested":{"type":"boolean","description":"Enable/disable installment sales.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"flexibleLink":{"type":"boolean","description":"Lets the customer complete the payment with one of three preset amounts or a custom amount. This feature must be enabled on the merchant account.","enum":[true,false]},"presetPriceValues":{"type":"integer","description":"Preset amounts shown for FlexibleLink.","enum":[10,20,30]},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}},"IyziLinkCreateOrUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Created/updated link information.","properties":{"token":{"type":"string","description":"Token generated by iyzico."},"url":{"type":"string","description":"Purchase URL of the product."},"imageUrl":{"type":"string","description":"Product image URL."}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_add_product_sample.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/IyziLinkSample.java#L26">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/IyziLinkSample.cs#L12">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/iyzilink_create_product.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/3ifjsxa/1-create-product">Postman</a></td></tr></tbody></table>

## Create Fast Link

> Creates a Fast Link. Fast Link is a solution that enables quick and easy collection for payments up to 750 TRY. A Fast Link can be used only once. To create a Fast Link, you must first have an approved iyzico link.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/fast-link/products":{"post":{"tags":["iyzico Link"],"summary":"Create Fast Link","description":"Creates a Fast Link. Fast Link is a solution that enables quick and easy collection for payments up to 750 TRY. A Fast Link can be used only once. To create a Fast Link, you must first have an approved iyzico link.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkFastLinkRequest"}}}},"responses":{"200":{"description":"Successful creation response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateOrUpdateResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkFastLinkRequest":{"type":"object","required":["price","currencyCode"],"properties":{"conversationId":{"type":"string","description":"Value sent for request/response correlation."},"locale":{"type":"string","description":"Response language. Default **tr**.","enum":["tr","en"]},"description":{"type":"string","description":"Link description shown to the customer."},"price":{"type":"string","format":"decimal","description":"Product price."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]}}},"IyziLinkCreateOrUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Created/updated link information.","properties":{"token":{"type":"string","description":"Token generated by iyzico."},"url":{"type":"string","description":"Purchase URL of the product."},"imageUrl":{"type":"string","description":"Product image URL."}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_create_fastlink_sample.php">PHP</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/la0zxnb/2-fast-link">Postman</a></td></tr></tbody></table>

## Update iyzico Link

> Update an existing iyzico Link by using the token returned at creation time.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}":{"put":{"tags":["iyzico Link"],"summary":"Update iyzico Link","description":"Update an existing iyzico Link by using the token returned at creation time.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token value of the iyzico Link to be updated."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkUpdateRequest"}}}},"responses":{"200":{"description":"Successful update response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkCreateOrUpdateResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkUpdateRequest":{"type":"object","required":["name","description","price","currencyCode"],"description":"Fields that can be sent for link update (**token** is sent in the path).","properties":{"conversationId":{"type":"string","description":"Value used for request/response correlation."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"name":{"type":"string","description":"Product name."},"description":{"type":"string","description":"Product description."},"price":{"type":"string","format":"decimal","description":"Product price."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"encodedImageFile":{"type":"string","description":"Base64-encoded product image."},"addressIgnorable":{"type":"boolean","description":"Do not request/request address.","enum":[true,false]},"installmentRequested":{"type":"boolean","description":"Enable/disable installment sales.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}},"IyziLinkCreateOrUpdateResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Created/updated link information.","properties":{"token":{"type":"string","description":"Token generated by iyzico."},"url":{"type":"string","description":"Purchase URL of the product."},"imageUrl":{"type":"string","description":"Product image URL."}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_update_product_sample.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/IyziLinkSample.java#L54">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/IyziLinkSample.cs#L53">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/iyzilink_update_product.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/8mi20ck/4-update-product">Postman</a></td></tr></tbody></table>

## Get iyzico Link

> Query a single link by token. Returns the iyzico Link details for the given token.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}":{"get":{"tags":["iyzico Link"],"summary":"Get iyzico Link","description":"Query a single link by token. Returns the iyzico Link details for the given token.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token value of the iyzico Link to query."},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language (default **en**).","enum":["tr","en"]},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Request/response correlation value."}],"responses":{"200":{"description":"Product detail response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkDetailResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkDetailResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IyziLinkProduct"}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}},"IyziLinkProduct":{"type":"object","description":"iyzico Link product detail.","properties":{"name":{"type":"string","description":"Product name."},"conversationId":{"type":"string","description":"Merchant-side reference."},"description":{"type":"string","description":"Product description."},"price":{"type":"string","format":"decimal","description":"Product price (decimal)."},"currencyId":{"type":"integer","description":"Currency ID."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"token":{"type":"string","description":"Token generated by iyzico."},"productType":{"type":"string","description":"Product type.","enum":["IYZILINK","FASTLINK"]},"productStatus":{"type":"string","description":"Product status.","enum":["ACTIVE","PASSIVE"]},"merchantId":{"type":"integer","description":"Merchant ID."},"url":{"type":"string","description":"Purchase link."},"imageUrl":{"type":"string","description":"Product image."},"addressIgnorable":{"type":"boolean","description":"Do not request/request address.","enum":[true,false]},"soldCount":{"type":"integer","description":"Number of sold items."},"installmentRequested":{"type":"boolean","description":"Installment status.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"presetPriceValues":{"type":"array","description":"Preset price options.","items":{"type":"string","format":"decimal"}},"flexibleLink":{"type":"boolean","description":"Flexible priced link."},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_retrieve_product_sample.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/IyziLinkSample.java#L98">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/IyziLinkSample.cs#L103">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/iyzilink_retrieve_product.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/s7ubz0s/7-retrieve-product-by-token">Postman</a></td></tr></tbody></table>

## List iyzico Links

> Lists all created iyzico Links with pagination.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products":{"get":{"tags":["iyzico Link"],"summary":"List iyzico Links","description":"Lists all created iyzico Links with pagination.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language.","enum":["tr","en"]},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Page number."},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of items per page."},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Free-form field for request/response correlation."}],"responses":{"200":{"description":"Listing response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkListResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkListResponse":{"allOf":[{"$ref":"#/components/schemas/BasicStatusResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"listingReviewed":{"type":"boolean","description":"Status information for the listing operation."},"totalCount":{"type":"integer","description":"Total item count."},"currentPage":{"type":"integer","description":"Current page."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Product list.","items":{"$ref":"#/components/schemas/IyziLinkProduct"}}}}}}]},"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}},"IyziLinkProduct":{"type":"object","description":"iyzico Link product detail.","properties":{"name":{"type":"string","description":"Product name."},"conversationId":{"type":"string","description":"Merchant-side reference."},"description":{"type":"string","description":"Product description."},"price":{"type":"string","format":"decimal","description":"Product price (decimal)."},"currencyId":{"type":"integer","description":"Currency ID."},"currencyCode":{"type":"string","description":"Currency code.","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"token":{"type":"string","description":"Token generated by iyzico."},"productType":{"type":"string","description":"Product type.","enum":["IYZILINK","FASTLINK"]},"productStatus":{"type":"string","description":"Product status.","enum":["ACTIVE","PASSIVE"]},"merchantId":{"type":"integer","description":"Merchant ID."},"url":{"type":"string","description":"Purchase link."},"imageUrl":{"type":"string","description":"Product image."},"addressIgnorable":{"type":"boolean","description":"Do not request/request address.","enum":[true,false]},"soldCount":{"type":"integer","description":"Number of sold items."},"installmentRequested":{"type":"boolean","description":"Installment status.","enum":[true,false]},"stockEnabled":{"type":"boolean","description":"Enable/disable stock control.","enum":[true,false]},"stockCount":{"type":"integer","description":"Stock quantity."},"presetPriceValues":{"type":"array","description":"Preset price options.","items":{"type":"string","format":"decimal"}},"flexibleLink":{"type":"boolean","description":"Flexible priced link."},"categoryType":{"type":"string","description":"Product category type. Default value is \"UNKNOWN\".","enum":["GOLD","FOOD","PHONE","UNKNOWN","PC","TABLET"]}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_retrieve_products_sample.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/IyziLinkSample.java#L77">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/IyziLinkSample.cs#L82">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/iyzilink_retrieve_product_list.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/tc8nx98/5-search-merchant-products">Postman</a></td></tr></tbody></table>

## Update Link Status

> Sets an iyzico link’s status to \*\*ACTIVE\*\* or \*\*PASSIVE\*\*. Requires the link token and the new status value.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}/status/{status}":{"patch":{"tags":["iyzico Link"],"summary":"Update Link Status","description":"Sets an iyzico link’s status to **ACTIVE** or **PASSIVE**. Requires the link token and the new status value.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token of the iyzico link."},{"name":"status","in":"path","required":true,"schema":{"type":"string","enum":["ACTIVE","PASSIVE"]},"description":"New status to set."},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language (default **en**).","enum":["tr","en"]},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Request/response correlation value."}],"responses":{"200":{"description":"Status update result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicStatusResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"BasicStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Request result.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["en","tr"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_update_product_status.php">PHP</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/aoxgv8g/3-update-product-status">Postman</a></td></tr></tbody></table>

## Delete iyzico Link

> Deletes an iyzico Link.

```json
{"openapi":"3.0.3","info":{"title":"iyzilink API","version":"1.1.1"},"tags":[{"name":"iyzico Link","description":"Pay by link (iyzico Link)"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/iyzilink/products/{token}":{"delete":{"tags":["iyzico Link"],"summary":"Delete iyzico Link","description":"Deletes an iyzico Link.","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token of the link to delete."},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Response language (default **en**).","enum":["tr","en"]},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Request/response correlation value."}],"responses":{"200":{"description":"Deletion result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IyziLinkDeleteResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Signature value starting with IYZWSv2 (Base64).\n","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Request body content type.","schema":{"type":"string","enum":["application/json"]}}},"schemas":{"IyziLinkDeleteResponse":{"type":"object","properties":{"status":{"type":"string","description":"Operation result.","enum":["success","failure"]},"systemTime":{"type":"integer","description":"Unix timestamp (ms)."},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Echoed back if sent with the request."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/iyzilink_delete_product_sample.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/IyziLinkSample.java#L119">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/IyziLinkSample.cs#L125">.Net</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-python/blob/master/samples/iyzilink_delete_product.py">Python</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/o6mw1da/6-delete-product">Postman</a></td></tr></tbody></table>


# Shopping Credit

{% embed url="<https://www.youtube.com/watch?v=J7z5TAeElKA>" %}

**Shopping credit** is an alternative payment method that allows shopping in many different sectors, from clothing to cosmetics, from electronic devices to stationery needs, with installments up to 36 months.

Through iyzico, the banks included in **Pay with iyzico** can offer the option of paying with **Shopping Credit** to both existing customers of the banks and those who will become new customers of the bank through the flow of becoming digital customers.

<div><figure><img src="/files/YGXmGIeWWaksjAOAWCCL" alt=""><figcaption></figcaption></figure> <figure><img src="/files/bJkqtl2Ve79m8s3MCklg" alt=""><figcaption></figcaption></figure> <figure><img src="/files/rdDiyu2gN7oaGZ4Yvdua" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/FHXWkFTgmcrCWOxN4x9A" alt=""><figcaption></figcaption></figure> <figure><img src="/files/XLJm7RHAsIiQaBQ44LX8" alt=""><figcaption></figcaption></figure> <figure><img src="/files/BrmQs05VAxoSGrWlfnL6" alt=""><figcaption></figcaption></figure></div>


# Shopping Credit Implementation

When customers click on the bank they choose among the banks listed in **Pay with iyzico** and select the "Continue to Bank Screen" button, a payment form will be created. In order to enable the Shopping Credit payment method, a few adjustments must be made within the integration for member businesses that currently have **Pay with iyzico** integration.

### Steps

* [Initialize Shopping Credit](/en/products/shopping-credit/shopping-credit-implementation/initialize-shopping-credit)
* [Retrieve Shopping Credit](/en/products/shopping-credit/shopping-credit-implementation/retrieve-shopping-credit)


# Initialize Shopping Credit

The **payWithIyzicoPageUrl** value you will receive as a result of the request shown below is a unique page to which end users will be directed so that they can use shopping credit with iyzico. After the end user completes the shopping credit process, they are automatically directed to the callBackUrl address you specified during the request.

The created link can be displayed on the payment page with a button. The **token** you will receive with the link can be stored at this stage or when it is sent to the **callBackUrl** address (in case it is advanced to the shopping credit process). The validity period of the resulting link and token values is **30 minutes**. If the process is not completed within this period, the token will expire. Inquiries can be made at any time for each token value at which the process starts.

Buyer parameters name, surname, email and gsmNumber must be real values. These values are important both for your technical integration and for the end users' experience on the payment form page. These values are shown as default in the input fields on the **Pay with iyzico** page.

{% hint style="info" %}
**NOTE :** callBackUrl address must have SSL.
{% endhint %}

&#x20;

{% hint style="danger" %}
**NOTE :** Within the scope of shopping credit regulation, shopping credit cannot be used for products in the Gold category, but Shopping Credit can be provided with a limited number of installments for Mobile Phone, Computer and Tablet products. Therefore, if one of the products in the basket is one of these products, the relevant value must be sent in the category1(BasketItem) field in accordance with the regulation.
{% endhint %}

For the product value in the cart:

1. Gold is "GOLD",
2. Food is “FOOD”,
3. Mobile phone is “PHONE”,
4. “PC” if the computer is a desktop or laptop,
5. Tablet means "TABLET"

Their values are expected to be sent in the category1(BasketItem) field. Values sent for all product categories other than these are marked as **OTHER** by us. Apart from these, businesses can continue to send the values they currently send for product categories. There is no case sensitive requirement for these values.

{% hint style="info" %}
**NOTE :** The prices of products with the same id (BasketItem) in the same category in the basket must also be the same.
{% endhint %}

### Initialize Shopping Credit Request

You can access the **Pay with iyzico** Initiation document, which you will use to initiate a Shopping Credit, by clicking on the card below.

<table data-card-size="large" data-view="cards"><thead><tr><th data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/1e7zLBPzmy24AuSYx0jD">/pages/1e7zLBPzmy24AuSYx0jD</a></td></tr></tbody></table>


# Retrieve Shopping Credit

The shopping credit inquiry process consists of 2 stages. Therefore, it is important to integrate the 2 inquiry methods mentioned below in order to successfully display the result of the credit process to the end user at all stages.

### Steps

1. [Shopping Credit Retrieve (CallbackURL)](#step-1-shopping-credit-retrieve-callbackurl)
2. [Shopping Credit Retrieve (Webhook)](#step-2-shopping-credit-retrieve-webhook)

### Step 1 - Shopping Credit Retrieve (CallbackURL)

Since the Shopping Credit process is an asynchronous process, the credit process may have different statuses. In these cases, when the token value sent to the callbackURL address given when creating the payment form is queried by the merchant, **INIT\_CREDIT** and **PENDING\_CREDIT** statuses will be returned to the **paymentStatus** field from the parameters returned from the service. It is expected that these two values can be read by the workplace and the relevant action can be taken.

When the button continues to the selected bank screen, the bank screen will be redirected and the **paymentStatus** parameter **INIT\_CREDIT** value will be set. This status status, which is initiated when the customer clicks the continue button on the bank screen, will be set as status **FAILURE** by iyzico after a maximum of **20 minutes** if no action is taken on the screens. The validity period of the bank screen is maximum 20 minutes.

If the credit transaction falls into the flow of becoming a new customer on the bank's side, **PENDING\_CREDIT** status will be returned from the service when the **paymentStatus** field is queried. The process of becoming a new customer can take up to 65 minutes on the bank's side.

{% hint style="info" %}
**NOTE :** Depending on the credit response from the bank, it is recommended that our member businesses carry out stock tracking and control within a maximum of 1 hour.
{% endhint %}

#### Retrieve Shopping Credit Request (CallbackURL)

You can access the **Pay with iyzico** Inquiry document, which you will use to inquire about Shopping Credit via callback address, by clicking on the card below.

<table data-card-size="large" data-view="cards"><thead><tr><th data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/o8rrivywBSkUe2Iklazy">/pages/o8rrivywBSkUe2Iklazy</a></td></tr></tbody></table>

For the end user who has successfully completed the shopping credit process via **Pay with iyzico**, when the relevant token value is queried, if the **paymentStatus** value in the response is **SUCCESS**, the shopping credit process has been successfully completed. If the application fails, the relevant value will be returned as **FAILURE**.

### Step 2 - Shopping Credit Retrieve (Webhook)

You can access the document you will use to inquire about Shopping Credit via webhook by clicking on the card below.

<table data-card-size="large" data-view="cards"><thead><tr><th data-type="content-ref"></th></tr></thead><tbody><tr><td><a href="/pages/D4sw9FYPFYY9giDnbiZd">/pages/D4sw9FYPFYY9giDnbiZd</a></td></tr></tbody></table>

The Shopping Credit flow is structurally an asynchronous process. For this reason, it is necessary to successfully monitor the completion of the relevant process during the completion of the process. In this entire process, in addition to the checks to be made by the member business with the **iyzico Webhook Notification system** integration, iyzico sends JSON Payload via HTTP 15 seconds after the transaction for each payment event. This request repeats up to **3 times at 10-minute** intervals unless a **200 response** is received from your application and notifies the merchant of the result of the relevant credit process.

For payments received through the iyzico payment form, since the payment result is transmitted through the browser, payments that cannot be captured due to user/browser or server fluctuations can be captured with the webhook solution. When the webhook is opened for your account, the system also sends the token and payment status to the URL you specify. When the token information received via the browser cannot be accessed, the token information received via notification can be processed into the system. If the token sent through the browser has been captured and processed, the notification may be ignored.

The webhook solution can also be used to activate your services such as analysis, alerting and reporting.

{% hint style="info" %}
**NOTE :** Companies that do not perform Notification Validation must send a retrieve request to verify after receiving the webhook notification.
{% endhint %}

**Notification Validation**

The **X-IYZ-SIGNATURE** value sent in the header can be used to validate that the request came from iyzico.

The **X-IYZ-SIGNATURE** value is obtained by combining and hashing the following parameters as strings in the given order.

**Validation for Shopping Credit**

The Secret Key you have, the eventType and token information sent with the notification are combined as a string and hashed with Sha1. The base64 enconde output of the result received should be equal to the **X-IYZ-SIGNATURE** value.

<table><thead><tr><th width="125">No</th><th width="216">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>secretKey</td><td>Security key owned by the member business</td></tr><tr><td>2</td><td>iyziEventType</td><td><p>Specifies the request type. Values it can take :<br>- CREDIT_PAYMENT_INIT,<br>- CREDIT_PAYMENT_PENDING,</p><p>- CREDIT_PAYMENT_AUTH</p></td></tr><tr><td>3</td><td>token</td><td>Token information produced for the relevant payment</td></tr></tbody></table>

**Hash Structure for "Pay with iyzico" and Shopping Credit**

```
final String stringToBeHashed = new StringBuilder("secretKey")
.append(request.getIyziEventType())
.append(request.getToken()) .toString();
```

The created string is formatted as base64 encode.

```
String hash = Base64.encodeBase64String(DigestUtils.sha1(stringToBeHashed));
```




---

[Next Page](/llms-full.txt/1)