Wix Garanti Virtual POS Integration

For businesses operating an e-commerce site on the Wix platform, Garanti BBVA Virtual POS integration offers the opportunity to use one of Turkey's strongest payment infrastructures directly. In this guide, we discuss in detail all the technical steps, security requirements, and best practices for integrating the Garanti BBVA virtual POS system with the Wix Velo infrastructure.

What is Garanti BBVA Virtual POS?

Garanti BBVA Virtual POS is an enterprise-level online payment solution developed for e-commerce sites. As one of Turkey's most widely used virtual POS infrastructures, the system stands out with its advanced security features and flexible payment options.

Integration with the Wix platform is carried out through the Velo by Wix development environment. Thanks to this integration, it is possible to go beyond standard Wix payment methods and benefit from all the features of Garanti BBVA.

Key features of Garanti BBVA Virtual POS include transaction security reinforced with 3D Secure 2.0, an advanced fraud protection system, support for Visa, Mastercard, Troy, and American Express cards, flexible installment options ranging from 2 to 12 months, BKM Express and wallet integrations, instant provision and automatic reconciliation, and 24/7 technical support service.

Garanti BBVA Virtual POS Application Process

Before integration, a virtual POS application must be made to Garanti BBVA and approved. The application process is generally completed within 5-10 business days.

Documents required for application are: Current tax plate, notarized signature circular, copy of the trade registry gazette, certificate of activity, photocopy of the company official's ID, website URL, and technical integration document.

Application evaluation criteria include the business's duration of activity and registry record, estimated monthly e-commerce turnover, sector risk assessment, content and security suitability of the website, and existing banking relationship.

Information to be received after application approval includes Terminal ID (9 digits), Merchant ID (workplace number), Provision Password, 3D Secure Store Key, and API user information.

API Information Required for Integration

After virtual POS approval is received from Garanti BBVA, the API information provided by the bank is used for integration. This information is critically important and must be stored securely.

Basic API parameters received include Terminal ID, Merchant ID, Provision Password, Store Key, User ID (API User ID), and User Password (API User Password).

This information is extremely sensitive and must absolutely not be present in frontend codes. Wix Secrets Manager offers an ideal solution for securely storing such confidential information.

API endpoint information used includes sanalposprovtest.garanti.com.tr for the test environment and sanalposprov.garanti.com.tr for the production environment. For the 3D Secure redirection URL, sanalposprovtest.garanti.com.tr/servlet/gt3dengine for test and sanalposprov.garanti.com.tr/servlet/gt3dengine for production are valid.

Wix Velo Development Environment Setup

Before starting the integration, the Wix Velo development environment must be configured correctly.

Steps to activate Velo are as follows: In the Wix Editor, Velo is activated by clicking the Dev Mode button from the top menu. The Code Files section becomes visible on the left panel. New .jsw and .js files can be created under the Backend folder. The Public folder is used for frontend codes.

For Secrets Manager configuration, go to the Settings section from the Wix Dashboard. Open the Secrets Manager option. Create a separate secret for each piece of API information. Naming should be kept standard, for example, GARANTI_TERMINAL_ID, GARANTI_MERCHANT_ID, GARANTI_PROV_PASSWORD, GARANTI_STORE_KEY.

Necessary modules and packages such as wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data, and crypto-js should be installed or imported.

Technical Integration Steps

The integration process consists of five basic stages. Completing each stage correctly is critical for the smooth operation of the system.

First stage: Creating a backend service file involves creating a file named garantiPOS.jsw in Wix's backend folder. This file contains the payment initiation function, hash calculation function, XML request creation function, Garanti API communication function, 3D Secure callback verification function, and order update function.

Second stage: Hash calculation algorithm is the most critical component of the integration. Garanti BBVA requires certain parameters to be encrypted to ensure transaction security. The hash value creation order is TerminalID + OrderID + Amount + SuccessURL + FailURL + Type + InstallmentCount + StoreKey + SecurityData. The SecurityData value is created by hashing the Password + TerminalID combination with SHA-1. These parameters are combined and encrypted with the SHA-512 algorithm.

