Garanti BBVA Virtual POS Setup on Wix Platform: Comprehensive Technical Guide

Installation of the Garanti BBVA Virtual POS system on the Wix platform is critically important for e-commerce businesses to establish a secure and professional payment infrastructure. This integration process is carried out through Velo backend technology offered by Wix and provides businesses with bank-level security standards. Proper configuration of the installation phase both improves customer experience and enables the business to have full control over payment processes.

Obtaining API Information and System Preparation

The first and most fundamental step of Garanti BBVA Virtual POS integration is to complete the virtual POS application by contacting the bank's business solution center. This process includes an approval process that evaluates your business's commercial activities and financial structure. When your application is approved, special identification information is allocated to you by Garanti BBVA. This information includes Merchant ID (Member Business Number), Terminal No (Terminal Number), Provision Username, Provision Password, and Store Key used for 3D Secure transactions.

Merchant ID is your business's unique identification number at the bank, and all transaction records are kept under this number. Terminal No can be thought of as the digital equivalent of a physical POS device, and you can manage your different sales channels separately with multiple terminal numbers. Provision password is a critical security key used in transaction verification and hash calculations and must be kept absolutely confidential. Store Key is the encryption key used in 3D Secure transactions.

In addition to this information, Garanti BBVA provides separate API endpoint addresses for test environment and live environment. While the address sanalposprovtest.garanti.com.tr is used for test environment, the address sanalposprov.garanti.com.tr is used for live transactions. Since tests you perform in the test environment will not cause actual money movement, it is strongly recommended that you actively use this environment during the development process. API reference guides, sample codes, and integration scenarios are explained in detail at sanalposdokumantasyon.garanti.com.tr, which is Garanti BBVA's official documentation portal.

Velo Backend Configuration and Security Layers

Velo technology offered by the Wix platform provides a comprehensive backend development environment. Velo is JavaScript-based and offers a working environment similar to Node.js. For Garanti POS integration, you first need to access the Backend folder from the Code Files section in Wix Editor. JavaScript files you create in the Backend folder will run server-side and protect your sensitive information.

As a first step, functions should be written to send HTTP requests to Garanti API using the wix-fetch module. However, storing your API keys directly in the code creates serious security risks. Therefore, you need to securely store sensitive information such as Merchant ID, Terminal No, Provision Password, and Store Key using Wix's Secrets Manager feature. To access Secrets Manager, you can open the Secrets Manager tab by going to the Site Settings section from Wix Dashboard. You can access secret values you create here from your backend code through the wix-secrets-backend module.

Basic functions that need to be created in backend configuration are as follows: initiatePayment function that initiates the payment transaction, generateHash function that creates security signature with SHA-512 hash algorithm, processCallback function that processes 3D Secure callback data, and verifyTransaction function that verifies transaction result. Each function should have comprehensive error management mechanisms, and all critical operations should be recorded in log files. You can view logs in Velo Developer Console and perform debugging operations with the console.log function provided by Wix.

Another critical point in terms of security is Cross-Origin Resource Sharing (CORS) configuration. To avoid encountering CORS errors in requests made to Garanti API, your backend functions should be defined as backend modules, not web modules. How to create and configure backend modules is explained in detail at wix.com/velo/reference, which is Wix Velo's official documentation.

Defining 3D Return URLs and HTTP Endpoint Setup

Garanti BBVA's 3D Secure system sends transaction results to the URL addresses you specify after customers complete identity verification. Therefore, separate callback URLs need to be defined for successful and failed transactions. HTTP functions are used to create these URLs on the Wix Velo platform. You can define these endpoints by creating a file named http-functions.js in the Backend folder.

For successful transactions, for example, a success3d endpoint can be created. This endpoint must work with POST method and be able to receive all parameters from Garanti. Parameters sent by Garanti include mdStatus (3D Secure status code), xid (transaction ID), oid (order number), authCode (approval code), procReturnCode (transaction result code), response (response code), errmsg (error message), hostmsg (bank message), hash (security signature), and hashparams (hash parameters). Each of these parameters is used at different stages of the transaction flow.

