Wix Virtual POS Setup Guide for Kuwait Turk: Step-by-Step Process

Pre-Installation Preparation: Information from the Bank

When your Free POS application from Kuveyt Türk is approved, you receive an email. This email contains critical information that will be useful for your business, and you need to store it carefully. First, there's the Customer Number - this is your account identity at Kuveyt Türk. The second important information is the Store Number, which is your virtual POS terminal's ID. Third comes the Username and Password, with which you'll log into the bank panel.

After receiving this information, the first thing you should do is log into the corporate panel. Go to https://kurumsal.kuveytturk.com.tr in your browser. Enter your customer number, username, and password. When you log in, an SMS password will be sent to your phone; enter it on the screen and confirm. Now you're in the bank panel.

Your first task in the panel is to create an API user. Your normal user information is for the web panel, while the API user is for programmatic access. Click on "Virtual POS" option from the "All Transactions" menu, then press the "Add New User" button. On the screen that opens, determine a username - don't use Turkish characters and spaces, only English letters and numbers. Enter your email, mobile phone, and Turkish ID number. The most important part: in the "User Role" section, be sure to select "API". If you select a normal role, the system will reject your requests.

Be careful when setting a password - at least 8 characters, containing uppercase letters, lowercase letters, and numbers. Note this password because you won't be able to see it again. Leave the "Status" section as "Active" and save. Now you have two sets of information: normal user information (for panel login) and API user information (for Wix integration).

Wix Velo Backend Configuration

Now let's move to the Wix side. Open your Wix Editor and click the "Dev Mode" button in the upper left corner. This activates developer tools. Wait a bit, the "Code Panel" will open on the left side. Here you'll see your Velo backend files.

The first step is to enter Secrets Manager. At the top of the Code Panel, there's a "Secrets Manager" option, click it. This is like a vault that allows you to securely store your sensitive information. Now we'll add the information you received from Kuveyt Türk here. Press the "Add Secret" button and add the following information one by one:

Create a secret named kuveytturk_customer_id and write your customer number in it. For kuveytturk_merchant_id, enter your store number. For kuveytturk_api_username, write your API username. For kuveytturk_api_password, enter your API password. Finally, add kuveytturk_hash_password - this is usually the same as your API password, but in some cases it can be different; if the bank specified it specially for you, use that.

Why don't we write this information directly in the code? Because code can sometimes be visible in the browser, accidentally shared, or uploaded to a versioning system. Information in Secrets Manager is only used server-side and is never sent to the browser. This is the basic rule of security.

After adding the secrets, create a new file in the backend folder. Let the file name be "kuveytturkService.jsw". Backend files end with ".jsw" extension - the "w" letter means "web". Click on this file and the code editor will open.

Creating the Payment Initiation Endpoint

In your backend file, first import the necessary modules. You'll read your secrets from the wix-secrets-backend module, send requests to the bank's API with wix-fetch, and calculate hash with the crypto module. Your import lines should be like this:

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

Now let's write the payment initiation function. This function will receive card information from the frontend, calculate hash, send a request to the bank's API, and return the 3D Secure redirect URL. Don't forget to add the export keyword at the beginning of the function, otherwise you can't access it from the frontend.

Inside the function, first read the secrets. Then generate a unique number for the order - a combination of timestamp and random number is a good method. Convert the amount to kuruş - Kuveyt Türk expects "10000" for 100 TL. It's time for hash calculation - combine parameters in the correct order and encrypt with HMACSHA1: MerchantId, MerchantOrderId, Amount, OkUrl, FailUrl, UserName, hashPassword.

Determine your callback URLs. OkUrl for successful transactions, FailUrl for failed transactions. These URLs must start with https and be accessible from the internet. Use the real URL of your Wix site. For example: https://yoursite.wixsite.com/mysite/_functions/kuveytturkCallback.

Prepare all this information in XML format. Kuveyt Türk uses XML, not JSON. In your XML message, send APIVersion as "TDV2.0.0" - this is very important, old versions are no longer supported. Determine CardType by looking at the first digits of the card number: if it starts with 4, it's Visa; if it starts with 5, it's MasterCard; if it starts with 9792, it's Troy.

After preparing the XML, send a POST request to the bank's API endpoint. The URL is usually under boatest.kuveytturk.com.tr for test environment, under boa.kuveytturk.com.tr for live environment. Request headers are important: Content-Type should be "application/xml". Wait for the response - the bank will return an HTML page. This HTML contains an auto-submitting form that redirects the customer to the 3D Secure screen.

3D Secure Redirect and User Experience

Your backend function returns the HTML response to the frontend. Your frontend code takes this HTML and places it on the page. The JavaScript code inside the HTML runs automatically and takes the customer to Kuveyt Türk's 3D Secure screen. This transition happens within seconds, the customer barely notices.

Now the customer is on the bank's own page. This page is not under your control; Kuveyt Türk manages it completely. Transaction details appear on the screen - amount, store name, date-time. The bank performs risk analysis in the background: evaluates data such as the customer's shopping history, device information, IP address, transaction amount.

If the system finds it low risk, it approves directly without asking for an SMS password. This is called "frictionless authentication". The transaction is completed without the customer doing anything. If it finds it high risk, it sends an SMS to the customer's phone. The customer enters the code and presses the "Approve" button.

