.svg?alt=media&token=17ec6f8f-ac20-4c93-8c47-630298706a48)
Create PreAuth Payment
Last updated
Last updated
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.
POST https://api.iyzipay.com/payment/preauth
| Name | Type | Description |
|---|---|---|
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.
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
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