Your success callback URL will be in this format: https://your-site-address.wixsite.com/mysite/_functions/success3d. You need to send this URL to Garanti as the successurl parameter during payment initiation stage. Similarly, an error3d endpoint should be created for failed transactions and transmitted as the errorurl parameter. These URLs must work with HTTPS protocol; otherwise, the Garanti system will not accept these URLs.

The first operation you should do in your callback functions is to verify the incoming hash value. The hash parameter returned from Garanti guarantees the integrity of transaction data and prevents manipulation. For hash verification, you should take the parameters specified in the incoming hashparams value in order and combine them, add Store Key to the end, and pass through SHA-512 algorithm. The hash value you obtain should match exactly with the hash value from Garanti. If there's no match, the transaction is not reliable and must be rejected.

Technical Details of Payment Flow and 3D Secure Integration

When the customer enters payment information on the checkout page and clicks the "Complete Payment" button, your Velo backend function comes into play. As the first stage, card information entered by the customer, order amount, and customer information are received. A request in XML format to be sent to Garanti API is created with this data. The XML structure is specified in detail in Garanti's documentation and must conform to a specific schema.

In the XML request, the Mode parameter is specified as "PROD" (live environment) or "TEST" (test environment). The Version parameter shows the API version and generally the value "v0.01" is used. ProvUserID, UserID, and HashData information are included in Terminal. Customer information section should contain customer's IP address, email address, and phone number. Card information includes card number, expiration date, and CVV code. Order section contains OrderID (unique order number), GroupID, and order description.

Transaction section contains transaction details. Type parameter specifies "sales" (sale), Amount is in kuruş, CurrencyCode is currency code (949 for TRY), and InstallmentCnt is installment count. CardholderPresentCode value should be set as "0" (e-commerce). After this XML structure is created, it is POSTed to Garanti's 3D Secure gateway address. The address https://sanalposprovtest.garanti.com.tr/VPServlet is used for test environment, https://sanalposprov.garanti.com.tr/VPServlet for live environment.

After the request is sent, the Garanti system redirects the customer to the 3D Secure verification screen. On this screen, the customer uses the verification method determined by their bank. The most common method is one-time password sent via SMS, but some banks also offer different methods such as approval via mobile application, biometric verification, or password entry. When the customer completes verification or fails, the Garanti system redirects the customer to the callback URLs you specified.

Transaction Result Verification and Order Management

A multi-layered verification process should be applied while processing callback data from Garanti. The first layer is the hash verification mentioned earlier. After hash verification is successful, the mdStatus parameter should be checked. If mdStatus value is "1", "2", "3", or "4", 3D Secure verification is successful. If the value is "0", "5", "6", "7", or "8", verification has failed or could not be completed.

Even if mdStatus is successful, it is necessary to check whether the transaction has been approved by the bank. The Response parameter is checked for this. If Response value is "Approved," the transaction is approved. If ProcReturnCode parameter is "00," the transaction has been completed successfully. Different ProcReturnCode values indicate different error situations. For example, "05" indicates insufficient balance, "51" indicates card limit exceeded, "54" indicates card expiration date has passed, "57" indicates cardholder does not have authorization to perform this transaction.

After all verifications are successful, order status should be updated in your Wix Data database. Before marking order status as "payment completed," you must be sure that the transaction is actually approved in the bank's system as well. For this, you can optionally check transaction status once more using Garanti's inquiry API. This double verification mechanism provides extra protection against possible fake notification attacks.

Critical information that should be kept in your order database includes unique order number, customer information, order amount, payment status, transaction date, authCode (approval code) returned from Garanti, HostRefNum (bank reference number), and RetrefNum (reference number). This information will be used in refund, cancellation, or reconciliation operations. Also, as per PCI-DSS compliance, you should never store sensitive information such as card number and CVV in your database.

