Payment Infrastructure Compliant with Participation Banking

Kuveyt Türk, as one of Turkey's leading participation banks, offers services in accordance with interest-free banking principles. For e-commerce businesses, this feature is not just a matter of religious preference, but also the key to reaching a specific customer base. While some of your customers do not prefer conventional banks, they see working with participation banks as a priority. When you connect Kuveyt Türk POS to Wix, you can appeal to both groups of customers.

Although the connection process seems technical, it actually follows a logical flow. First, you place the information received from the bank into Wix's secure area. Then you set up a system that initiates payment. When the customer makes a payment, the bank performs verification and then notifies you of the result. You process the order according to this result. This cycle repeats with each transaction, but since the system works automatically, you only see the results.

Kuveyt Türk's POS system supports both single payment and installment transactions. In single payment transactions, the customer pays the entire amount at once. In installment transactions, they divide the amount and make monthly payments. Which option you offer is up to you. If you want installments, commission rates increase, but shopping becomes more attractive to the customer. Installments are almost mandatory for high-value products - no one wants to buy a 10,000 TL product in a single payment.

Connection Information Provided by the Bank

When your Free POS application to Kuveyt Türk is approved, the bank sends you critical information. Without this information, you cannot do anything because these are your digital identity. The first information is Merchant ID - your store number. This number represents your business in Kuveyt Türk's system. A unique ID specific to each POS application. If you have multiple websites, you can get a separate Merchant ID for each.

The second important information is Customer ID - your customer number. This is your account number at Kuveyt Türk. A customer can have multiple Merchant IDs, but Customer ID always remains the same. The bank uses this number to find your account and deposit payment revenues.

Third, there's User Code - your user code. You use this code when logging into the bank panel. You may need one code to log into the normal panel and another code for API requests. You create the API user yourself in the bank panel. You go to "New User Add" from the "Virtual POS" menu and select the role as "API". You note this user's code and password because they will be used in Wix integration.

Finally, there's Password and security key information. Password is the API user's password. The security key is used in hash calculations. Hash is a security mechanism that proves the data you send hasn't been altered in transit. You should not share the security key with anyone - if this key is compromised, malicious people can transact in your name.

Defining Information to Velo Backend

After receiving this information, you switch to the Wix side. When you open Wix Editor and activate Dev Mode, Code Panel appears on the left. Here's Secrets Manager - like a secure vault where you store your sensitive information. Writing passwords in normal code files is dangerous because code can sometimes be visible in the browser or accidentally shared. Information in Secrets Manager stays only server-side and never goes to the browser.

Open Secrets Manager and create a separate "secret" for each piece of information. Naming is important - use meaningful and consistent names. For example, create a secret called kuveytturk_customer_id and write your Customer ID in it. Similarly, add secrets kuveytturk_merchant_id, kuveytturk_user_code, kuveytturk_password, and kuveytturk_security_key. Fill the value of each with information received from the bank.

To access these secrets in your backend code, you use the wix-secrets-backend module. For example:

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

const customerId = await getSecret('kuveytturk_customer_id');
const merchantId = await getSecret('kuveytturk_merchant_id');

This way, information comes to your code securely. The await keyword is important because reading secrets is an asynchronous operation - it takes a bit of time. After secrets are ready, you use them in your payment initiation function.

Create a new file in the Backend folder, name it "kuveytturkService.jsw". This file will manage all Kuveyt Türk operations. Functions like payment initiation, hash calculation, and transaction queries will be here. When the file is ready, export your functions to make them accessible from frontend.

Payment Initiation and 3D Verification Redirect

The customer has filled their cart on your site, come to the payment page, and is entering card information. When they press the "Make Payment" button, your frontend code comes into play. You take the card number, expiration date, CVV, and cardholder name and send them to your backend function. One point to be careful about here: never store or process card information in frontend. Send it directly to backend.

Your backend function receives this information and converts it to the format Kuveyt Türk expects. First, you generate an order number - a combination of timestamp and random number is a secure method. This number will be the same both in your system and at Kuveyt Türk. You convert the amount to kuruş (cents) because the bank expects "10000" instead of 100 TL.

Now comes a critical step: hash calculation. Hash is like the fingerprint of the data you send. You combine certain parameters in a certain order and encrypt them. For Kuveyt Türk, the order is: MerchantId, MerchantOrderId, Amount, OkUrl, FailUrl, UserName, SecurityKey. You separate these parameters with "|" and encrypt them with HMACSHA1 algorithm. The result is a string, which you send to the bank's API.

You package all this information in XML format. Kuveyt Türk uses XML, not JSON. It's very important to specify APIVersion as "TDV2.0.0" in your XML message - old versions are not supported. You POST the message to the bank's endpoint. Usually boatest.kuveytturk.com.tr for test environment, boa.kuveytturk.com.tr for live environment.

The bank returns an HTML response. This HTML contains a form and JavaScript code. The form auto-submits and takes the customer to Kuveyt Türk's 3D Secure screen. Now the customer is under the bank's control. Transaction details appear on the screen - how much money will be charged, which store they shopped from, date-time information.

