Init 3DS
Init 3DS API is responsible for processing the customer's card payments with 3DS.
As like Its ancestor NON-3DS;
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, 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.
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.
Init 3DS Request
POST
https://api.iyzipay.com/payment/3dsecure/initialize
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 |
callbackUrl* | String | Redirection URL |
Init 3DS Response
Output Name | Type | Description |
---|---|---|
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 |
threeDSHtmlContent | String | 3D verification screen in HTML format |
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
andpaymentTransactionId
values should be stored for future reference and tracking.In the event of a failed transaction (
failure
status), theerrorCode
,errorMessage
, anderrorGroup
parameters will be returned with corresponding values, providing details about the error.
Last updated