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

POST https://api.iyzipay.com/payment/preauth

Request Body

Name	Type	Description
price*	Decimal	Total amount of basket. The sum of basket items’ amount must be equal to the price of basket
contactName(BillingAddress)*	String	Contact name of billing address
registrationAddress(Buyer)*	String	Registration address of buyer
ip(Buyer)*	String	IP of buyer
email(Buyer)*	String	Email of buyer
country(Buyer)*	String	Country of buyer
city(Buyer)*	String	City of buyer
identityNumber(Buyer)*	String	Identity number of buyer. TCKN for Turkish merchants, passport number for foreign merchants
surname(Buyer)*	String	Surname of buyer
name(Buyer)*	String	Name of buyer
id(Buyer)*	String	ID of buyer.
cardHolderName*	String	Name of the card owner
cvc*	String	4 (AMEX) or 3 (VISA, MC, TROY) digits card verification code
expireMonth*	String	Expiration month of the card (2 digits)
expireYear*	String	Expiration year of the card
cardNumber*	String	15 (AMEX) or 16 (VISA, MC) digits card number
installment*	Integer	Installment value. For single installment payments it should be 1 (valid values: 1, 2, 3, 6, 9, 12)
currency*	String	Currency (default: TRY). Alternatively, you can set USD, EUR, GBP and IRR
paidPrice*	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)*	String	Address details of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory
country(ShippingAddress)*	String	Country name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory
city(ShippingAddress)*	String	City name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory
contactName(ShippingAddress)*	String	Contact name of shipping address. If one of the itemType in basket is PHYSICAL, then this parameter will be mandatory
address(BillingAddress)*	String	Address details of billing address
country(BillingAddress)*	String	Country name of billing address
city(BillingAddress)*	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.