VakıfBank Virtual POS Setup for Wix: Complete Technical Guide

VakıfBank Virtual POS setup on Wix provides a significant advantage, especially for businesses wanting to accept payments with state bank guarantee. VakıfBank's reliable infrastructure, fast transaction approval, and widespread customer base create a powerful payment alternative for Wix stores. In this guide, we cover the step-by-step setup of VakıfBank Virtual POS on the Wix platform.

What is VakıfBank Virtual POS?

VakıfBank Virtual POS is the online payment solution offered by one of Turkey's leading state banks for e-commerce businesses. The system, which stands out with state bank guarantee, institutional reliability, and wide customer base, creates preference especially for Turkish consumers who shop with a focus on trust.

Integration with the Wix platform is performed through the Velo by Wix development environment. Through this integration, all features of VakıfBank can be utilized beyond standard Wix payment methods.

Key features of VakıfBank Virtual POS include state bank guarantee and institutional reliability, enhanced transaction security with 3D Secure 2.0, Visa, Mastercard, Troy card support, World card and VakıfBank card advantages, flexible installment options ranging from 2-12 months, competitive commission rates, and 24/7 technical support service.

When evaluating VakıfBank POS advantages, the trust effect created by state bank perception stands out. Access to the extensive VakıfBank customer base is provided. Advantageous commission rates are offered for SMEs. Special solutions are available for corporate customers. On-site support opportunity exists through widespread branch network.

VakıfBank Virtual POS Application Process

Before setup, a virtual POS application must be submitted to and approved by VakıfBank. The application process typically completes within 7-14 business days.

Required documents for application include current tax certificate, notarized signature circular, trade registry gazette copy, activity certificate, company authorized person ID photocopy, website URL and content information, and VakıfBank account information (advantage for existing customers).

Application evaluation criteria include business operation duration and registry record, estimated monthly e-commerce turnover, sector risk assessment, website content and security compliance, and existing VakıfBank relationship.

Application channels include VakıfBank branches, online application portal, commercial banking representative, and VakıfBank business banking line.

Information received after application approval includes Merchant ID (Business Number), Terminal ID (Terminal Number), Password (Business Password), 3D Secure Store Key, and API endpoint information.

Required API Information for Integration

After receiving virtual POS approval from VakıfBank, API information provided by the bank is used for setup. This information is critically important and must be stored securely.

Basic API parameters include MerchantId (Business Number), TerminalNo (Terminal Number), Password (Business Password), HostTerminalNo (Host Terminal Number), and StoreKey (3D Secure encryption key).

This information is extremely sensitive and must never be included in frontend code. Wix Secrets Manager offers the ideal solution for securely storing such confidential information.

API endpoint information includes onlineodemetest.vakifbank.com.tr for test environment and onlineodeme.vakifbank.com.tr for production environment. For 3D Secure redirection, 3dsecuretest.vakifbank.com.tr in test environment and 3dsecure.vakifbank.com.tr in production environment are valid.

Wix Velo Development Environment Setup

Before starting setup, the Wix Velo development environment must be properly configured.

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

For Secrets Manager configuration, navigate to Settings from Wix Dashboard. Open the Secrets Manager option. Create separate secrets for each API credential. Naming should be kept standard, such as VAKIFBANK_MERCHANT_ID, VAKIFBANK_TERMINAL_NO, VAKIFBANK_PASSWORD, VAKIFBANK_STORE_KEY.

Required modules and packages include wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data, and crypto-js, which should be installed or imported.

Technical Setup Steps

The setup process consists of five basic stages. Correct completion of each stage is critically important for smooth system operation.

Stage One: Creating backend service file - Create a file named vakifbankPOS.jsw in Wix's backend folder. This file includes payment initiation function, hash calculation function, VakıfBank API communication function, 3D Secure callback verification function, and order update function.

Stage Two: Hash calculation algorithm - This is the most critical component of setup. VakıfBank requires a hash value to ensure transaction security. The hash value creation sequence is MerchantId + TerminalNo + Password + OrderId + Amount + CurrencyCode + StoreKey. These parameters are combined and encrypted with SHA-512 algorithm.

Stage Three: 3D Secure redirect configuration - Two callback URLs are defined: SuccessUrl for successful transactions and FailUrl for failed transactions. These URLs redirect to dynamic pages to be created on your Wix site.

Stage Four: Creating callback endpoint - HTTP functions are written to process responses from VakıfBank. These functions perform parsing of incoming data, hash verification, evaluation of transaction results, and updating of order status.

Stage Five: Frontend integration - Payment form and user interface connection is established. Card information is securely collected and backend functions are called.

3D Secure Payment Flow

3D Secure is a security protocol that provides cardholder verification in online payments. VakıfBank's 3D Secure 2.0 infrastructure offers advanced security features and state bank guarantee.

The payment flow operates as follows: Customer clicks payment button on cart page and enters card information into secure form fields. System calculates necessary hash values in the background and prepares form data. Customer is automatically redirected to VakıfBank 3D Secure page. Transaction is verified with SMS code or VakıfBank Mobile approval. After successful verification, bank posts transaction result to callback URL. Backend verifies incoming response and performs hash check. Order is moved to confirmed status and stock is updated. Customer is redirected to successful payment page.

3D Secure response parameters are evaluated as: Status value can be Y (verified), N (not verified), U (verification could not be performed), or A (attempt made). ResultCode value 0000 indicates successful transaction. ResultDetail contains explanation message in case of error. ProvisionNumber provides authorization code for successful transactions.

