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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iyzico.com/en/payment-methods/preauth-and-capture/non-3ds/non-3ds-implementation/create-preauth-payment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.