Wix Integration with Kuwait Turk Virtual POS: Participation Banking and E-Commerce

With Wix Kuveyt Türk virtual POS integration, businesses can easily start using the bank's secure payment infrastructure.

Payment System Compliant with Participation Banking Principles

Kuveyt Türk, as one of Turkey's leading participation banks, offers services in accordance with interest-free banking principles. This feature is an important advantage for businesses with e-commerce sites because some customer groups prefer to work with participation banks in line with religious and ethical preferences. When you integrate Kuveyt Türk Virtual POS into Wix, you can appeal to both customers using conventional banking and those preferring participation banking.

Participation banking is based on profit-loss partnership and fee-based systems instead of interest income. This principle is also maintained in Kuveyt Türk Virtual POS - commission structures are transparent and predetermined. As a business owner, you know in advance what commission rates you will pay and there are no hidden costs in the process. This approach makes budget planning easier, especially for small and medium-sized enterprises.

Kuveyt Türk's "Free POS" system is also a special service that should be evaluated in this context. While many banks charge annual fees, setup fees, or activation costs for virtual POS, Kuveyt Türk Free POS is completely free. You only pay commission per transaction. This is very important especially for newly opened e-commerce sites, startups, and projects in testing phase because it minimizes startup costs.

Basic Advantages of Kuveyt Türk Virtual POS

When working with the Free POS system, setup fee is zero, monthly fee is zero, no annual membership fee. Commission is only deducted from completed transactions. This means you work with the "sell first, pay later" logic. If you make no sales in the first week of the month, you pay nothing to your bank. Commission only comes into play when there is a sale.

Commission rates vary according to sector, turnover volume, and working conditions. However, generally, Kuveyt Türk's commission rates are at or below market average. For single payment transactions, usually a rate around 1 percent is involved. The rate increases for installment transactions but still remains competitive. You can decide whether to pass the commission on to your customer or not.

There's another important detail: blocking periods. Many banks hold your POS revenues for 7-15 days. With Kuveyt Türk Free POS, this period can be longer - approximately 21 business days. However, it's possible to shorten this period by negotiating with the bank. If your cash flow is critical, it makes sense to negotiate the blocking period during application. Alternatively, Kuveyt Türk has products like "Sağlam Business Pratik Card" - your POS revenues automatically convert to your card limit the next day and you can use them immediately.

Kuveyt Türk Virtual POS accepts payments from all cards with Visa, MasterCard, and Troy logos. This means you can receive payments from both domestic and foreign customers without problems. Installment support is also available - you can make installments with Kuveyt Türk credit cards. If you want to offer installments for other bank cards, there's a separate application process for this, but it's also feasible.

3D Secure 2.0 and Security Infrastructure

Kuveyt Türk Virtual POS switched to the 3D Secure 2.0 system starting from September 2022. This system offers more advanced security features compared to old 3D Secure. The most important difference is improved user experience. In the old system, you had to enter an SMS password for every payment. In the new system, sometimes transactions can be completed without asking for SMS password in low-risk transactions - they call this process "frictionless authentication."

3D Secure 2.0 collects much more data during transactions - device information, browser features, IP address, shopping history, etc. The bank analyzes this data to perform risk scoring. If found low risk, the transaction is approved directly; if found high risk, SMS password is requested. This both increases security and improves customer experience. 70-80% of your customers can now complete their shopping without entering an SMS password.

When integrating with Wix Velo, you must send the API version as "TDV2.0.0". This parameter signals Kuveyt Türk's system that "this transaction is being done with 3D Secure 2.0." If you use old API versions, your transactions will be rejected or you'll get a security error. This update became mandatory from January 2024; old systems are no longer supported.

Hash calculation is also a critical part of security. Kuveyt Türk uses hash to verify that the data you send hasn't been altered in transit. When calculating hash, you combine certain parameters and encrypt them with the HMACSHA1 algorithm. What matters is the order: MerchantId, MerchantOrderId, Amount, OkUrl, FailUrl, UserName, hashPassword. You write these parameters side by side in this order and encrypt them. If the order is wrong or a parameter is missing, you get the error "Encrypted data (Hashdata) does not match."