Regardless of approval or rejection, the bank redirects the customer to the callback URL you specified. Successful transactions go to OkUrl, failed transactions to FailUrl. But be careful: this redirect comes from the customer's browser, so it can theoretically be manipulated. That's why you must verify in your callback URL.

Callback URL and Transaction Verification

You need to use HTTP Functions for the callback URL. Create a new file in the "HTTP Functions" folder, not in the backend folder. Let the file name be "http-functions.js" - be careful, it's .js extension, not .jsw. In this file, you can accept POST requests from outside.

Set the function name as post_kuveytturkCallback. Having "post_" in front is important; this indicates that it's a handler for HTTP POST method. The function receives request as a parameter. You access form data in the request with request.formData().

The bank sends you many parameters. The most important ones: ResponseCode (transaction result), MerchantOrderId (your order number), HashData (bank's hash), RRN (reference number), OrderId (bank's transaction ID), AuthCode (approval code). Get these parameters from form data.

The first check is hash verification. The bank uses these parameters when calculating hash: MerchantOrderId, RRN, ResponseCode, OrderId, hashPassword. You also calculate hash with the same parameters and compare with the HashData sent by the bank. If they don't match, the data may have been altered in transit - reject the transaction.

If the hash is correct, check ResponseCode. Only code "00" means successful transaction. All other codes are errors or rejections. If you see "00", update the order status as "paid". Save OrderId and AuthCode information to the database - you may need them for refund or cancellation later.

If ResponseCode is not "00", mark the order status as "failed". Also save the error code - you can use it to inform the customer or for troubleshooting. Some common codes: "05" card rejected, "51" insufficient balance, "54" card expired.

Dual Panel Tracking System and Advantages

After the installation is complete, you can now track your transactions from two different panels. This system provides great advantages both in terms of security and control.

In your Wix Dashboard, you see the general status of orders. Which customer bought what, what's the order number, what's the payment status - these are in the Wix panel. If you're using Wix Data, all details are in your "Orders" collection. E-commerce-focused information such as customer email, delivery address, product information, payment date stays here. You can update order status as "being prepared", "in cargo", "delivered".

In the Kuveyt Türk Corporate Panel, there are financial details. Which card was payment made with, what are the last 4 digits of the card, how many installments, how much commission was deducted, exactly what time did the transaction take place - you see these in the bank panel. Also, end-of-day reconciliation, weekly-monthly reports, and refund transactions are managed here.

These two panels complement each other. For example, when a customer complains "I made payment but the order doesn't appear to have arrived," first you look at the Wix panel - is there really no order? Then you switch to the Kuveyt Türk panel - did the payment really come? If payment came but there's no order in Wix, it means there was an error in the callback process. You check the logs and solve the problem.

The opposite can also happen. There's an order in Wix but the transaction doesn't appear in Kuveyt Türk. In this case, probably a test transaction was made or an error occurred at the payment initiation stage. You can leave the order status as "waiting for payment" and send the customer a retry link.

As a daily routine, checking both panels in the morning is a good habit. You see payments that came in at night in the Kuveyt Türk panel, you confirm in the Wix panel that these orders were processed correctly. In the afternoon, you track cargo processes from Wix. On weekends or at the end of the month, you download financial reports from Kuveyt Türk - you can do analyses like how much turnover you made, which days were busier, what's the average cart amount.

Testing Process and Going Live

After completing the installation, be sure to test. Kuveyt Türk provides test cards - you can try the entire flow without real money being withdrawn. Use test environment URLs, not live environment URLs. Start a payment with a test card. Enter card information, see that you're redirected to the 3D Secure screen, enter the test code instead of the SMS password.

Check that the callback is working. Was an order created in Wix? Was the status updated as "paid"? Does the transaction appear in the Kuveyt Türk test panel? Verify each step one by one. Also test failed transactions - enter wrong CVV, use an expired card number. Confirm that the system catches errors correctly and shows meaningful messages to the customer.

Double-check your hash calculations. Hash error is one of the most common problems. Is the order of parameters correct? Are you sending all values as strings? Are you using the pipe character (|) as a separator? If there's an error, the bank returns "Encrypted data (Hashdata) does not match".

If the test is successful, it's time to go live. Close test mode in the Kuveyt Türk panel, switch to live mode. In your backend code, change the API URLs from test environment to live environment. Publish your Wix site. Make your first real transaction with a small amount like 1 TL. If successful, congratulations - your system is working!

Track logs in live as well. Be especially careful the first week. Check both Wix and Kuveyt Türk panels after each transaction. If you see a problem, intervene immediately. Customer satisfaction is critical - a customer who can't make payment may go to another site.

Do regular maintenance. Read update emails from Kuveyt Türk. Sometimes changes occur in the API, new parameters are added, or old versions are closed. Follow these updates and update your system in time. Change your passwords in Secrets Manager every 6 months - it's a good practice for security.

Installing Kuveyt Türk Virtual POS on Wix is not complicated when you follow the right steps. Prepare API information properly, store securely in Velo backend, make hash calculations correctly, configure callback well. When installation is complete, you'll have a payment system that complies with participation banking, is secure and transparent. By tracking your transactions from both panels, you can ensure both customer satisfaction and financial control.