kt.vpos¶
Sanal POS · 15 uç nokta
Asenkron istemcide (AsyncKuveytTurk) aynı metotlar await ile çağrılır. Her metot ayrıca extra_query, extra_body ve request_options kabul eder (ayrıntı).
| Metot | İstek | Akış | Sandbox | Canlı |
|---|---|---|---|---|
add_card_to_merchant_safe |
POST /v1/vpos/addCardToMerchantSafe |
CC | test edilmedi | test edilmedi |
digital_payment_commission_reconciliation |
POST /v1/vpos/commissionReconciliation |
CC | test edilmedi | test edilmedi |
get_customer_by_safe_key |
POST /v1/vpos/getCustomerBySafeKey |
CC | test edilmedi | test edilmedi |
get_seller_order_details |
POST /v1/vpos/getMerchantOrderDetail |
CC | kısmen test edildi | test edilmedi |
non_3_d_payment |
POST /v1/vpos/non3DPayment |
CC | test edilmedi | test edilmedi |
non_three_d_payment_by_merchant_safe |
POST /v1/vpos/nonThreeDPaymentByMerchantSafe |
CC | test edilmedi | test edilmedi |
order_detail_with_payment_id |
POST /v1/vpos/orderDetailWithPaymentId |
CC | kısmen test edildi | test edilmedi |
payment_order_reversal |
POST /v1/vpos/paymentOrderReversal |
CC | test edilmedi | test edilmedi |
pre_authorization |
POST /v1/vpos/preAuthorization |
CC | test edilmedi | test edilmedi |
recurring_non_three_d_payment |
POST /v1/vpos/recurringNonThreeDPayment |
CC | test edilmedi | test edilmedi |
sale_order_reversal |
POST /v1/vpos/saleOrderReversal |
CC | test edilmedi | test edilmedi |
secure_partner_payment |
POST /v1/vpos/secureCommonPaymentToken |
CC | test edilmedi | test edilmedi |
threee_d_payment |
POST /v1/vpos/threeDPayment |
CC | test edilmedi | test edilmedi |
virtual_pos_non_three_d_payment |
POST /v1/vpos/nonThreeDPayment |
CC | test edilmedi | test edilmedi |
virtual_pos_sale_reversal |
POST /v1/vpos/saleReversal |
CC | test edilmedi | test edilmedi |
add_card_to_merchant_safe¶
addCardToMerchantSafe · POST /v1/vpos/addCardToMerchantSafe · kapsam public · client credentials
This API is used to securely store a customer’s card information in the payment system for use in merchant-safe Non-3D Secure payment flows.
yanit = kt.vpos.add_card_to_merchant_safe(merchant_id=..., customer_id=..., user_name=..., hash_data=..., merchant_order_id=..., payment_customer_id=..., card_number=..., card_expire_date_month=..., card_expire_date_year=..., card_cvv2=..., card_holder_name=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
business_key |
businessKey |
gövde | sayı | Business key value associated with the merchant-safe card registration process. | |
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
payment_customer_id |
paymentCustomerId |
gövde | tam sayı | evet | Payment customer identifier to which the card will be linked. |
payment_definition_id |
paymentDefinitionId |
gövde | tam sayı | Payment definition identifier associated with the customer payment setup. | |
customer_definition_id |
customerDefinitionId |
gövde | tam sayı | Customer definition identifier associated with the merchant customer record. | |
customer_name |
customerName |
gövde | metin | Name of the customer whose card information will be stored. | |
adress_text |
adressText |
gövde | metin | Address text of the customer. | |
phone_number |
phoneNumber |
gövde | metin | Phone number of the customer. | |
email_adress |
emailAdress |
gövde | metin | Email address of the customer. | |
district |
district |
gövde | metin | District information of the customer address. | |
city |
city |
gövde | metin | City information of the customer address. | |
country |
country |
gövde | metin | Country information of the customer address. | |
postal_code |
postalCode |
gövde | metin | Postal code of the customer address. | |
fax_number |
faxNumber |
gövde | metin | Fax number of the customer. | |
extra_field1 |
extraField1 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field2 |
extraField2 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field3 |
extraField3 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field4 |
extraField4 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field5 |
extraField5 |
gövde | metin | Additional field reserved for merchant-specific information. | |
merchant_customer_id |
merchantCustomerId |
gövde | tam sayı | Merchant-side customer identifier. | |
card_number |
cardNumber |
gövde | metin | evet | Card number to be stored in the merchant-safe payment system. |
card_expire_date_month |
cardExpireDateMonth |
gövde | metin | evet | Expiration month of the card. |
card_expire_date_year |
cardExpireDateYear |
gövde | metin | evet | Expiration year of the card. |
card_cvv2 |
cardCvv2 |
gövde | metin | evet | CVV2 security code of the card. |
card_holder_name |
cardHolderName |
gövde | metin | evet | Name of the cardholder. |
safe_key |
safeKey |
gövde | metin | Existing or generated safe key value associated with the stored card. | |
sort_number |
sortNumber |
gövde | tam sayı | Sort order value for the stored card record. | |
is_active |
isActive |
gövde | bool | Indicates whether the stored card record is active. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): CardId, PaymentCustomerId, SafeKey, ResponseCode, ResponseMessage
digital_payment_commission_reconciliation¶
Digital Payment Commission Reconciliation · POST /v1/vpos/commissionReconciliation · kapsam digital_payments · client credentials
Performs commission reconciliation for digital payment transactions by using the provided transaction list. The response returns reconciliation status information for each transaction, including transaction identifier, status code, status message, and commission type.
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
transaction_list |
transactionList |
gövde | liste | evet | List of digital payment transactions to be included in commission reconciliation. |
Yanıt alanları (dokümana göre): transactionId, statusCode, statusMessage, commissionType
get_customer_by_safe_key¶
getCustomerBySafeKey · POST /v1/vpos/getCustomerBySafeKey · kapsam public · client credentials
This API is used to retrieve payment customer card information defined in the payment system by using a given safeKey.
yanit = kt.vpos.get_customer_by_safe_key(merchant_id=..., customer_id=..., payment_customer_id=..., user_name=..., hash_data=..., safe_key=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
payment_customer_id |
paymentCustomerId |
gövde | tam sayı | evet | Payment customer identifier associated with the stored card. |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
safe_key |
safeKey |
gövde | metin | evet | Safe key used to find the payment customer card information. |
host_ip |
hostIp |
gövde | metin | Host IP address from which the request is initiated. | |
card_holder_ip_address |
cardHolderIpAddress |
gövde | metin | IP address of the cardholder. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): CardId, PaymentCustomerId, CardNumber, ExpiryDate, SortNumber, IsActive, CVV2, CVV2Encrypted, CardHolderName, SafeKey, MerchantId
get_seller_order_details¶
Get Seller Order Details · POST /v1/vpos/getMerchantOrderDetail · kapsam public · client credentials
The Get Merchant Order Detail API allows merchants to query payment and transaction details for their Virtual POS orders. It returns order status, transaction status, amount details, card information, terminal information, and additional transaction metadata for the requested criteria.
yanit = kt.vpos.get_seller_order_details(merchant_id=..., customer_id=..., user_name=..., hash_data=..., start_date=..., end_date=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | kısmen test edildi | erişilebilir, parametre/iş kuralı hatası — Müşteri no giriniz. | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
order_id |
orderId |
gövde | metin | Order identifier used to query a specific order. | |
merchant_order_id |
merchantOrderId |
gövde | metin | Unique order identifier generated by the merchant. | |
hash_data |
hashData |
gövde | metin | evet | Hash value generated with transaction information and validated by the bank. |
start_date |
startDate |
gövde | tarih | evet | Start date for querying merchant order details. Format: dd.MM.yyyy. |
end_date |
endDate |
gövde | tarih | evet | End date for querying merchant order details. Format: dd.MM.yyyy. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, MerchantOrderId, MerchantId, CardHolderName, CardType, CardNumber, OrderDate, OrderStatus, LastOrderStatus, OrderType, TransactionStatus, FirstAmount, CancelAmount, DrawbackAmount, ClosedAmount, FEC, VPSEntryMode, InstallmentCount, TransactionSecurity, ResponseCode, ResponseExplain, EndOfDayStatus, TransactionSide, CardHolderIPAddress, MerchantIPAddress, MerchantUserName, ProvNumber, BatchId, CardExpireDate, CVV2, PosTerminalId, Explain, Explain2, Explain3, RRN, Stan, UserName, Host_Name, SystemDate, UpdateUserName, UpdateHostName, UpdateSystemDate, EndOfDayDate, HostIP, LastOrderStatusDescription, OrderTypeDescription, TransactionStatusDescription, EndOfDayStatusDescription, FecDescription, TransactionSecurityDescription, FECAmount, IdentityTaxNumber, QueryId, DebtId, DebtorName, Period, SurchargeAmount, SGKDebtAmount, DeferringCount
non_3_d_payment¶
NON 3D Payment · POST /v1/vpos/non3DPayment · kapsam public · client credentials
This API is used to process Non-3D Secure Virtual POS payments. In Non-3D payment transactions, the payment is completed using the customer’s card information without performing 3D Secure verification. The card and merchant must be authorized for Non-3D Secure payment processing.
yanit = kt.vpos.non_3_d_payment(merchant_id=..., customer_id=..., user_name=..., amount=..., merchant_order_id=..., currency=..., hash_data=..., installment_count=..., deferring_count=..., card_number=..., card_expire_date_year=..., card_expire_date_month=..., card_cvv2=..., card_holder_name=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
amount |
amount |
gövde | metin | evet | Transaction amount. For example, 100 should be sent for 1.00 TL and 123450 should be sent for 1,234.50 TL. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
currency |
currency |
gövde | metin | evet | Currency code of the transaction amount. For TL, it should be sent as 0949. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated with transaction information and validated by the bank. |
installment_count |
installmentCount |
gövde | tam sayı | evet | Number of installments for the payment transaction. |
deferring_count |
deferringCount |
gövde | tam sayı | evet | Number of deferment periods for the payment transaction. |
card_number |
cardNumber |
gövde | metin | evet | Card number to be used for the Non-3D payment transaction. |
card_expire_date_year |
cardExpireDateYear |
gövde | metin | evet | Expiration year of the card. |
card_expire_date_month |
cardExpireDateMonth |
gövde | metin | evet | Expiration month of the card. |
card_cvv2 |
cardCvv2 |
gövde | metin | evet | CVV2 security code of the card. |
card_holder_name |
cardHolderName |
gövde | metin | evet | Name of the cardholder. |
vpos_sub_merchant_id |
vposSubMerchantId |
gövde | tam sayı | Sub-merchant identifier for the Virtual POS transaction. | |
bkm_id |
bkmId |
gövde | metin | BKM identifier related to the payment transaction. | |
pf_sub_merchant_terminal_id |
pfSubMerchantTerminalId |
gövde | metin | Payment facilitator sub-merchant terminal identifier. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, MerchantOrderId, ProvisionNumber, RRN, Stan, ResponseCode, ResponseMessage
non_three_d_payment_by_merchant_safe¶
nonThreeDPaymentByMerchantSafe · POST /v1/vpos/nonThreeDPaymentByMerchantSafe · kapsam public · client credentials
This API is used for merchant-approved Non-3D payment processing by using a card stored with a merchant-safe key.
yanit = kt.vpos.non_three_d_payment_by_merchant_safe(merchant_id=..., customer_id=..., payment_customer_id=..., merchant_order_id=..., user_name=..., hash_data=..., amount=..., currency=..., safe_key=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
payment_customer_id |
paymentCustomerId |
gövde | tam sayı | evet | Payment customer identifier associated with the stored card. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
amount |
amount |
gövde | metin | evet | Transaction amount to be collected. |
currency |
currency |
gövde | metin | evet | Currency code of the transaction amount. |
installment_count |
installmentCount |
gövde | tam sayı | Number of installments for the payment transaction. | |
deferring_count |
deferringCount |
gövde | tam sayı | Number of deferment periods for the payment transaction. | |
safe_key |
safeKey |
gövde | metin | evet | Merchant-safe key of the stored card to be used for the Non-3D payment. |
description |
description |
gövde | metin | Description of the Non-3D payment transaction. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, ProvisionNumber, RRN, Stan, ResponseCode, ResponseMessage
order_detail_with_payment_id¶
Order Detail With Payment Id · POST /v1/vpos/orderDetailWithPaymentId · kapsam public · client credentials
This API is used to query the details of collections created under a payment instruction. It returns payment, order, amount, status, terminal, authorization, and additional transaction details by using paymentId and related query parameters.
yanit = kt.vpos.order_detail_with_payment_id(merchant_id=..., customer_id=..., user_name=..., hash_data=..., amount=..., payment_id=..., parent_payment_id=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | kısmen test edildi | erişilebilir, parametre/iş kuralı hatası — Müşteri no giriniz. | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier registered in the Kuveyt Türk Virtual POS service. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
order_id |
orderId |
gövde | tam sayı | Order identifier used to query a specific order. | |
merchant_order_id |
merchantOrderId |
gövde | metin | Merchant-side transaction or order number. This field may be sent empty for this API. | |
start_date |
startDate |
gövde | tarih | Start date for querying order details. Format: dd.MM.yyyy. | |
end_date |
endDate |
gövde | tarih | End date for querying order details. Format: dd.MM.yyyy. | |
hash_data |
hashData |
gövde | metin | evet | Hash value generated with payment transaction information and validated by the bank. |
amount |
amount |
gövde | sayı | evet | Transaction amount. This field should be sent as 0 for this method. |
ok_url |
okUrl |
gövde | metin | URL to which the user is redirected after successful card verification in secure payment transactions. | |
fail_url |
failUrl |
gövde | metin | URL to which the result is sent if card verification fails or an error occurs. | |
payment_id |
paymentId |
gövde | tam sayı | evet | Payment identifier used to query collection details. |
parent_payment_id |
parentPaymentId |
gövde | tam sayı | evet | Parent payment identifier related to the payment instruction. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, ProvNumber, PaymentId, ParentPaymentId, MerchantId, MerchantOrderId, Amount, Currency, PaymentDate, PaymentStartDate, PaymentStatus, ResponseCode, ResponseDetail, ReverseAmount, DrawbackAmount, ClosedAmount, TerminalId, RRN, OrderStatus, AuthNumber, PeriodType, PeriodNumber, IterationCounter, IsActive, TotalIteration, RejectedRetryCount, RejectedPeriodNumber, RejectedPeriodType, LastTriedTime, LastTryCount, PaymentCustomerId, PaymentCardId, AdditionalData1, AdditionalData2, AdditionalData3
payment_order_reversal¶
paymentOrderReversal · POST /v1/vpos/paymentOrderReversal · kapsam public · client credentials
It is used to cancel a coming payment that has not yet been finalized or converted into a collected payment.
yanit = kt.vpos.payment_order_reversal(customer_id=..., merchant_id=..., hash_data=..., merchant_order_id=..., user_name=..., parent_payment_id=..., payment_id=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
transaction_type |
transactionType |
gövde | metin | Type of the transaction to be performed. | |
installment_count |
installmentCount |
gövde | tam sayı | Number of installments for the payment transaction. | |
amount |
amount |
gövde | tam sayı | Transaction amount. | |
display_amount |
displayAmount |
gövde | metin | Display amount value of the transaction. | |
cancel_amount |
cancelAmount |
gövde | sayı | Amount to be cancelled for the payment order reversal. | |
currency_code |
currencyCode |
gövde | metin | Currency code of the transaction amount. | |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
transaction_security |
transactionSecurity |
gövde | metin | Transaction security type or security level information. | |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
parent_payment_id |
parentPaymentId |
gövde | tam sayı | evet | Parent payment identifier of the related payment transaction. |
payment_id |
paymentId |
gövde | tam sayı | evet | Payment identifier of the coming payment to be reversed. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): ParentPaymentId, PaymentId, ResponseCode, ResponseMessage
pre_authorization¶
preAuthorization · POST /v1/vpos/preAuthorization · kapsam public · client credentials
This virtual POS service is used to obtain a preauthorization, which places a limit hold for a specified amount without charging the customer’s card.
yanit = kt.vpos.pre_authorization(merchant_id=..., customer_id=..., user_name=..., amount=..., merchant_order_id=..., currency=..., hash_data=..., card_number=..., card_expire_date_year=..., card_expire_date_month=..., card_cvv2=..., card_holder_name=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
amount |
amount |
gövde | metin | evet | Transaction amount for which preauthorization will be obtained. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
currency |
currency |
gövde | metin | evet | Currency code of the transaction amount. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
card_number |
cardNumber |
gövde | metin | evet | Card number to be used for the preauthorization transaction. |
card_expire_date_year |
cardExpireDateYear |
gövde | metin | evet | Expiration year of the card. |
card_expire_date_month |
cardExpireDateMonth |
gövde | metin | evet | Expiration month of the card. |
card_cvv2 |
cardCvv2 |
gövde | metin | evet | CVV2 security code of the card. |
card_holder_name |
cardHolderName |
gövde | metin | evet | Name of the cardholder. |
vpos_sub_merchant_id |
vposSubMerchantId |
gövde | tam sayı | Sub-merchant identifier for the Virtual POS transaction. | |
bkm_id |
bkmId |
gövde | metin | BKM identifier related to the payment transaction. | |
pf_sub_merchant_terminal_id |
pfSubMerchantTerminalId |
gövde | metin | Payment facilitator sub-merchant terminal identifier. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): MerchantOrderId, ProvisionNumber, RRN, Stan, ResponseCode, ResponseMessage
recurring_non_three_d_payment¶
recurringNonThreeDPayment · POST /v1/vpos/recurringNonThreeDPayment · kapsam public · client credentials
This API is used to create recurring Non-3D payment instructions for regular payment collection. It receives card, merchant, customer, payment schedule, and transaction details as request parameters.
yanit = kt.vpos.recurring_non_three_d_payment(merchant_order_id=..., merchant_id=..., customer_id=..., user_name=..., hash_data=..., amount=..., currency=..., card_number=..., card_expire_date_year=..., card_expire_date_month=..., card_cvv2=..., card_holder_name=..., customer_name=..., payment_start_date=..., iteration_counter=..., period_number=..., period_type=..., card_holder_customer_id=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
amount |
amount |
gövde | metin | evet | Recurring payment amount to be collected. |
currency |
currency |
gövde | metin | evet | Currency code of the recurring payment amount. |
installment_count |
installmentCount |
gövde | tam sayı | Number of installments for the payment transaction. | |
deferring_count |
deferringCount |
gövde | tam sayı | Number of deferment periods for the payment transaction. | |
card_number |
cardNumber |
gövde | metin | evet | Card number to be used for the recurring Non-3D payment. |
card_expire_date_year |
cardExpireDateYear |
gövde | metin | evet | Expiration year of the card. |
card_expire_date_month |
cardExpireDateMonth |
gövde | metin | evet | Expiration month of the card. |
card_cvv2 |
cardCvv2 |
gövde | metin | evet | CVV2 security code of the card. |
card_holder_name |
cardHolderName |
gövde | metin | evet | Name of the cardholder. |
description |
description |
gövde | metin | Description of the recurring payment instruction. | |
bkm_id |
bkmId |
gövde | metin | BKM identifier related to the payment transaction. | |
customer_name |
customerName |
gövde | metin | evet | Name of the customer associated with the recurring payment. |
payment_start_date |
paymentStartDate |
gövde | tarih | evet | Start date of the recurring payment instruction. |
iteration_counter |
iterationCounter |
gövde | tam sayı | evet | Number of payment iterations to be executed. |
period_number |
periodNumber |
gövde | tam sayı | evet | Period interval number for the recurring payment schedule. |
period_type |
periodType |
gövde | tam sayı | evet | Period type of the recurring payment schedule. |
card_holder_customer_id |
cardHolderCustomerId |
gövde | tam sayı | evet | Customer identifier of the cardholder. |
payment_definition_id |
paymentDefinitionId |
gövde | tam sayı | Payment definition identifier associated with the recurring payment setup. | |
adress_text |
adressText |
gövde | metin | Address text of the customer. | |
city |
city |
gövde | metin | City information of the customer address. | |
country |
country |
gövde | metin | Country information of the customer address. | |
district |
district |
gövde | metin | District information of the customer address. | |
email_adress |
emailAdress |
gövde | metin | Email address of the customer. | |
extra_field1 |
extraField1 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field2 |
extraField2 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field3 |
extraField3 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field4 |
extraField4 |
gövde | metin | Additional field reserved for merchant-specific information. | |
extra_field5 |
extraField5 |
gövde | metin | Additional field reserved for merchant-specific information. | |
fax_number |
faxNumber |
gövde | metin | Fax number of the customer. | |
merchant_customer_id |
merchantCustomerId |
gövde | tam sayı | Merchant-side customer identifier. | |
phone_number |
phoneNumber |
gövde | metin | Phone number of the customer. | |
postal_code |
postalCode |
gövde | metin | Postal code of the customer address. | |
customer_definition_id |
customerDefinitionId |
gövde | tam sayı | Customer definition identifier associated with the merchant customer record. | |
vpos_sub_merchant_id |
vposSubMerchantId |
gövde | tam sayı | Sub-merchant identifier for the Virtual POS transaction. | |
pf_sub_merchant_terminal_id |
pfSubMerchantTerminalId |
gövde | metin | Payment facilitator sub-merchant terminal identifier. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, PaymentId, PaymentCustomerId, MerchantOrderId, Amount, CurrencyCode, PaymentStartDate, IterationCounter, PeriodNumber, PeriodType, IsActive, PaymentStatus, ProvisionNumber, RRN, Stan, ResponseCode, ResponseMessage
sale_order_reversal¶
saleOrderReversal · POST /v1/vpos/saleOrderReversal · kapsam public · client credentials
It enables the complete reversal of a successful sale transaction by cancelling it before end-of-day settlement.
yanit = kt.vpos.sale_order_reversal(merchant_id=..., customer_id=..., user_name=..., amount=..., merchant_order_id=..., hash_data=..., sale_reversal_type=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | User name associated with the merchant integration. |
amount |
amount |
gövde | metin | evet | Transaction amount to be reversed. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated for transaction security and request validation. |
language |
language |
gövde | tam sayı | Language option used for the transaction response messages. | |
sale_reversal_type |
saleReversalType |
gövde | tam sayı | evet | Sale reversal type that identifies the reversal operation. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, MerchantOrderId, ProvisionNumber, RRN, Stan, ResponseCode, ResponseMessage
secure_partner_payment¶
Secure Partner Payment · POST /v1/vpos/secureCommonPaymentToken · kapsam public · client credentials
This API is used to generate a Secure Common Payment token for Virtual POS transactions. It allows merchants to redirect customers to Kuveyt Türk’s Secure Common Payment page, where the customer can complete the payment through supported 3D Secure or GO payment flows.
yanit = kt.vpos.secure_partner_payment(merchant_id=..., user_name=..., amount=..., merchant_order_id=..., currency_code=..., transaction_type=..., token_type=..., success_url=..., fail_url=..., hash_data=..., installment_count=..., client_ip=..., card_holder_ip=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
amount |
amount |
gövde | metin | evet | Transaction amount. For example, 100 should be sent for 1.00 TL and 123450 should be sent for 1,234.50 TL. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
currency_code |
currencyCode |
gövde | metin | evet | Currency code of the transaction amount. For TL, it should be sent as 0949. |
transaction_type |
transactionType |
gövde | metin | evet | Transaction type to be performed through the Secure Common Payment flow. |
token_type |
TokenType |
gövde | metin | evet | Token type that specifies the payment flow to be initiated. |
success_url |
successUrl |
gövde | metin | evet | URL to which the customer is redirected after successful payment or verification. |
fail_url |
failUrl |
gövde | metin | evet | URL to which the customer is redirected if payment or verification fails, or if an error occurs. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated with transaction information and validated by the bank. |
installment_count |
installmentCount |
gövde | tam sayı | evet | Number of installments for the payment transaction. |
order_description |
orderDescription |
gövde | metin | Description of the order. | |
client_ip |
clientIp |
gövde | metin | evet | IP address of the client initiating the request. |
card_holder_ip |
cardHolderIp |
gövde | metin | evet | IP address of the cardholder/customer who will open the Secure Common Payment page. |
email |
email |
gövde | metin | Email address of the cardholder/customer. | |
cc |
cc |
gövde | metin | Country or phone area code of the cardholder/customer. | |
subscriber |
subscriber |
gövde | metin | Phone number of the cardholder/customer. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): Url, ResponseCode, ResponseMessage
threee_d_payment¶
ThreeeD Payment · POST /v1/vpos/threeDPayment · kapsam public · client credentials
Virtual POS 3D Secure payment API is used to initiate an online card payment with 3D Secure verification. It returns HTML content that redirects the cardholder to the 3D Secure authentication flow, together with response code and response message information.
yanit = kt.vpos.threee_d_payment(merchant_id=..., customer_id=..., user_name=..., amount=..., merchant_order_id=..., currency=..., success_url=..., fail_url=..., hash_data=..., installment_count=..., deferring_count=..., card_number=..., card_expire_date_year=..., card_expire_date_month=..., card_cvv2=..., card_holder_name=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | Merchant identifier for the Virtual POS transaction. |
customer_id |
customerId |
gövde | tam sayı | evet | Customer identifier associated with the merchant. |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
amount |
amount |
gövde | metin | evet | Transaction amount. For example, 100 should be sent for 1.00 TL and 123450 should be sent for 1,234.50 TL. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
currency |
currency |
gövde | metin | evet | Currency code of the transaction amount. For TL, it should be sent as 0949. |
success_url |
successUrl |
gövde | metin | evet | URL to which the cardholder is redirected after successful 3D Secure verification. |
fail_url |
failUrl |
gövde | metin | evet | URL to which the cardholder is redirected if 3D Secure verification fails or an error occurs. |
hash_data |
hashData |
gövde | metin | evet | Hash value generated with transaction information and validated by the bank. |
installment_count |
installmentCount |
gövde | tam sayı | evet | Number of installments for the payment transaction. |
deferring_count |
deferringCount |
gövde | tam sayı | evet | Number of deferment periods for the payment transaction. |
description |
description |
gövde | metin | Description of the payment transaction. | |
card_number |
cardNumber |
gövde | metin | evet | Card number to be used for the 3D Secure payment transaction. |
card_expire_date_year |
cardExpireDateYear |
gövde | metin | evet | Expiration year of the card. |
card_expire_date_month |
cardExpireDateMonth |
gövde | metin | evet | Expiration month of the card. |
card_cvv2 |
cardCvv2 |
gövde | metin | evet | CVV2 security code of the card. |
card_holder_name |
cardHolderName |
gövde | metin | evet | Name of the cardholder. |
vpos_sub_merchant_id |
vposSubMerchantId |
gövde | tam sayı | Sub-merchant identifier for the Virtual POS transaction. | |
bkm_id |
bkmId |
gövde | metin | BKM identifier related to the payment transaction. | |
pf_sub_merchant_terminal_id |
pfSubMerchantTerminalId |
gövde | metin | Payment facilitator sub-merchant terminal identifier. |
Gövde alanları istekte request nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): HtmlContent, ResponseCode, ResponseMessage
virtual_pos_non_three_d_payment¶
Virtual POS NonThreeD Payment (Masked Card) · POST /v1/vpos/nonThreeDPayment · kapsam cards · client credentials
This API is used to perform Non-3D payment transactions through Virtual POS by using identity-tax number and payment information. It returns the payment transaction result and, if the transaction is successful, provision information.
yanit = kt.vpos.virtual_pos_non_three_d_payment(merchant_id=..., user_name=..., amount=..., merchant_order_id=..., card_number=..., currency_code=..., transaction_type=..., identity_tax_number=..., hash_data=..., installment_count=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | The merchant's registered merchant ID at the bank. |
customer_id |
customerId |
gövde | tam sayı | The merchant's customer account number. | |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
amount |
amount |
gövde | sayı | evet | Payment amount of the transaction. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
card_number |
cardNumber |
gövde | metin | evet | Card number used for the payment transaction. |
currency_code |
currencyCode |
gövde | metin | evet | Currency code of the transaction. For TL, it should be sent as 0949. |
transaction_type |
transactionType |
gövde | metin | evet | Transaction type. Sale: 1, Reversal: 6. |
identity_tax_number |
identityTaxNumber |
gövde | metin | evet | Customer identity number or tax number. |
hash_data |
hashData |
gövde | metin | evet | Hash value calculated for the transaction and validated by the bank. |
installment_count |
installmentCount |
gövde | tam sayı | evet | Number of installments for the payment transaction. |
description |
description |
gövde | metin | Description of the payment transaction. | |
insurance_deferring_count |
insuranceDeferringCount |
gövde | tam sayı | Insurance deferring count for the payment transaction. |
Gövde alanları istekte APIPaymentTransactionContract nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, ProvisionNumber, MerchantOrderId, ResponseCode, ResponseMessage, RRN, Stan, ExecutionReferenceId, IsEnrolled, TransactionTime, Password
virtual_pos_sale_reversal¶
Virtual POS Sale Reversal (Masked) · POST /v1/vpos/saleReversal · kapsam cards · client credentials
This API is used to reverse a sales transaction performed through Virtual POS. A sales transaction can be cancelled on the same day before settlement. It returns the reversal transaction result and related authorization information.
yanit = kt.vpos.virtual_pos_sale_reversal(merchant_id=..., user_name=..., amount=..., merchant_order_id=..., currency_code=..., transaction_type=..., order_id=..., provision_number=..., r_rn=..., stan=..., hash_data=...)
| Ortam | Durum | Sonuç | Tarih |
|---|---|---|---|
| Sandbox | test edilmedi | işlem yapan uç nokta; otomatik test edilmez | 2026-10-04 |
| Canlı | test edilmedi | henüz denenmedi |
| Parametre | API'deki adı | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|---|
merchant_id |
merchantId |
gövde | tam sayı | evet | The merchant's registered merchant ID at the bank. |
customer_id |
customerId |
gövde | tam sayı | The merchant's customer account number. | |
user_name |
userName |
gövde | metin | evet | API user name associated with the merchant integration. |
amount |
amount |
gövde | sayı | evet | Reversal amount of the transaction. |
merchant_order_id |
merchantOrderId |
gövde | metin | evet | Unique order identifier generated by the merchant. |
currency_code |
currencyCode |
gövde | metin | evet | Currency code of the transaction. For TL, it should be sent as 0949. |
transaction_type |
transactionType |
gövde | tam sayı | evet | Transaction type. Sale: 1, Reversal: 6. |
order_id |
orderId |
gövde | tam sayı | evet | Unique order number of the transaction to be reversed. |
provision_number |
provisionNumber |
gövde | metin | evet | Provision number of the transaction to be reversed. |
r_rn |
rRN |
gövde | metin | evet | RRN number of the transaction to be reversed. |
stan |
stan |
gövde | metin | evet | STAN number of the transaction to be reversed. |
description |
description |
gövde | metin | Description of the reversal transaction. | |
hash_data |
hashData |
gövde | metin | evet | Hash value calculated for the transaction and validated by the bank. |
Gövde alanları istekte APIPaymentTransactionContract nesnesinin içine yerleştirilir.
Yanıt alanları (dokümana göre): OrderId, ProvisionNumber, MerchantOrderId, ResponseCode, ResponseMessage, RRN, Stan, ExecutionReferenceId, TransactionTime