Kuveyt Türk Integration with Wix Velo

To use Kuveyt Türk Virtual POS on Wix, you need to use the Velo backend structure. The reason for this is the requirement for payment transactions to be performed server-side. Card information should not circulate in the browser; sensitive data must be processed securely. Velo backend is designed precisely for this purpose.

The first step is to obtain the necessary information from Kuveyt Türk. When your application is approved, the bank sends you an email. This email contains Customer Number (CustomerId), Store Number (MerchantId), Username, and Password information. This information is your digital identity - Kuveyt Türk's system recognizes you with this information.

Customer Number represents your account at Kuveyt Türk. Store Number is an ID specific to your virtual POS. If you have multiple websites, you can get a separate store number for each. Username and Password are the credentials you use to log into the bank panel.

You also need to create an API User. This is different from your normal login credentials. Log into Kuveyt Türk's corporate panel (https://kurumsal.kuveytturk.com.tr), go to "New User Add" section from the "Virtual POS" menu. Here, in the "User Role" section, definitely select "API". If you select normal user role, the system will reject your API requests. Create a username for the API user without using Turkish characters and spaces. Your password must be at least 8 characters and contain uppercase-lowercase letters and numbers.

Now you need to securely add this information to Wix. Open Dev Mode in Wix Editor; Code Panel will appear on the left. Go to Secrets Manager and create these secrets:

kuveytturk_customer_id - Your customer number
kuveytturk_merchant_id - Your store number
kuveytturk_api_username - Your API username
kuveytturk_api_password - Your API password
kuveytturk_hash_password - Password to be used in hash calculations (usually the same as API password)

After these credentials are stored in Secrets Manager, you access them in your backend code like this:

import { getSecret } from 'wix-secrets-backend';

const customerId = await getSecret('kuveytturk_customer_id');
const merchantId = await getSecret('kuveytturk_merchant_id');
const apiUsername = await getSecret('kuveytturk_api_username');
const apiPassword = await getSecret('kuveytturk_api_password');
const hashPassword = await getSecret('kuveytturk_hash_password');

Payment Initiation Process

The process starts when the customer clicks the "Make Payment" button on your site. Your frontend code collects card information - card number, expiration date, CVV, and cardholder name. You don't send this information directly to the bank's API; you first do preliminary preparation in your own backend.

In the backend, you create a unique order number. This number will be the same both in your system and at Kuveyt Türk, so you can compare transactions. Then you convert the payment amount to the format Kuveyt Türk expects. Kuveyt Türk expects the amount in kuruş (cents) - meaning if you want to send 100 TL, you need to send it as "10000".

Now it's time for hash calculation. This operation is critical because if the hash is wrong, the transaction will be rejected. Hash parameters in order: MerchantId, MerchantOrderId (your order number), Amount (amount), OkUrl (return address for successful transactions), FailUrl (return address for failed transactions), UserName (your API username), hashPassword. Write these parameters side by side separated by "|" and encrypt with HMACSHA1.

Example hash calculation function:

import crypto from 'crypto';

function calculateHash(merchantId, orderId, amount, okUrl, failUrl, username, hashPassword) {
  const dataString = `${merchantId}|${orderId}|${amount}|${okUrl}|${failUrl}|${username}|${hashPassword}`;
  const hash = crypto.createHmac('sha1', hashPassword).update(dataString).digest('base64');
  return hash;
}

After calculating the hash, you send all data to Kuveyt Türk in XML format. Kuveyt Türk uses an XML-based API, not JSON. POST URL: Usually https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelPayGate for test environment, https://boa.kuveytturk.com.tr/sanalposservice/Home/ThreeDModelPayGate for live environment.

Your XML message should contain:

