Wix İş Bankası Virtual POS Connection Process: A Practical Guide from Configuration to Management

By connecting İş Bankası Virtual POS to Wix, users can benefit from the bank's secure and fast payment system.

How Does the Connection Process Work?

Connecting İş Bankası Virtual POS to your Wix site may seem technically complex, but it actually consists of a structured process of logical steps. In this article, we will examine step by step the entire process from adding the bank's API information to the system to the moment your customer makes a payment. We will also see how to track your payment transactions after the connection is completed.

First Step: Configuring API Information to Velo Backend

The bridge between Wix and İş Bankası begins with the configuration established in the Velo backend system. Velo is Wix's JavaScript-based development platform and allows you to write custom code and work with APIs¹. During this configuration phase that forms the foundation of the connection process, you need to securely integrate various information provided by the bank into the system.

Adding Merchant Information to the System

After your contract with İş Bankası is approved, the bank sends you a series of identification information. This information includes Store Number, Terminal Number, API Username, and API Password². Each of these pieces of information is critically important for the correct routing of payment transactions and the unique identification of your business.

The safest method for storing this information in the Velo backend system is to use Wix Secrets Manager³. Secrets Manager ensures that sensitive data is stored in an encrypted manner and prevents this information from being visible on the browser side. For example, instead of writing your API password as plain text in the code, you can save it to Secrets Manager and call it in your backend code as follows:

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

export async function getIsbankAPIPassword() {
  const password = await getSecret("isbankAPIPassword");
  return password;
}

This method is an indispensable practice in terms of security³. After your merchant information is added to the system, each payment transaction is verified with this identification information and connection is made to İş Bankası with this information.

Security Keys and Hash Verification

One of the security layers in İş Bankası Virtual POS system is the hash verification mechanism. Hash basically creates a mathematical fingerprint of your data, allowing you to understand whether the data has been altered⁴. İş Bankası uses a two-stage hash structure.

In the first stage, your provision password and terminal number are combined and hashed with SHA1 algorithm. As a result of this process, the "hashedPassword" value is obtained. In the second stage, your transaction information is combined with this hashedPassword and hashed again to create the final "HashData"⁴. This HashData value is used to verify the information sent to you by the bank in each of your API requests.

You need to write functions in your Velo backend that automatically perform these hash calculations. An example implementation could be as follows:

import crypto from 'crypto';

function generateHashData(password, terminalNo, transactionData) {
  // Step 1: Hashed Password
  const hashedPassword = crypto
    .createHash('sha1')
    .update(password + terminalNo)
    .digest('hex');
  
  // Step 2: Hash Data
  const hashData = crypto
    .createHash('sha1')
    .update(transactionData + hashedPassword)
    .digest('hex');
  
  return hashData;
}

Thanks to this mechanism, every request going from you to the bank's servers is verified and third parties are prevented from interfering with your system⁴.

Configuring 3D Secure Return URLs

One of the most critical points of the 3D Secure process is redirecting back to your site after your customer completes verification at the bank. You need to define two separate URLs for this redirect: success URL for successful transactions and fail URL for failed transactions⁵.

In the Wix Velo system, these URLs are generally endpoints defined in the http-functions.js file⁶. For example:

Success URL: https://yourdomain.wixsite.com/_functions/payment3DSuccess

Fail URL: https://yourdomain.wixsite.com/_functions/payment3DFail

These URLs are registered in the İş Bankası system, and when the customer completes 3D verification, the bank automatically redirects the user to the relevant URL⁵. By writing functions in your Velo backend that listen to these endpoints, you can process incoming data and update payment status.

Second Step: Automatic Redirect During Customer Payment Process

After all configuration is completed, the system is now ready for your customers to make payments. The process begins when your customer presses the "Complete Payment" button on your site.

Payment Initiation and PaymentInfo Creation

When the customer clicks the payment button, your frontend code calls a function you defined in the backend. This function creates an object called PaymentInfo⁷. The PaymentInfo object contains the payment amount, currency, order number, and customer information.

export async function initiatePayment(amount, orderId) {
  const paymentInfo = {
    amount: amount,
    currency: 'TRY',
    orderId: orderId,
    merchantId: await getSecret("isbankMerchantId"),
    // other required information...
  };
  
  const payment = await createPayment(paymentInfo);
  return payment;
}

When this function runs, the Wix system creates a Payment object, and this object contains a unique payment ID⁷. This ID is used to track the transaction during the rest of the payment process.

Automatic Redirect to 3D Secure Screen

After the Payment object is created, your frontend code calls the startPayment() function⁷. This function automatically redirects your customer to İş Bankası's 3D Secure verification screen. This redirect operation is designed to be seamless from a user experience perspective - the customer usually sees the bank's page in a popup window or new tab.

On İş Bankası's 3D Secure screen, the customer is asked to approve from their bank's mobile application or enter the one-time password received via SMS⁸. This step ensures that the actual cardholder approves the transaction and significantly reduces fraud risk⁸.

When the customer completes this verification step or cancels, İş Bankası redirects the customer to the return URLs you defined in the configuration phase. If verification is successful, they are sent to the success URL; if unsuccessful, to the fail URL⁵.

Third Step: Receiving Information and Verification via Callback URL