Installment Sales Configuration and Installment Options

Garanti BBVA Virtual POS system gives businesses the opportunity to offer flexible installment options. To configure installment sales, you first need to agree with your bank and determine how many installments you will offer for which card types. Different installment rates and commission structures exist for each bank and card type. You should create an installment table to dynamically show installment options in your Wix integration.

To create an installment table, you can use Garanti's Installment Rates Query API. This API returns how many installments can be made with which cards for a specific amount and the interest rates to be applied for each installment. This information from the API is shown to the customer on the checkout page. The customer selects the desired installment count, and this information is sent to Garanti as the InstallmentCnt parameter when payment transaction is initiated.

If installment count is sent as "0" or "1," single payment is made. For installment count values of 2 and above, installment sales are performed. During some promotional periods, banks may offer zero-interest installment opportunities. In this case, commission rate appears as zero, and the customer can installment without additional payment. However, as a business, you pay the commission rate determined by the bank. Therefore, when calculating your profit margin in installment sales, it is important to consider this cost.

When showing installment options in Wix, it is recommended to show monthly payment amount and total payment amount next to each installment option to improve user experience. For example, when 3 installments are selected for a product worth 1000 TL, a display like "3 x 340 TL (Total: 1020 TL)" ensures clear customer information.

Managing Refund and Cancellation Transactions

Being able to digitally manage refund and cancellation transactions for e-commerce businesses significantly increases operational efficiency. Garanti BBVA Virtual POS system offers the opportunity to perform refund and void transactions through API. Cancellation transaction is performed for transactions not yet finalized by the bank and is generally valid for transactions within the same day. Refund transaction is performed for finalized transactions and means returning money to the customer's card.

For cancellation transaction, Transaction Type parameter in XML request to be sent to Garanti API is set as "void". For refund transaction, the value "refund" is used. OrderID, authCode, and HostRefNum information of the original transaction are needed to perform the transaction. Therefore, as mentioned earlier, storing this information for each transaction in your database is critically important.

Partial refund transactions are also supported. For example, if you want to refund only 200 TL portion of a 500 TL transaction, it is sufficient to send Amount parameter as 20000 kuruş (200 TL) in refund request. However, care should be taken that total refund amount does not exceed original transaction amount. You can easily perform these operations by adding "Refund" or "Cancel" buttons to order detail page in your Wix management panel.

Refund and cancellation transactions must be logged and notified to customer via email or SMS. In refund transactions, reflection of money to customer's account varies by bank but generally takes 3-7 business days. Clearly informing customer of this period is important for customer satisfaction.

Successful Transaction Notifications and Customer Communication

Informing customer when payment transaction is completed successfully is critical both as a legal obligation and for customer satisfaction. After receiving successful transaction notification from Garanti BBVA system, you can use Wix's email sending functions to automatically send email to customer. You can send customized email to customer with emailContact function through wix-crm-backend module.

Email content should include information such as order number, order details, total amount, payment method, estimated delivery date, and cargo tracking number (if ready). Additionally, links should be provided to access invoice and receipt information. Email design should be compatible with your brand's visual identity and display a professional appearance. You can create email templates with Wix's Ascend by Wix tool and define automatic sending rules.

SMS notifications are also an effective communication channel especially for mobile users. You can send instant SMS to customer when transaction is approved using SMS services integrated with Garanti BBVA. SMS content should be short and concise, containing order number and order status tracking link. Compliance with TTDDK's Message Management System (İYS) regulations is mandatory for sending SMS in Turkey; therefore, customer must have approved receiving commercial electronic messages.

You can enable customers to track their own orders by creating an order tracking panel through Wix Dashboard. This panel should be accessible when customer logs into their account and should show real-time order status. Order status should be updated with stages such as "payment received," "being prepared," "shipped," "delivered."