<KuveytTurkVPosMessage>
  <APIVersion>TDV2.0.0</APIVersion>
  <HashData>[your calculated hash]</HashData>
  <MerchantId>[your store number]</MerchantId>
  <CustomerId>[your customer number]</CustomerId>
  <UserName>[your API username]</UserName>
  <CardNumber>[card number]</CardNumber>
  <CardExpireDateYear>[year, 2 digits]</CardExpireDateYear>
  <CardExpireDateMonth>[month, 2 digits]</CardExpireDateMonth>
  <CardCVV2>[CVV]</CardCVV2>
  <CardHolderName>[cardholder name]</CardHolderName>
  <CardType>[Visa, MasterCard, or Troy]</CardType>
  <BatchID>0</BatchID>
  <TransactionType>Sale</TransactionType>
  <InstallmentCount>0</InstallmentCount>
  <Amount>[amount, in kuruş]</Amount>
  <DisplayAmount>[amount, in kuruş]</DisplayAmount>
  <CurrencyCode>0949</CurrencyCode>
  <MerchantOrderId>[your order number]</MerchantOrderId>
  <OkUrl>[successful return URL]</OkUrl>
  <FailUrl>[failed return URL]</FailUrl>
</KuveytTurkVPosMessage>

When you send this request, Kuveyt Türk returns an HTML page. This page contains a form and JavaScript code - it automatically redirects the user to the bank's 3D Secure screen. Your frontend code takes this HTML and renders it in the browser. The customer is now on Kuveyt Türk's own page and has no relationship with your site.

3D Secure Verification and Callback

While the customer is on Kuveyt Türk's 3D Secure screen, the system performs risk analysis. If it's a low-risk transaction, it approves directly without asking for SMS password. If it finds high risk, it sends an SMS password to the customer's phone. The customer enters this password on the screen and clicks the "Approve" button.

When the transaction is completed - whether successful or unsuccessful - the bank redirects the customer to the URL you specified. You specified this URL with OkUrl and FailUrl parameters when initiating payment. Successful transactions return to OkUrl, failed transactions to FailUrl.

But attention: this redirect comes from the customer's browser. So theoretically the customer can manipulate the URL or go to your success page even though the transaction failed. That's why you must do verification in your callback URL.

Kuveyt Türk sends you many parameters via POST method during callback. The most important ones:

ResponseCode: Transaction result. "00" is successful, other codes mean error or rejection. Accept only transactions with ResponseCode "00" as successful.

MerchantOrderId: Your order number. You can find the transaction in your own database with this number.

HashData: Hash of data sent by the bank. You should also calculate hash with the same parameters and compare. If it matches, the data is secure.

RRN: Bank reference number. Used to query the transaction in the bank's system.

OrderId: Transaction ID created by Kuveyt Türk's system. You use this ID for refund or cancellation.

AuthCode: Approval code. This code comes filled in successful transactions.

Your callback function should work like this:

import crypto from 'crypto';
import { getSecret } from 'wix-secrets-backend';

export async function post_kuveytturkCallback(request) {
  const formData = await request.formData();
  
  const merchantOrderId = formData.get('MerchantOrderId');
  const responseCode = formData.get('ResponseCode');
  const hashData = formData.get('HashData');
  const rrn = formData.get('RRN');
  const orderId = formData.get('OrderId');
  const authCode = formData.get('AuthCode');
  
  // Hash verification
  const hashPassword = await getSecret('kuveytturk_hash_password');
  const calculatedHash = crypto
    .createHmac('sha1', hashPassword)
    .update(`${merchantOrderId}|${rrn}|${responseCode}|${orderId}|${hashPassword}`)
    .digest('base64');
  
  if (calculatedHash !== hashData) {
    return { status: 400, body: 'Hash verification failed' };
  }
  
  // ResponseCode check
  if (responseCode === '00') {
    // Update order - payment successful
    await updateOrder(merchantOrderId, 'paid', orderId, authCode);
    return { 
      status: 200, 
      body: 'Payment successful',
      headers: { 'Location': '/success' }
    };
  } else {
    // Payment failed
    await updateOrder(merchantOrderId, 'failed');
    return { 
      status: 200, 
      body: 'Payment failed',
      headers: { 'Location': '/failed' }
    };
  }
}

