Akbank Virtual POS Integration for Wix: Complete Technical Guide

For businesses operating e-commerce sites on the Wix platform, Akbank Virtual POS integration is the professional way to offer customers secure and installment payment options. In this comprehensive guide, we examine all technical steps for integrating Akbank virtual POS system with Wix Velo infrastructure and points requiring attention in detail.

What is Akbank Virtual POS?

Akbank Virtual POS is a comprehensive online payment solution developed for e-commerce sites. Through 3D Secure 2.0 technology, cardholder identity verification is performed and transaction security is ensured at the highest level. The system offers installment payment options ranging from 2-12 months in addition to single-payment sales.

Integration with the Wix platform is performed through the Velo by Wix development environment. Through this integration, fully customized payment flows can be created beyond standard Wix payment methods.

Key features of Akbank Virtual POS include enhanced transaction security with 3D Secure 2.0, Visa, Mastercard, Troy, and American Express card support, flexible installment options and campaign management, instant authorization and automatic end-of-day reconciliation, mobile payment and contactless transaction compatibility, and 24/7 technical support service.

Akbank Virtual POS Application Process

Before integration, a virtual POS application must be submitted to and approved by Akbank. The application process typically completes within 5-10 business days.

Required documents for application include current tax certificate, notarized signature circular, trade registry gazette copy, activity certificate, website URL, and technical integration information. After application approval, all API information required for integration is communicated by Akbank through secure channels.

Application evaluation criteria include business operation duration, estimated monthly turnover, sector risk assessment, and website content compliance.

Required API Information for Integration

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

Basic API parameters include ClientId (Business Identification Number), StoreKey (Store Security Key), Username (API Username), Password (API Password), Terminal ID (Terminal Number), and 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. If this information falls into the wrong hands, serious financial and security risks may arise.

Wix Velo Development Environment Preparation

Before starting integration, 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 Wix Editor. The Code Files section becomes visible in the left panel. New .jsw 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 and keep naming standard (e.g., AKBANK_CLIENT_ID, AKBANK_STORE_KEY).

Required npm packages include wix-secrets-backend, wix-fetch, crypto-js, and wix-stores-backend.

Technical Integration Steps

The integration 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 payment.jsw in Wix's backend folder. This file includes payment initiation function, hash calculation function, Akbank API communication function, callback verification function, and order update function.

Stage Two: Hash calculation algorithm - This is the most critical component of integration. Akbank requires encryption of specific parameters to ensure transaction security. Hash value creation sequence is ClientId + OrderId + Amount + OkUrl + FailUrl + TranType + InstallmentCount + StoreKey. These parameters are combined and encrypted with SHA-512 algorithm.

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

Stage Four: Creating callback endpoint - HTTP functions are written to process responses from Akbank. These functions perform hash verification of incoming data, check transaction results, and update 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 Details

3D Secure is a security protocol that provides cardholder verification in online payments. Akbank's 3D Secure 2.0 infrastructure offers advanced security features.

The payment flow operates as follows: Customer clicks payment button on cart page and enters card information into secure form fields. System sends payment initiation request to Akbank in the background, and customer is redirected to Akbank 3D Secure page. Verification is performed via SMS, mobile application, or biometric authentication. After successful verification, Akbank 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 2.0 advantages include frictionless flow allowing verification step to be skipped for low-risk transactions, biometric verification support, faster transaction time, enhanced fraud protection, and higher approval rates.

Installment Configuration and Campaign Management

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

Installment parameters include InstallmentCount (number of installments) and TotalInstallment values added to the payment request. For single payment, InstallmentCount value is sent as 0 or 1.

Supported installment options typically include 2, 3, 4, 5, 6, 9, and 12 installments. During campaign periods, 18 or 24 installment options may also be offered. Installment interest rates vary according to Akbank's published tariff.

For campaign management, card-specific campaigns can be defined from Akbank POS panel. Discounts can be applied to specific BIN ranges. Minimum amount conditional installment campaigns can be created.

Error Management and Error Codes

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

Common Akbank error codes and descriptions are: Code 00 indicates successful transaction, code 05 indicates unapproved card (customer should contact bank), code 12 indicates invalid transaction (card details should be checked), code 14 indicates invalid card number, code 33 indicates expired card, code 41 indicates lost card, code 43 indicates stolen card, code 51 indicates insufficient funds, code 54 indicates card expiration date passed, code 61 indicates daily transaction limit exceeded, code 65 indicates daily transaction count exceeded, and code 91 indicates bank not responding (should retry).

Error logging strategy should log all API requests and responses, never log sensitive information (card number, CVV), record timestamp, transaction ID, and error code 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 integrations. 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, IP whitelist configuration, and 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, and access logs should be kept.

Additional security layers may include rate limiting (maximum request limit per minute), request signature (signing each request), SSL pinning (certificate pinning), and fraud detection rules.

Testing Process and Going Live

After integration completion, a comprehensive testing process is mandatory. Akbank provides separate endpoints and test cards for test environment.

Test scenario checklist should include successful single payment, successful 3-installment payment, successful 6-installment payment, successful 12-installment payment, insufficient balance scenario, invalid card number scenario, expired card scenario, 3D Secure timeout 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 Akbank 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 (cancellation of same-day transaction).

For automatic refund integration, Akbank's refund API is used. Call is made with original transaction reference number (HostRefNum). Refund amount and currency are specified. Refund operations typically reflect to cardholder's account within 1-3 business days.

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

Reporting and Monitoring

After successful integration, payment activities can be monitored from both Wix and Akbank panels.

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 Akbank POS panel, daily transaction summary, installment distribution report, card type-based analysis, refund and cancellation report, and reconciliation reports can be viewed.

Recommended KPIs to track include daily/weekly/monthly transaction volume, average cart value, installment usage rate, successful transaction rate, refund rate, and chargeback rate.

Common Issues and Solutions

Common problems that may be encountered during integration process and solution suggestions should be addressed proactively to ensure smooth payment operations and optimal customer experience.

Conclusion

Akbank Virtual POS integration for Wix e-commerce sites provides a secure, feature-rich payment solution that enhances customer trust and increases conversion rates. With proper implementation of 3D Secure 2.0, flexible installment options, and comprehensive security measures, businesses can offer professional payment experiences while maintaining PCI DSS compliance. The integration requires technical expertise but delivers significant value through improved transaction success rates and customer satisfaction.