Wix and Garanti POS Integration: Detailed Technical Guide

Implementing Garanti BBVA virtual POS integration on the Wix platform is critically important for e-commerce businesses to establish a secure payment infrastructure. This integration process includes many stages from technical infrastructure setup to security protocols.

Preliminary Preparation and Required Documents

Before starting the integration process, it is necessary to make a commercial agreement with Garanti BBVA and complete the virtual POS application. During this process, critical identification information such as Terminal ID (Terminal Number), Merchant ID (Member Business Number), Provision User ID, and Provision Password are allocated specifically for your business. This information forms the basis of all API communication and must be stored securely.

You can access general information about virtual POS services at garanti.com.tr/tr/isyerleri/sanal-pos, which is Garanti BBVA's official developer portal. For technical documentation, it is recommended to visit sanalposdokumantasyon.garanti.com.tr. These resources provide API references, sample codes, and integration guides.

Velo Backend Infrastructure Setup

The Velo code environment offered by the Wix platform is at the heart of Garanti POS integration. Velo is a JavaScript-based development environment that allows you to add custom backend functions to your Wix sites. For integration, you need to establish a connection to the Garanti API using the HTTP module in your backend folder.

As a first step, functions should be created to send requests to Garanti API endpoints using the wix-fetch module. The address sanalposprovtest.garanti.com.tr is used for the test environment, and sanalposprov.garanti.com.tr for the live environment. This separation allows you to test without risking real payment transactions during the development process.

Basic functions to be created in the backend should include payment initiation, hash generation, 3D Secure verification, and transaction result checking. Error management and logging mechanisms must be added for each function. You can securely store your API keys using Velo's Secrets Manager feature, so sensitive information does not appear openly in your code.

Hash Algorithm and Security Layers

The most critical security element of Garanti BBVA virtual POS integration is the SHA-512 hash algorithm. This algorithm guarantees the integrity of transaction data and prevents unauthorized changes. The hash generation process must be performed in a specific order.

For hash calculation, Terminal ID, Order ID (order number), amount information, last four digits of credit card number, success and error URLs along with provision password are combined and passed through the SHA-512 algorithm. As a result of this process, a 128-character hash value is obtained. This hash value must be included in every request sent to Garanti API and must be verified by the bank.

In the callback stage, it is critically important that the hash value returned from the bank is recalculated on the server side and compared. The transaction result should not be trusted and the order status should not be updated without this verification. Otherwise, the system can be manipulated with fake transaction notifications.

3D Secure Payment Flow

Garanti BBVA's 3D Secure system provides an additional security layer to verify the cardholder's identity. When a payment transaction is initiated, the user is automatically redirected to the bank's 3D Secure page. On this page, the cardholder completes the transaction by approving through an SMS code sent to their phone number or through a mobile application.

An HTML form must be created for the redirect operation, and this form must be sent to Garanti's 3D Secure gateway address via POST method. The form should contain Terminal ID, Merchant ID, order number, amount, installment information, card information, and hash value. You need to dynamically create and submit this form on your Wix site's checkout page.

When 3D Secure verification is completed, the bank redirects the user to the success or error callback URLs you specified earlier. These URLs must be HTTP functions defined in Velo backend. These functions that receive and process callback data save the transaction result to your database after hash verification and display the appropriate page to the user.

Order Management and Database Integration

Wix Data (database) should be used to store order information on the Wix platform. A unique order number (Order ID) must be created for each payment transaction, and this number should be both sent to Garanti API and stored in your own database. Through this matching, you can associate callback data with the correct order.

It is recommended to create an enum structure for order statuses: statuses such as pending, payment initiated, in 3D Secure, payment successful, payment failed can be defined. Order status should be updated at each stage. Additionally, all API responses and error messages should be recorded for logging purposes. These logs are vitally important for troubleshooting.

You can track your transactions, perform reconciliation, and carry out reporting operations through the Enpara.com Virtual POS Management Panel provided by Garanti BBVA. Through this panel, you can view your test and live environment transactions separately.

Testing Process and Error Management

Comprehensive testing is mandatory before going live. Different scenarios such as successful payment, insufficient balance, incorrect card information, 3D Secure error should be tested using Garanti BBVA test cards. Test card information is available in Garanti's technical documentation.

User-friendly messages should be prepared for every possible error situation. Technical error codes should not be shown directly to the user; instead, understandable explanations should be provided. For example, instead of the error code "05 - Transaction not approved," a message like "Your bank did not approve the transaction. Please contact your bank or try a different card" can be shown.

A retry mechanism should be established for timeout situations. A timeout period of 30 seconds should be set for requests made to Garanti API, and the user should be informed when this period is exceeded. Additionally, the number of automatic retries in case of network errors should be limited.

Security and Compliance Requirements

Compliance with PCI DSS (Payment Card Industry Data Security Standard) standards is critically important. Credit card information should never be stored, logged, or written to the database on your server. Card information should be transmitted directly to Garanti's system.

SSL certificate must be installed and all payment pages must be served over HTTPS protocol. Although Wix automatically provides SSL, if you are using a custom domain, you must ensure that the certificate is active.

Within the scope of KVKK (Personal Data Protection Law), necessary legal texts should be prepared regarding the storage and processing of customer information. Privacy policy and terms of use links must be present on the payment page.

Performance Optimization and User Experience

Fast loading of the payment page is critical for user experience. You should minimize API response times by optimizing your Velo functions. You can prevent page freezes by using asynchronous operations.

A loading indicator should be added during redirection to the 3D Secure page. The user should see that the transaction is ongoing and understand that they need to wait. Smooth transitions should be used in page redirects after callback.

Mobile compatibility tests must be performed. Although Wix offers responsive design, it should be ensured that payment forms work properly on small screens in particular. The situation where the 3D Secure page is blocked by popup blocker on mobile devices should be tested.

Documentation and Support Resources

For technical support, you can contact Garanti BBVA's business solution center. Additionally, Wix Velo Documentation (wix.com/velo/reference) provides detailed information about HTTP requests, database operations, and backend functions.

It will be useful to review the Wix Community forums and Garanti BBVA's FAQ (Frequently Asked Questions) section for common problems and solutions encountered during integration. There are also open-source Garanti POS integration examples on GitHub, but these need to be carefully examined for security.

Successful completion of this integration ensures that your business acquires a professional and reliable payment infrastructure. System continuity should be guaranteed with regular maintenance, security updates, and performance monitoring.