Connecting Halkbank Virtual POS to Wix: A Simple and Secure Process

Information Required for Connection

To connect Halkbank Virtual POS to Wix, you first need special information received from the bank. This information works like digital keys and enables systems to communicate securely with each other.

First, there's the Merchant ID. This is the unique number that identifies your store in the Halkbank system. It's usually a 9-digit number and the bank sends it to you via email. You'll use this number in every API call because this is how the bank understands "aha, this transaction is coming from this store."

The second important information is Terminal ID. Some businesses may have multiple terminals, so it's necessary to specify which terminal the transaction is being conducted through. You can find this number in the "Member Business Terminal Information" section in your Halkbank panel.

The third critical piece is the 3D Security Key. This key is used to prove that the data you send hasn't been altered in transit. You use this key in hash calculations. You can see it or create a new one from the "Security Key Change" section in the Halkbank panel. You should not share this key with anyone - if this information is leaked, your system becomes compromised.

Finally, API User Information is needed. These are different from your normal login credentials. In the Halkbank panel, you create a user of type "API User" from the "Add New User" section. This username and password enable your Wix backend to access the Halkbank system.

Adding Information to Velo Backend

Now let's look at how to add this information to Wix. When you open Dev Mode in Wix Editor, the Code Panel appears on the left. There's an important feature here: Secrets Manager. This is a vault that allows you to securely store your sensitive information.

Open Secrets Manager and create a "secret" for each piece of information. For example, you create a secret named "halkbank_merchant_id" and write your Merchant ID into it. Similarly, you create separate secrets for terminal ID, security key, API username, and password.

Why don't we write directly in code? Because code can sometimes be visible in the browser or accidentally shared. Information in Secrets Manager is only accessible server-side and is never sent to the browser. This is the cornerstone of security.

To use this information in your backend file, you write code like this:

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

const merchantId = await getSecret('halkbank_merchant_id');
const securityKey = await getSecret('halkbank_security_key');

This information is now secure and ready to use in your code. You'll use this information when initiating payment, calculating hash, and verifying transactions.

Payment Initiation and 3D Secure Redirect

The process begins when the customer clicks the "Make Payment" button on your site. Your frontend code collects the card information entered by the user - card number, expiration date, CVV, and cardholder name. This information is sent to your backend function.

In the backend, you generate a unique number for the order and send all information to Halkbank API. But there's an important step before sending: hash calculation. Hash is like a fingerprint of your data. You combine Merchant ID, order number, amount, and security key and encrypt them with SHA-512 algorithm. This hash enables the bank to answer the question "did this store really send this data?"

If the request you send to Halkbank API is successful, the bank returns a redirect URL to you. This URL is the address of Halkbank's 3D Secure verification screen. Your frontend code automatically redirects the customer to this address.

Now the customer is on Halkbank's own screen. This screen is completely under the bank's control and has nothing to do with your site. The customer enters the SMS password sent to their mobile phone. At this stage, the customer confirms "yes, I am making this payment." If the password is correct, the transaction is approved; if wrong, it's rejected.

Callback URL and Transaction Result

After the customer approves the transaction on the 3D Secure screen, the bank sends them back to your site. But it doesn't just send the customer; it also sends the transaction result. This return occurs through the callback URL.

You specified the callback URL when initiating payment. In Wix, this must be an HTTP function because it needs to accept POST requests from outside. For example, an address like https://yoursite.wixsite.com/_functions/halkbankCallback.

The bank sends a POST request to this address and passes many parameters. The most important parameters are:

mdStatus: Result of 3D Secure verification. If "1" it's successful, other values mean failed. You only proceed with the transaction if it's "1".

status: General result of payment transaction. If "APPROVED" or "SUCCESS," payment is successful; if "DECLINED," it's rejected.

hash: Hash of data sent by the bank. You also calculate hash with the same data and compare. If they match, the data is secure; if not, it may have been manipulated.

authCode: Approval code. Unique approval number given by the bank in successful transactions.

transactionId: Transaction ID. You can query the transaction with this number later, make refunds or cancellations.

Your callback function receives these parameters, verifies the hash, and checks mdStatus and status. If everything is in order, it marks the order as "paid." If there's a problem, it records as "failed" and shows an error message to the customer.

Dual Panel Tracking System

After connection is complete, you gain a great advantage as a business owner: you can track your transactions from two different places. This dual panel system is very valuable for both security and control.

Wix Panel: You see orders in your Wix Dashboard. E-commerce-focused information like which customer bought what, payment status, shipping information are here. If you're using Wix Data, you store all details in the "Orders" collection. Data such as order number, customer email, amount, payment status, transaction ID are here.

Halkbank POS Panel: In Halkbank's own management panel, you see financial details. Information like which card payment was made with, last 4 digits of card, number of installments, commission amount, bank approval code, transaction date and time are here. You also manage banking operations like end-of-day reconciliation, refund transactions, authorization cancellation from this panel.

These two panels complement each other. For example, when a customer says "I made payment but order wasn't created," you can check the Halkbank panel to see if payment actually came. If payment came but there's no order in Wix, there was a problem in the callback process. Or vice versa, if there's an order in Wix but no transaction in Halkbank, there may have been an error in the payment initiation stage.

As a daily routine, it's good practice to check both panels. In the morning, you see transactions that came overnight from the Halkbank panel; in the afternoon, you track whether orders have been shipped from the Wix panel. At the end of the month, you get financial reports from the Halkbank panel - you do analyses like how much turnover you made, how much commission was paid, which days were busier.

Security and Sustainability

To keep your system secure after establishing connection, you need to pay attention to a few things. First, update your information in Secrets Manager periodically. Especially changing the 3D Security Key every 6 months is a good security practice. Don't forget to also update the secret in Wix after changing it.

Second, follow security updates from Halkbank. For example, there may be changes like hash algorithm updated or new parameters added. If you miss these updates, the system may stop working.

Third, regularly review your transaction logs. Wix's log system shows errors that occur in your backend codes. If you're frequently getting hash errors in your callback function or unexpected parameters are coming, you need to detect and fix these.

Finally, make backups. Regularly export and backup order information in your Wix Data collection. This way, you won't lose your data if any problem occurs.

Conclusion

Connecting Halkbank Virtual POS to Wix is a secure and convenient system when done correctly. When you add critical information like Merchant ID, Terminal ID, API information, and security key to Velo backend and configure the payment flow correctly, your system works smoothly for years. With the dual panel tracking system, you can keep both customer experience and financial process under full control.