The bank performs risk analysis in the background. It evaluates data such as the customer's past shopping behavior, device information, IP address, and transaction amount. If it finds low risk, it approves directly without asking for SMS password - this is called "frictionless authentication". If it finds high risk, it sends a code to the customer's phone, the customer enters the code, and the transaction is completed.

Receiving Transaction Result with Callback URL

When the transaction is completed - whether successful or failed - the bank redirects the customer to the URL you specified. You sent this URL with OkUrl and FailUrl parameters when initiating payment. Successful transactions return to OkUrl, failed transactions to FailUrl. However, this redirect comes from the customer's browser, so it's not secure. The customer could theoretically manipulate the URL. That's why you must verify in your callback URL.

You use Wix's HTTP Functions feature for callback URL. In the "http-functions.js" file, you create a function named post_kuveytturkCallback. This function accepts POST requests from outside. The bank sends you many parameters as form data. The most critical ones: ResponseCode (transaction result), MerchantOrderId (your order number), HashData (bank's hash), RRN (reference number), OrderId (bank's transaction ID).

The first check is hash verification. When calculating hash, the bank uses MerchantOrderId, RRN, ResponseCode, OrderId, and SecurityKey. 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 manipulated, reject the transaction. If they match, check ResponseCode.

Only code "00" means successful transaction. All other codes mean error, rejection, or failure. If you see "00," the customer has successfully completed the payment and money has been charged from their card. Update the order status to "paid," send confirmation email to customer, notify inventory system. Save OrderId and RRN to the database because you may need them for refund or inquiry later.

If ResponseCode is not "00," the transaction failed. Mark the order status as "payment failed." Look at the error code and inform the customer. "51" means insufficient balance, "54" means card expired, "05" means card rejected by bank. Translate these codes into Turkish messages and show to customer in an understandable way. You can give the customer a chance to try again or suggest alternative payment methods.

Single Payment and Installment Transactions

Kuveyt Türk POS supports both single payment and installment transactions, but they work differently. Single payment is simple - the customer pays the entire amount at once. In your XML message, you send the InstallmentCount parameter as "0" or "1." Commission rate is low, transaction is fast, customer makes a single payment.

In installment transactions, you give values like 2, 3, 6, 9, 12 to the InstallmentCount parameter. But be careful: to do installments, you need to make an installment agreement with your bank. When applying for Free POS or afterward, you need to go to the bank branch and say "I want to open installments." The bank tells you which installment numbers you can offer and the commission rates.

Commission rates increase in 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 or absorb them yourself. If you reflect them, when the customer buys a 100 TL product in 3 installments, they pay a total of 101.5 TL - approximately 33.83 TL per month. If you don't reflect, the customer pays 100 TL but you receive 98.5 TL because 1.5% commission is deducted from you.

On frontend, you can dynamically show installment options. As the amount increases, you can offer more installment options. For example, below 100 TL only single payment, 100-500 TL 3 installments, 500-1000 TL 6 installments, above 1000 TL 9 or 12 installments. This improves customer experience because you're not showing unnecessary installment options for small amounts.

When showing the installment table, calculate and show the monthly payment amount. "9 installments" doesn't mean much to the customer, but "9 months x 111.11 TL" is more meaningful. The customer can plan their budget, knows how much they'll pay monthly. Also show the total amount - sometimes shopping with installments can be more expensive than single payment, the customer should know this.

Connection Accuracy and Continuity

After the connection is established, you need to make sure the system is working properly. Check every day for the first week - are transactions completing successfully, is callback working properly, are orders being updated correctly. If there's a problem, detect and solve it early. When the customer can't make payment, they immediately go to another site, you lose that sale.

Definitely keep logs. Record every payment initiation, every hash calculation, every callback. When there's a problem, it's very difficult to find errors without logs. You need to be able to see which parameter you sent wrong, where the hash didn't match, what the bank returned. You can use Wix's console.log function or create a separate log table.

Regularly update the information in Secrets Manager. Especially changing the security key every 6 months is a good security practice. When you change it, don't forget to update the secret in Wix too. Follow update emails from Kuveyt Türk - sometimes there are changes in the API, new parameters are added, or old versions are shut down.

Regularly compare the bank panel and Wix panel. In the morning, log into the Kuveyt Türk panel and see the payments that came in overnight, then verify in the Wix panel that these orders were processed correctly. Do the amounts match? Do the order numbers align? If there's a discrepancy, investigate immediately. Sometimes callback can fail, sometimes the customer can abandon the payment midway - you need to detect and manage these situations.

Conclusion

When configured correctly, connecting Kuveyt Türk POS to Wix is a secure system that works smoothly. Define your bank information to Velo backend, set up payment flow correctly, configure callback well. When the system runs automatically, it will support both single payment and installment transactions. You'll have a payment infrastructure compliant with participation banking that gains customer trust.