When the customer returns to your site from the bank, the actual critical process begins. İş Bankası sends the customer along with a series of parameters. These parameters include information such as whether the transaction was successful, transaction number, approval code, and 3D verification result⁹.

Data Processing at Callback Endpoint

The callback endpoint you defined in your Velo backend captures these parameters. An example callback function could be as follows:

import { ok, serverError } from 'wix-http-functions';

export async function post_payment3DSuccess(request) {
  try {
    const params = await request.body.text();
    const parsedData = parseIsbankResponse(params);
    
    // Verification operations...
    const isValid = await validatePayment(parsedData);
    
    if (isValid) {
      await updateOrderStatus(
        parsedData.orderId, 
        'paid'
      );
      return ok({ redirect: '/order-success' });
    }
  } catch (error) {
    return serverError({ error: error.message });
  }
}

The first point to note here is validating the incoming data. It is critically important to perform hash checking to verify that the response from İş Bankası actually comes from the bank and has not been altered in transit⁴.

Payment Verification Mechanism

You need to pass through several checks during the verification process. First, you compare the incoming hash value with the hash you calculated yourself. If the two values match, you can be sure that the data has not been manipulated⁴.

The second check is the value of the mdStatus parameter. If mdStatus=1, 3D verification is successful and processing can continue. If mdStatus=0, 2, 3, or 4, verification has failed and the transaction should be terminated¹⁰. Continuing the payment process without these checks creates serious security risks.

The third check is the accuracy of the transaction amount. You must ensure that the incoming transaction amount is the same as the amount you sent initially. This check provides protection against man-in-the-middle attacks.

Updating Order Status

After all verification checks are successful, you need to update the status of the relevant order in your Wix order system. You can change the order status from "pending" to "paid" using the Wix eCommerce API¹¹.

import { orders } from 'wix-stores-backend';

async function updateOrderStatus(orderId, status) {
  await orders.updateOrder(orderId, {
    paymentStatus: status,
    fulfillmentStatus: status === 'paid' 
      ? 'readyToShip' 
      : 'pending'
  });
}

After this update, an order confirmation email is automatically sent to your customer and the order processing process begins on the business side¹¹.

Fourth Step: Tracking and Management via Dual Panel

After the connection process is completed, you can track your payment transactions through two separate panels. This dual panel approach offers important advantages in terms of both security and transparency.

Transaction Tracking from Wix Panel

You can see all your orders and payment statuses from the "Orders" section in your Wix Dashboard¹¹. Each order card contains payment method, transaction status, amount, and date information. You can also see customer information, order content, and delivery status on the same screen.

The advantage of the Wix panel is that you can manage all your e-commerce operations from one place. Order, inventory, customer management, and payment tracking work integratively within the same interface. You can also access business intelligence features such as detailed sales reports, best-selling products, and customer analysis¹¹.

Detailed Reporting from İş Bankası POS Panel

You can log into İş Bankası Virtual POS management panel at https://spos.isbank.com.tr¹². In this panel, you access more technical and financial details of your payment transactions.

On the panel, you can see the provision number, transaction time, first 6 and last 4 digits of the card, installment information, and commission amounts for each transaction¹². You can also access daily, weekly, and monthly total turnover reports.

One of the important features offered by the İş Bankası panel is the ability to make manual interventions. For example, when a customer wants to return a product, you can initiate the return transaction directly from this panel. You also perform operations such as cancellation transactions, pre-authorization closure, and security key management through this panel¹².

Using Both Panels Together

In practice, you usually conduct your daily operations from the Wix panel. When an order comes in, you see it in Wix, package it, and send it. However, you consult the İş Bankası panel for financial reconciliation, commission calculations, and technical matters related to the bank.

For example, when you want to check your total turnover at the end of the month, you can perform cross-validation using both panels. The number of orders you see in the Wix panel should match the number of transactions you see in the İş Bankası panel¹¹,¹². If there is a discrepancy, you can immediately notice and investigate.

Security and Transparency Advantage

One of the biggest advantages of the dual panel structure is security and transparency. Each transaction is recorded in both systems. This way, in case of any abnormality, you can investigate through two separate log systems⁶.

For example, when a customer says "I made payment but order was not created," you can check from the İş Bankası panel whether the payment actually came. If payment came but order was not created in Wix, this indicates a problem in the callback process and your technical team can quickly solve the problem.

Similarly, in the complaint "I placed an order but my money was not withdrawn," you can determine the actual situation by checking order status from Wix panel and provision status from İş Bankası panel¹².

Seamless and Manageable Payment Flow

Wix and İş Bankası Virtual POS connection, when configured correctly, offers a payment system that is both secure and easy to manage. Securely adding API information to Velo backend, establishing hash verification mechanisms, and correctly implementing the callback process form the foundation of the process.

From a customer experience perspective, the process is automatic and smooth - the customer enters their card, verifies at their bank, and the transaction is completed. In the background, robust verification mechanisms work and each step is recorded in both Wix and İş Bankası systems.

For business owners, the dual panel advantage provides operational and financial control together. All processes from daily sales tracking to monthly turnover reports, from manual return transactions to commission calculations become manageable through these two panels.

In conclusion, for businesses that apply technical details correctly and actively use both panels, Wix-İş Bankası integration creates a reliable, transparent, and efficient payment infrastructure.