VakıfBank POS Integration: Setting Up a Secure Payment System on Your Wix Site

For businesses running e-commerce sites on Wix, VakıfBank POS integration is one of the most effective ways to offer customers reliable and installment-based payment options. In this guide, we cover the technical steps and points to consider for integrating the VakıfBank virtual POS system with the Wix Velo infrastructure.

What is VakıfBank Virtual POS?

VakıfBank virtual POS is an online payment infrastructure developed for e-commerce sites. Thanks to 3D Secure support, cardholder verification is performed, and transaction security is ensured. The system offers single payment and installment sales options, as well as the ability to define campaigns specific to different card programs.

Integration with the Wix platform is carried out through the Velo by Wix (formerly Corvid) development environment. This integration makes it possible to create customized payment flows beyond standard Wix payment methods.

Information Required for Integration

Once the virtual POS application to VakıfBank is approved, the information provided by the bank is used for integration. This information includes the Merchant ID, Terminal ID, 3D Secure Encryption Key (ENCKEY), and API username and password.

This information is highly sensitive and should only be stored in backend codes. Wix Secrets Manager offers an ideal solution for securely storing such confidential information.

Technical Integration Steps

The integration process consists of several basic stages, and the correct configuration of each stage is critical for the smooth operation of the system.

Wix Secrets Manager configuration is the first step. After activating the Velo development mode in the Wix Editor, the Secrets Manager is accessed. Here, the Merchant ID, Terminal ID, and ENCKEY values provided by VakıfBank are defined individually. These values are used by calling them from the backend codes.

Creating a backend service file is the second stage. A JavaScript file is created in Wix's backend folder to manage payment transactions. This file performs operations such as preparing the payment initiation request, calculating the hash value, sending a request to the VakıfBank API, and creating the 3D Secure redirection URL.

The hash calculation algorithm is the most critical component of the integration. VakıfBank requires certain parameters to be encrypted to ensure transaction security. The hash value is created by combining parameters such as Merchant ID, Terminal ID, transaction amount, order number, and ENCKEY in the specified order and encrypting them with the SHA-512 algorithm.

Callback URL configuration is the fourth stage. When 3D Secure verification is completed, VakıfBank sends the transaction result as a POST request to the determined callback URL. Verification of the incoming data and updating of the order status are performed at this URL.

3D Secure Payment Flow

The customer follows a specific flow during the payment process. First, they click the payment button on the cart page and enter their card details into secure form fields. The system sends a payment initiation request to VakıfBank in the background, and the customer is redirected to the VakıfBank 3D Secure page. Here, verification is done via SMS or mobile application. If the verification is successful, VakıfBank sends the transaction result to the callback URL. The backend verifies this response and changes the order status to approved. Finally, the customer is redirected to the successful payment page.

Installment Configuration

VakıfBank POS supports different installment options. Additional parameters are added to the payment request for installment transactions. The InstallmentCount parameter specifies the number of installments, and NumberOfInstallments specifies the total count of installments. Different installment options can be offered for different card programs, and this configuration is managed from the VakıfBank POS panel.

Error Management and Logging

Error management is critically important in payment integrations. Possible error scenarios include hash verification errors, timeouts, insufficient funds, exceeding card limits, and 3D Secure verification failures.

For each error condition, understandable messages should be shown to the user, and technical details should be recorded with a logging system. Wix's console.log function can be used during the development phase, but a more comprehensive logging solution should be preferred in the production environment.

Security Measures

Security comes first in payment integrations. Basic security measures include never having API information in frontend codes, storing all sensitive data in the Secrets Manager, mandatory use of the HTTPS protocol, IP restriction configuration, and regular security audits.

Additionally, regarding PCI DSS compliance, it is important to remember that card information should not be stored on your servers. Tokenization services provided by VakıfBank offer a secure alternative for recurring payments.

Testing and Going Live

After the integration is completed, comprehensive tests must be conducted. Successful payment scenarios with test cards, failed payment scenarios (insufficient funds, invalid card), installment payment tests, and refund transaction tests should be performed.

VakıfBank provides separate endpoints and test cards for the test environment. After all tests are successfully completed, the switch to live is made with production information.

Refund and Cancellation Transactions

Post-sales refund and provision cancellation transactions can be performed manually via the VakıfBank POS panel. VakıfBank's refund API can be used for automatic refund integration. This API is called with the original transaction reference number, and the transaction is performed by specifying the refund amount.

VakıfBank POS integration provides your Wix e-commerce site with a professional payment infrastructure. When configured correctly, you can offer 3D Secure safety, installment options, and a seamless payment experience. Due to technical infrastructure requirements and security standards, it is recommended that this integration be carried out by an experienced developer.