Suitability for Service Sector and Subscription Models

Kuveyt Türk Virtual POS is an ideal solution especially for certain sectors. In addition to physical product sales, it's also very suitable for service-based business models. There are several reasons for this.

Education Platforms: Kuveyt Türk is advantageous for sites selling online courses, webinars, and certificate programs. Because in the education sector, there's an audience that prefers participation banks. Especially in areas like religious education, Arabic courses, Quran teaching, if your customers care about participation banking principles, having Kuveyt Türk POS can directly increase your sales.

Consulting Services: In services like business consulting, career coaching, and psychological counseling, usually pre-payment is taken. Customer comes to the site, selects an appointment, makes payment. In such services, there's no physical delivery; digital confirmation is sufficient. Kuveyt Türk's fast transaction flow is very suitable for this model.

Subscription Systems: For businesses working with monthly or yearly subscription models - software services (SaaS), content platforms, membership sites - recurring payments are critical. You can do automatic renewal with Kuveyt Türk API. Customer saves card information once, payment is automatically charged next month. You need to activate the "recurring payment" feature for this operation, but the system supports it.

Digital Products: If you're selling digital products like e-books, PDF documents, templates, graphic design files, Kuveyt Türk's instant approval system makes your job easier. You can send the download link to the customer within seconds after payment is approved. You don't need to wait for physical shipping.

Event Tickets: Speed is important in selling tickets for events like seminars, conferences, workshops. Customer wants to get the ticket immediately. Thanks to Kuveyt Türk's 3D Secure 2.0 system, transactions complete very quickly. In low-risk transactions, the ticket is approved without even asking for SMS.

Commission Structures and Payment Plans

Commission structures at Kuveyt Türk are flexible and open to negotiation. Generally, there are four different working condition models.

Without Blocking and With Commission: This is the most common model. When the transaction occurs, the bank deducts commission and pays you the remainder. Payment usually passes to your account within 1-2 days. Commission rates may be slightly higher in this model, but you reach cash immediately.

With Blocking and With Commission: The transaction amount is held for a certain period (like 7, 14, 21 days), then commission is deducted and deposited to your account. As the blocking period extends, the commission rate decreases. If your cash flow is strong and you can wait a bit, this model provides you with lower commission.

With Blocking and Without Commission: The transaction amount is held for a long time (30-60 days) but no commission is charged. The bank uses the money and makes profit, and you don't pay commission. This model makes more sense for businesses with large turnovers.

Weekly/Monthly Bulk Payment: All transactions accumulated over a week or month are paid in bulk. Discounted commission is usually applied in this model because transaction costs decrease for the bank.

If you're using Free POS, the default model is usually "with blocking and with commission." Commission rate is approximately between 0.75-1.5 percent, blocking period is around 21 business days. However, these figures are not fixed. You can obtain better conditions by negotiating with the bank during or after application.

An important point: commission rates increase for installment transactions. If single payment is 1%, 3 installments might be 1.5%, 6 installments 2%, 9 installments 2.5%. You can reflect these rates to your customer in the installment table on your site or absorb them yourself. If you reflect them, the customer pays a total of 101.5 TL when buying a 100 TL product in 3 installments. If you don't reflect, you receive 98.5 TL.

Technical Requirements and Special Notes

When doing Kuveyt Türk integration with Wix Velo, you need to pay attention to some technical details. If these details are overlooked, errors can occur in the system.

SSL Certificate Mandatory: Kuveyt Türk only serves sites using HTTPS protocol. Wix automatically provides SSL to all sites, so you won't have problems. However, if you're using a custom domain, make sure SSL is active.

Callback URLs Must Be Accessible: The addresses you set as OkUrl and FailUrl must be accessible from the internet. Localhost or test domains won't work in real transactions. You can use Wix's test site URLs when testing.