Installment Configuration

VakıfBank Virtual POS offers comprehensive installment options. Special campaigns for VakıfBank cards increase conversion rates.

Installment parameters include the InstallmentCount parameter specifying installment count. For single payment, this value is sent as 0 or 1. For installment transactions, values 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 are used.

VakıfBank card advantages include special additional installment opportunity for VakıfBank cardholders, World points earning and spending opportunity, 18-24 installment options during campaign periods, and special advantages for corporate cards.

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

Error Management and Error Codes

Comprehensive error management is critically important in payment setups. Technical details should be logged while displaying understandable messages to users.

Common VakıfBank error codes and descriptions are: Code 0000 indicates successful transaction, code 0001 indicates call card issuing bank, code 0005 indicates unapproved transaction, code 0012 indicates invalid transaction, code 0014 indicates invalid card number, code 0033 indicates expired card, code 0041 indicates lost card, code 0043 indicates stolen card, code 0051 indicates insufficient funds, code 0054 indicates card expiration date passed, code 0057 indicates transaction not permitted to cardholder, code 0058 indicates transaction not permitted to terminal, code 0061 indicates daily limit exceeded, code 0065 indicates daily transaction count exceeded, and code 0091 indicates no response from bank.

Error logging strategy should log all API requests and responses, never log sensitive information (card number, CVV), record timestamp, transaction ID, error code and error message at time of error, and use comprehensive logging solution in production environment.

Security Measures and PCI DSS Compliance

Security has the highest priority in payment setups. PCI DSS compliance is a legal requirement.

Basic security requirements include never having API credentials in frontend code, storing all sensitive data in Secrets Manager, mandatory use of HTTPS protocol, performing hash verification in 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, security vulnerability scans should be performed regularly, access logs should be kept, and personnel security training should be provided.

VakıfBank additional security features include advanced fraud detection system, transaction-based hash verification, IP-based filtering capability, velocity check mechanism, and suspicious transaction alert system.

Testing Process and Going Live

After setup completion, a comprehensive testing process is mandatory. VakıfBank provides separate endpoints and test cards for test environment.

Test environment information is provided through test endpoint address onlineodemetest.vakifbank.com.tr. Test card information is communicated by VakıfBank after application approval.

Test scenario checklist should include successful single payment, successful 3-installment payment, successful 6-installment payment, successful 12-installment payment, payment with VakıfBank card, insufficient balance scenario, invalid card number scenario, expired card scenario, 3D Secure timeout scenario, incorrect SMS code scenario, successful full refund operation, successful partial refund operation, and authorization cancellation operation.

Going live steps are as follows: All test scenarios are completed successfully. Test environment credentials are replaced with production credentials. Endpoint URLs are updated with production URLs. First real transaction is tested with low amount. Transaction is verified from both Wix panel and VakıfBank POS panel.

Refund and Cancellation Operations

Post-sale refund and authorization cancellation operations can be performed both manually and automatically.

Refund types include full refund (entire transaction amount), partial refund (portion of transaction amount), and authorization cancellation (same day, before end of day).

For automatic refund setup, VakıfBank's refund API is used. Call is made with original transaction reference number. Refund amount and currency are specified. Refund operations typically reflect to cardholder's account within 1-3 business days.

For manual operations, log into VakıfBank POS management panel. Find relevant transaction from transaction history. Select refund or cancel option, enter amount and confirm.

Reporting and Reconciliation

After successful setup, payment activities can be monitored from both Wix and VakıfBank panels. Bilateral control facilitates the reconciliation process.

For monitoring on Wix side, track orders from Wix Stores Dashboard. Payment statuses (pending, confirmed, canceled) are displayed. Wix Analytics can be used for custom reporting.

For monitoring in VakıfBank POS panel, daily transaction summary, installment distribution report, card type-based analysis (VakıfBank, Visa, Mastercard), refund and cancellation report, reconciliation reports, and commission detail report can be viewed.

For automatic reconciliation, end-of-day closing can be configured automatically or manually. Reconciliation time is set from VakıfBank POS panel. Daily reconciliation report can be sent via email.

Common Issues and Solutions

Common problems that may be encountered during setup process and solution suggestions are included below.

For hash verification error, check parameter ordering compliance with documentation, verify encoding (UTF-8), check amount format (including kuruş), confirm StoreKey value accuracy, and check that SHA-512 algorithm is used correctly.

For 3D Secure redirect issue, check callback URL accessibility, verify SSL certificate, check that URLs are HTTPS, and grant external redirects permission in Wix site settings.

For timeout errors, check VakıfBank API response times, add retry mechanism, and increase timeout duration (recommended 60-90 seconds).

For installment not appearing issue, check installment authorization in POS definition, verify minimum amount requirements, perform card BIN check, and check campaign definitions.

Conclusion

VakıfBank Virtual POS setup brings the payment infrastructure of one of Turkey's trusted state banks to your Wix e-commerce site. State bank guarantee, competitive commission rates, wide customer base, and strong technological infrastructure provide significant advantages to businesses. Once setup is complete, the business owner can both monitor order activities through the Wix panel and access all payment reports from the VakıfBank POS screen. Due to technical complexity and security requirements, it is recommended that this setup be performed by an experienced developer.

Contact Blakfy for VakıfBank Virtual POS setup and Wix e-commerce solutions: blakfy.com/contact