Third stage: 3D Secure redirection configuration involves defining two callback URLs. The Success URL is used for successful transactions, and the Fail URL for failed transactions. These URLs redirect to dynamic pages to be created on your Wix site.

Fourth stage: Creating callback endpoint involves writing HTTP functions that will process responses coming from Garanti BBVA. These functions perform hash verification of incoming data, check the mdStatus value, evaluate the transaction result, and update the order status.

Fifth stage: Frontend integration establishes the connection between the payment form and user interface. Card information is securely received, and backend functions are called.

3D Secure Payment Flow Details

3D Secure is a security protocol that provides cardholder verification in online payments. Garanti BBVA's 3D Secure 2.0 infrastructure offers advanced security features and higher approval rates.

The payment flow operates as follows: The customer clicks the payment button on the cart page and enters card details into secure form fields. The system calculates necessary hash values in the background and prepares form data. The customer is automatically redirected to the Garanti BBVA 3D Secure page. The transaction is approved via SMS code, mobile app approval, or biometric verification. After successful verification, Garanti POSTs the transaction result to the callback URL. The backend verifies the incoming response, performs a hash check, and checks the mdStatus value. The order status is changed to approved, and stock is updated. The customer is redirected to the successful payment page.

mdStatus values and meanings are as follows: Value 1 indicates full verification (Full 3D Authentication) and the transaction should be approved. Value 2 indicates the cardholder's bank or card is not registered in the system. Value 3 indicates the card is not registered in the system. Value 4 indicates a verification attempt was made (cardholder chose to register later). Value 5 indicates verification could not be performed. Value 6 indicates a 3D Secure error. Value 7 indicates a system error. Value 0 indicates verification failed or the user entered their password incorrectly.

Installment Configuration and Campaign Management

Garanti BBVA Virtual POS offers comprehensive installment options and campaign management capabilities. Installment sales significantly increase customer conversion rates.

As installment parameters, the Number parameter specifies the installment count. For single payments, this value is left blank or sent as 0.

Supported installment options are generally 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, and 12 installments. Special installment options can be offered during campaign periods. Installment interest rates vary according to the tariff determined by Garanti BBVA.

For BIN-based installment control, using the first 6 digits (BIN) of the card number, applicable installment options for that card can be queried. This query ensures only valid installment options are shown to the customer.

Within the scope of campaign integration, campaigns defined from the Garanti POS panel can be added to the payment request with the CampaignCode parameter. Card-specific discounts are applied automatically.

Error Management and Error Codes

Comprehensive error management is critically important in payment integrations. While understandable messages are shown to the user, technical details should be logged.

Common Garanti BBVA error codes and descriptions are: Code 00 indicates a successful transaction, 01 indicates call the issuing bank, 02 indicates call the issuing bank, 05 indicates a declined transaction, 12 indicates an invalid transaction, 13 indicates an invalid amount, 14 indicates an invalid card number, 33 indicates an expired card, 34 indicates a fake card or suspicious transaction, 41 indicates a lost or stolen card, 43 indicates a stolen card, 51 indicates insufficient funds, 54 indicates the card has expired, 57 indicates a transaction not open to the cardholder, 58 indicates a transaction not defined on the terminal, 62 indicates a restricted card, 65 indicates the daily transaction limit exceeded, 75 indicates the incorrect PIN attempt limit exceeded, 91 indicates no response from the bank, and 96 indicates a system failure.

As an error logging strategy, all API requests and responses should be logged, sensitive information (card number, CVV, password) must absolutely not be logged, timestamp, transaction ID, error code, and error message should be recorded at the moment of error, and a comprehensive logging solution should be used in the production environment.

Security Measures and PCI DSS Compliance

Security has the highest priority in payment integrations. Compliance with PCI DSS standards is a legal obligation and ensures customer trust.

Basic security requirements include never having API information in frontend codes, storing all sensitive data in the Secrets Manager, mandatory use of the HTTPS protocol, performing hash verification for every transaction, and conducting regular security audits.