API Version Parameter: Definitely send as "TDV2.0.0". Old versions are no longer supported.

Currency Code: Use code "0949" for Turkish Lira. "0978" for Euro, "0840" for USD.

Card Type Check: Verify that the card is Visa, MasterCard, or Troy. Other card types are not supported. You can detect card type by looking at the first digits of the card number - Visa starts with "4", MasterCard with "5", Troy with "9792".

Timeout Settings: Kuveyt Türk API can sometimes delay in responding. Especially during redirect to 3D Secure screen. Set timeout period to at least 30 seconds in your backend code.

Log System: Logging all transactions is critical. Especially hash calculations, API requests, and callback data. When there's a problem, it's very difficult to find errors without logs. You can use Wix's console.log function or log to a database table.

Test Environment Usage: Definitely do trials in test environment before going live. Kuveyt Türk provides test card numbers. You can check the entire flow without real money being withdrawn with test cards.

Error Messages: Consider all ResponseCode codes other than "00" as errors. Each code means a different error - insufficient balance, invalid card, limit exceeded, etc. Translate these codes to Turkish error messages and show to customer.

Refund and Cancellation Operations: Refund and void operations at Kuveyt Türk are done with separate API calls. Void is valid if done within the same day of transaction. You need to do refund operation next day or after. You use OrderId (ID given by bank) when doing refund.

Multiple Terminal Management: If you have multiple websites, you can get a separate MerchantId for each. This way you can do your reports separately. Multiple terminals can be defined under a single customer number.

Foreign Currency Transactions: If you want to transact in Euro or USD, you need to get authorization from the bank branch. By default, you can only transact in TL.

Practical Implementation Steps

To summarize the entire process, you need to follow these steps:

First, apply for Free POS to Kuveyt Türk. You can apply from Kuveyt Türk Mobile application or from branch. In the application, specify your activity sector, estimated turnover, and website address. Application is usually finalized within 3-5 business days.

When application is approved, you receive an email. This email contains customer number, store number, and initial login credentials. Log into the corporate panel with this information. SMS password is required at first login; enter the code that comes to your phone.

Create an API user in the panel. Define a user with role "API" from "Virtual POS" > "New User Add" section. Note this username and password.

Open Dev Mode in Wix Editor and save all information to Secrets Manager. CustomerId, MerchantId, API username, API password, and hash password.

Create a payment service file in backend (e.g., kuveytturkService.jsw). Write hash calculation, payment initiation, and callback processing functions in this file.

Prepare the payment form in frontend. There should be fields for card number, expiration date, CVV, and cardholder name. Call the backend service when form is submitted.

Create callback function in HTTP functions file. This function should accept POST requests and do hash verification.

Do trials with test cards in test environment. Test every scenario - successful payment, failed payment, wrong card information, insufficient balance, timeout, etc.

If everything works, switch to live environment. Close test mode in bank panel and switch to live mode. Make your first real transaction and check the result.

After transaction, verify that order is created in Wix panel and transaction appears in Kuveyt Türk panel. Regularly check both panels.

Recommendations

Integrating Kuveyt Türk Virtual POS into Wix is a strategic step especially for businesses appealing to customers who value participation banking principles. Thanks to Free POS, you can start e-commerce without startup costs and only pay commission when you make sales. The 3D Secure 2.0 infrastructure improves both security and user experience.

Although the integration process requires technical knowledge, it's manageable with the Velo backend structure. Hash calculations, XML message format, and callback operations require careful coding, but if you follow the examples in this article, you can proceed smoothly.

Especially for service sector, education platforms, consulting sites, and subscription models, Kuveyt Türk is a strong choice. Installment support, domestic-international card acceptance, and flexible commission structures provide advantages.

Finally, for post-integration support, you can reach Kuveyt Türk Virtual POS Support Team (sanalposdestek@kuveytturk.com.tr). They help with technical problems or integration errors. Also, detailed documentation and sample codes are available in the bank panel - reviewing these will be beneficial.