High Security Standards and PCI-DSS Compliance

Payment Card Industry Data Security Standard (PCI-DSS) determines mandatory security standards for all systems where credit card information is processed. To ensure PCI-DSS compliance in your Wix-Garanti integration, you need to comply with certain critical rules. The most basic rule is that sensitive information such as card number, CVV code, and expiration date should never be stored, logged, or written to database on your server.

Thanks to Garanti's 3D Secure system, card information is entered directly on the bank's secure page; therefore, card information transit through your system is minimized. However, the area where customer enters card information on your checkout form should still be protected with HTTPS, and form data should be sent over encrypted channel when submitted. Wix platform automatically provides SSL certificate and serves all pages over HTTPS.

API keys, passwords, and security tokens used in your backend codes must be stored in encrypted environment. As mentioned earlier, Wix Secrets Manager is an ideal solution for this purpose. Additionally, access control should be applied to your backend functions, and only authorized users should be able to perform sensitive operations. You can define role-based access controls with Wix's Permissions API.

Regular security audits and keeping the system updated are critical. Although Wix platform provides automatic security updates, custom codes you develop need to be tested against security vulnerabilities. You should take measures against common security vulnerabilities by referencing the OWASP Top 10 security risks list. Protection mechanisms should be implemented against attack types such as SQL injection, XSS (Cross-Site Scripting), CSRF (Cross-Site Request Forgery).

Performance Optimization and Scalability

Speed and reliability of payment process in e-commerce sites directly affect customer experience. Timeout periods in requests made to Garanti API should be optimized and response times should be minimized. You can prevent API requests from blocking page loading time by using asynchronous programming techniques in Wix Velo backend functions. JavaScript's Promise and async/await structures will help you in this regard.

Caching frequently used data can improve performance. For example, since installment rates do not change daily, you can prevent making API query in each transaction by caching this information. You can establish cache mechanisms with Wix Data API or benefit from Wix's built-in cache features. However, it is important to carefully set cache duration and ensure that outdated data is not shown to customer.

Load testing is recommended to ensure system stability during high traffic periods. Although Wix platform offers automatic scaling feature, backend functions you develop need to be optimized. Unnecessary database queries, loops, and memory usage should be minimized. You can monitor performance of your backend functions and detect bottlenecks with Wix Velo's Performance Monitoring tools.

Error handling and retry mechanisms should be properly configured. Network timeout or temporary problems on bank side may occur in requests made to Garanti API. In these situations, automatic retry mechanism should be established, but retry count should be limited to avoid infinite loop. You can increase waiting time in each retry using exponential backoff strategy.

Documentation and Technical Support Resources

API reference guides, sample codes, error codes list, and integration scenarios are presented in detail at sanalposdokumantasyon.garanti.com.tr, which is Garanti BBVA's official technical documentation portal. Test card information, sandbox environment access details, and frequently asked questions section are available on this platform. It is recommended to first review this documentation for technical problems you encounter during integration process.

Wix Velo's official documentation is located at wix.com/velo/reference. This resource contains comprehensive information about Velo APIs, backend modules, database operations, HTTP functions, and security best practices. Wix's Developer Forum also offers active community support and allows you to benefit from other developers' experiences.

You can receive technical support by contacting Garanti BBVA Business Solution Center via phone or email. Integration Support team provided by the bank produces solutions to problems you encounter during integration process and provides guidance on configuration. Additionally, you can access transaction reports, reconciliation information, and terminal settings through Enpara.com Virtual POS Management Panel, which is Garanti BBVA's merchant portal.

Conclusion

When this comprehensive integration process is completed, your business will be able to use the payment infrastructure of one of Turkey's most reliable banks seamlessly on the Wix platform. You can provide your customers with uninterrupted and secure payment experience by ensuring continuity of your system with regular maintenance, security updates, and performance optimizations.