For PCI DSS compliance, card information should not be stored on your servers, tokenization services should be used, vulnerability scans should be performed regularly, access logs should be kept, and staff security training should be provided.

As additional security layers, rate limiting (maximum request limit per minute), IP whitelist (accepting requests from specific IP addresses), request signature (signing every request), velocity check (blocking too many transactions in a short time), and BIN control (monitoring suspicious BIN ranges) can be applied.

Testing Process and Going Live

After integration is completed, a comprehensive testing process is mandatory. Garanti BBVA provides separate endpoints and test cards for the test environment.

Test environment information includes the test endpoint address sanalposprovtest.garanti.com.tr. The test card number 5549608789641500 can be used. Expiration date 12/30, CVV 000, 3D Secure password 'a' are set.

As a test scenario checklist, successful single payment, successful 3-installment payment, successful 6-installment payment, successful 12-installment payment, insufficient funds scenario, invalid card number scenario, expired card scenario, 3D Secure timeout scenario, incorrect 3D password scenario, successful full refund transaction, successful partial refund transaction, and provision cancellation transaction should be tested.

Steps for going live are as follows: All test scenarios are successfully completed. Test environment information is replaced with production information. Endpoint URLs are updated with production URLs. The first real transaction is tested with a low amount. The transaction is verified from both the Wix panel and the Garanti POS panel.

Refund and Cancellation Transactions

Post-sales refund and provision cancellation transactions can be performed both manually and automatically.

Refund types include full refund (entire transaction amount), partial refund (part of the transaction amount), and provision cancellation (cancellation of a transaction made within the same day).

For automatic refund integration, Garanti BBVA's refund API is used. The Type parameter is set to refund. The call is made with OriginalRetrefNum (original transaction reference number). The refund amount is specified. Refund transactions are generally reflected in the cardholder's account within 1-3 business days.

Provision cancellation can only be done within the same day, before the end-of-day closing. The Type parameter is set to void. Amount refund occurs instantly.

For manual transactions, log in to the Garanti POS management panel. Find the relevant transaction from the transaction history. Select the refund or cancellation option, enter the amount, and confirm.

Reporting and Monitoring

After successful integration, payment movements can be monitored from both the Wix and Garanti panels. Double-sided control facilitates the reconciliation process.

For monitoring on the Wix side, orders are tracked from the Wix Stores Dashboard. Payment statuses (pending, approved, cancelled) are viewed. Wix Analytics can be used for custom reporting.

Within the scope of monitoring on the Garanti POS panel, daily transaction summaries, installment distribution reports, card type-based analysis, refund and cancellation reports, reconciliation reports, and commission detail reports can be viewed.

For automatic reconciliation, end-of-day closing can be configured automatically or manually. The reconciliation time is set from the Garanti POS panel. A daily reconciliation report can be sent via email.

Common Problems and Solutions

Common problems encountered during the integration process and solution suggestions are listed below.

For hash verification error, compliance of parameter order with documentation should be checked, encoding (UTF-8) verified, amount format checked (in cents, without dots or commas), accuracy of SecurityData calculation confirmed, and accuracy of the StoreKey value checked.

For 3D Secure redirection problem, accessibility of callback URLs should be checked, SSL certificate verified, URL encoding check performed, and external redirects permission given in Wix site settings.

For timeout errors, Garanti API response times should be checked, a retry mechanism added, and timeout duration increased (recommended 30-60 seconds).

For mdStatus error, whether the 3D Secure password was entered correctly should be checked, whether the card is registered to 3D Secure verified, and whether 3D Secure limits were exceeded on the bank side checked.

Garanti BBVA Virtual POS integration provides your Wix e-commerce site with one of Turkey's strongest payment infrastructures. When configured correctly, you can offer 3D Secure 2.0 safety, flexible installment options, campaign management, and a seamless customer experience. Due to technical complexity and security requirements, it is recommended that this integration be carried out by an experienced developer.