3DS Başlatma

3DS Başlatma API’si müşterinin kart ödemelerinin 3DS ile işlenmesinden sorumludur.

NON-3DS entegrasyonunda olduğu gibi;

TROY, MASTERCARD, VISA ve AMEX markalı kartlarla yapılan işlemleri destekler.
BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, ADVANTAGE gibi taksit programlarına katılmış olan kartlara 2, 3, 6, 9 ve 12 taksit seçenekleri sunulmaktadır.
Panelde başarılı işlemler yeşil renkte, başarısız işlemler ise kırmızı renkte görüntülenir.
Üye iş yeri, conversationId ve basketId parametrelerini kendi tarafında sipariş numarası olarak kullanabilir.

Bu özellikleri birleştirerek müşterilerinize, işlemlerinin başarısı veya başarısızlığı hakkında gerçek zamanlı geri bildirim sağlayarak kusursuz bir ödeme deneyimi sağlayabilirsiniz.

3DS Başlatma İsteği

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

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

3DS Başlatma Dönen Parametreler

Output Name	Type	Description
status	String	Servis yanıt sonucu (başarılı/başarısız)
errorCode	String	Hata kodu
errorMessage	String	Hata Mesajı
errorGroup	String	Hata Grubu
locale	String	Dil (default: tr)
systemTime	Long	Zaman Değeri
conversationId	String	Ayarlanırsa istek ve yanıtla eşleşecek konuşma kimliği
threeDSHtmlContent	String	HTML formatında 3D doğrulama ekranı

Output Name

Type

Description

status

String

Servis yanıt sonucu (başarılı/başarısız)

errorCode

String

Hata kodu

errorMessage

String

Hata Mesajı

errorGroup

String

Hata Grubu

locale

String

Dil (default: tr)

systemTime

Long

Zaman Değeri

conversationId

String

Ayarlanırsa istek ve yanıtla eşleşecek konuşma kimliği

threeDSHtmlContent

String

HTML formatında 3D doğrulama ekranı

Son olarak aşağıdaki başlıkları analiz ederek, ödeme sorgusunun sonucunu etkili bir şekilde yönetebilir ve yanıtlayabilirsiniz, böylece müşterileriniz için sorunsuz ve güvenilir bir ödeme süreci sağlayabilirsiniz.

status parametresi işlemin durumu hakkında bilgi sağlar. success, işlemin başarıyla tamamlandığını ve ödemenin işlendiğini gösterir. failure, işlemin başarısız olduğunu belirtir ve başarısızlığın nedenine ilişkin bir hata mesajı verilir.
Bu hizmet için paymentStatus parametresi boştur.
paymentId ve paymentTransactionId değerleri, ileride referans noktası olarak kullanılabileceği için saklanmalıdır.
Başarısız bir işlem durumunda (failure durumu), errorCode, errorMessage ve errorGroup parametreleri, hatayla ilgili ayrıntıları sağlayarak ilgili değerlerle birlikte döndürülür.

Last updated 2 months ago