Wix Finansbank Virtual POS Integration

For businesses operating e-commerce sites on the Wix platform, QNB Finansbank Virtual POS integration offers the opportunity to utilize the reliable payment infrastructure of one of Türkiye's leading banks. Distinguished by its digitally focused approach, advanced technological infrastructure, and CardFinans advantages, QNB Finansbank provides a robust payment solution for e-commerce businesses.

What is QNB Finansbank Virtual POS?

QNB Finansbank Virtual POS is a comprehensive online payment solution developed for e-commerce websites. As the Turkish bank of the Qatar-based QNB Group, this system combines global standard technology with local market knowledge, making it an ideal choice, especially for digitally focused businesses.

Integration with the Wix platform is carried out through the Velo by Wix development environment. This integration allows users to go beyond standard Wix payment methods and take advantage of all the features offered by QNB Finansbank.

Key features of QNB Finansbank Virtual POS include transaction security enhanced with 3D Secure 2.0, advanced fraud detection and protection systems, support for Visa, Mastercard, Troy, and American Express cards, advantages of the CardFinans card program, flexible installment options from 2 to 12 months, fast transaction approval and low latency, a digital-first modern API infrastructure, and 24/7 technical support.

When evaluating the advantages of QNB Finansbank POS , the combination of global banking strength with local expertise, access to the CardFinans customer base, competitive commission rates and flexible packages, and fast application and approval processes thanks to its modern and developer-friendly API structure stand out.

QNB Finansbank Virtual POS Application Process

Prior to integration, a virtual POS application must be submitted to and approved by QNB Finansbank. The application process is usually completed within 5-10 business days.

The required documents for the application are: current tax certificate, notarized signature circular, copy of the trade registry gazette, certificate of activity, photocopy of the company official's ID, website URL and content information, and photocopy of the bank account statement.

Application evaluation criteria include the company's operating duration and registration status, estimated monthly e-commerce turnover, sector risk assessment, website content and security compliance, and existing relationship with QNB Finansbank.

Applications can be submitted through QNB Finansbank branches, the online application portal, a business banking representative, or the Finansbank business banking hotline.

The information to be collected after application approval includes Merchant ID (MbrId), Terminal ID (MerchantId), User Code, User Pass, 3D Secure Store Key (ENCKEY), and API endpoint information.

API Information Required for Integration

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

The basic API parameters include MbrId (Merchant Number - 5 digits), MerchantId (Merchant Code - 16 digits), MerchantPass (Merchant Password), UserCode (User Code), UserPass (User Password), and SecureKey (3D Secure encryption key).

This information is extremely sensitive and should absolutely not be found in frontend code. Wix Secrets Manager offers the ideal solution for securely storing such confidential information.

For API endpoint information , vpostest.qnbfinansbank.com is used for the test environment and vpos.qnbfinansbank.com for the production environment. For 3D Secure redirection, vpostest.qnbfinansbank.com/Gateway/3DHost.aspx is used in the test environment and vpos.qnbfinansbank.com/Gateway/3DHost.aspx is used in the production environment.

Wix Velo Development Environment Setup

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

To activate Velo , click the Dev Mode button in the top menu of the Wix Editor. The Code Files section will appear in the left panel. New .jsw and .js files can be created under the Backend folder. The Public folder is used for frontend code.

To configure Secrets Manager , go to Settings in the Wix Dashboard. Open the Secrets Manager option. Create a separate secret for each API entry. Naming conventions should be standard, for example: FINANSBANK_MBR_ID, FINANSBANK_MERCHANT_ID, FINANSBANK_MERCHANT_PASS, FINANSBANK_SECURE_KEY.

The necessary modules and packages , wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data, and crypto-js, must be installed or imported.

Technical Integration Steps

The integration process consists of five main stages. Completing each stage correctly is critical for the system to function smoothly.

Step 1: As part of creating the backend service file, a file named finansbankPOS.jsw is created in the Wix backend folder. This file contains the payment initiation function, hash calculation function, API request builder function, QNB Finansbank API communication function, 3D Secure callback verification function, and order update function.

Second stage: The hash calculation algorithm is the most critical component of the integration. QNB Finansbank requires a hash value to ensure transaction security. The hash value generation sequence is MbrId + OrderId + Amount + OkUrl + FailUrl + TxnType + InstallmentCount + Rnd + SecureKey. These parameters are combined, encrypted using the SHA-512 algorithm, and encoded in Base64.

Third stage: Two callback URLs are defined for 3D Secure redirection configuration . OkUrl (Success URL) is used for successful operations, and FailUrl (Fail URL) is used for failed operations. These URLs redirect to dynamic pages that will be created on your Wix site.

Fourth stage: As part of creating a callback endpoint, HTTP functions are written to process the responses received from QNB Finansbank. These functions parse the incoming data, perform hash validation, evaluate the transaction result, and update the order status.

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

3D Secure Payment Process Details

3D Secure is a security protocol that provides cardholder verification for online payments. QNB Finansbank's 3D Secure 2.0 infrastructure offers advanced security features and a modern user experience.

The payment process works as follows: The customer clicks the payment button on the shopping cart page and enters their card information into the secure form fields. The system calculates the necessary hash values in the background and prepares the form data. The customer is automatically redirected to the QNB Finansbank 3D Secure page. The transaction is verified with an SMS code or QNB Mobile app confirmation. After successful verification, the bank POSTs the transaction result to the callback URL. The backend verifies the received response and performs a hash check. The order is changed to confirmed status and the stock is updated. The customer is then redirected to the successful payment page.

3D Secure response parameters are evaluated as follows: If the ProcReturnCode value is 00, the transaction is successful. The Status value can be Y (verified), N (failed to verify), U (verification failed), or A (attempted). ErrMsg contains a descriptive message in case of an error. AuthCode provides a provisioning code for successful transactions.

Installment Scheme and CardFinans Advantages

QNB Finansbank Virtual POS offers comprehensive installment options and the advantages of the CardFinans card program. Special campaigns for CardFinans customers increase conversion rates.

The InstallmentCount parameter specifies the number of installments. For single payments, this value is 0 or left blank. For installment transactions, the values 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 are used.

CardFinans offers cardholders special benefits including additional installment options, points earning and spending campaigns, CardFinans mobile application integration, and special occasion campaigns (New Year, holidays, etc.).

For BIN-based installment payment inquiries, the first 6 digits of the card number can be used to view the available installment options for that card. This query ensures that only the currently available installment options are displayed to the customer.

During campaign integration , campaigns defined in the QNB Finansbank POS panel can be queried via API. Card-specific discounts and additional installments are applied automatically.

Error Management and Error Codes

Comprehensive error management is critical in payment integrations. Technical details should be logged while displaying clear messages to the user.

Common QNB Finansbank error codes and their explanations are as follows: 00 indicates a successful transaction, 01 indicates contacting the card-issuing bank, 02 indicates contacting the card-issuing bank, 03 indicates an invalid merchant, 04 indicates card confiscation, 05 indicates an unapproved transaction, 06 indicates an invalid transaction, 07 indicates card confiscation (fraud), 08 indicates fraudulent approval, 09 indicates a retry, 12 indicates an invalid transaction, 13 indicates an invalid amount, 14 indicates an invalid card number, 15 indicates contacting the card-issuing bank, 33 indicates an expired card, 34 indicates suspected fraud, 36 indicates a restricted card, 41 indicates a lost card, 43 indicates a stolen card, 51 indicates insufficient balance, 52 indicates checking the account number, 53 indicates an account not found, 54 indicates that the expiration date has passed, 55 indicates an incorrect PIN, 56 indicates that the card is not registered, 57 indicates an unauthorized transaction by the cardholder. Code 58 indicates an unauthorized transaction at the terminal, code 61 indicates exceeding the daily limit, code 62 indicates a restricted card, code 63 indicates a security breach, code 65 indicates exceeding the daily transaction limit, code 75 indicates exceeding the PIN attempt limit, code 91 indicates no response from the card-issuing bank, and code 96 indicates a system malfunction.

As a fault logging strategy , all API requests and responses should be logged, sensitive information (card number, CVV, PIN) should absolutely not be logged, timestamps, transaction ID, fault code, and fault messages should be recorded at the time of the fault, and a comprehensive logging solution should be used in the production environment.

Security Measures and PCI DSS Compliance

Security is the highest priority in payment integrations. Compliance with PCI DSS standards is a legal requirement.

Basic security requirements include ensuring API information is never found in frontend code, storing all sensitive data in Secrets Manager, mandatory use of HTTPS protocol, performing hash verification on every transaction, and conducting regular security audits.

To ensure 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 maintained, and personnel should receive security training.

QNB Finansbank offers advanced fraud detection algorithms, a velocity check system, BIN-based risk assessment, IP-based filtering, and a suspicious transaction alert system as additional security features .

Testing Process and Go-Live

A comprehensive testing process is mandatory after the integration is complete. QNB Finansbank provides separate endpoints and test cards for the test environment.

Test environment information is provided via the test endpoint address vpostest.qnbfinansbank.com . Test card information will be sent by QNB Finansbank after application approval.

The test scenarios to be checked as a checklist include: successful single payment, successful 3-installment payment, successful 6-installment payment, successful 12-installment payment, payment with CardFinans card, insufficient balance scenario, invalid card number scenario, expired card scenario, 3D Secure timeout scenario, incorrect SMS code scenario, successful full refund transaction, successful partial refund transaction, and provision cancellation transaction.

The 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 QNB Finansbank POS panel.

Return and Cancellation Procedures

Post-sales return and pre-authorization cancellation processes can be performed both manually and automatically.

Refund types include full refund (entire transaction amount - TxnType: Refund), partial refund (partial transaction amount - TxnType: Refund specifying the amount), and cancellation of authorization (same day, before the end of the day - TxnType: Void).

QNB Finansbank's refund API is used for automatic refund integration . The call is made using the original transaction reference number (OrderId or AuthCode). The refund amount and currency are specified. Refunds are usually reflected in the cardholder's account within 1-3 business days.

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

Reporting and Reconciliation

Following a successful integration, payment transactions can be tracked from both the Wix and QNB Finansbank panels.

On the Wix side , orders are tracked via the Wix Stores Dashboard. Payment statuses (pending, confirmed, canceled) are displayed. Wix Analytics can be used for custom reporting.

Within the QNB Finansbank POS panel, users can view daily transaction summaries, installment distribution reports, card type-based analysis (CardFinans, Visa, Mastercard), refund and cancellation reports, reconciliation reports, commission detail reports, and CardFinans campaign reports.

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

Sectoral Usage Recommendations

QNB Finansbank Virtual POS offers solutions tailored to the needs of various sectors.

For e-commerce stores, installment sales to increase basket value, CardFinans campaigns to attract customers, a faster checkout experience, and inventory management integration are recommended.

For the service sector, consulting fees, subscription systems, one-time service payments, and invoice-based collection can be applied.

Course registration payments, installment payment options for training packages, online course payments, and certificate program payments can be made through educational platforms .

For the healthcare sector , patient payments, installment treatment plans, online appointment payments, and check-up package sales can be implemented.

Common Problems and Solutions

Common problems that may be encountered during the integration process and suggested solutions are listed below.

To verify a hash validation error , check that the parameter order conforms to the documentation, verify the encoding (UTF-8), check the amount format (including cents, without periods or commas), confirm the accuracy of the SecureKey value, and ensure that the Base64 encoding is correctly applied.

To resolve 3D Secure redirect issues , check the accessibility of callback URLs, verify the SSL certificate, ensure URLs are HTTPS, and enable external redirects in Wix site settings.

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

To resolve the issue of installments not appearing , check the installment authorization in the POS settings, verify the minimum payment requirements, perform a card BIN check, and review the campaign definitions.

QNB Finansbank Virtual POS integration provides your Wix e-commerce site with a modern and reliable payment infrastructure. With its digitally focused approach, advanced fraud protection systems, CardFinans advantages, and competitive commission rates, QNB Finansbank is a strong choice for e-commerce businesses. When properly configured, it offers 3D Secure 2.0 security, flexible installment options, and a seamless customer experience. Due to the technical complexity and security requirements, it is recommended that this integration be performed by an experienced developer.

For QNB Finansbank Virtual POS integration and Wix e-commerce solutions, contact Blakfy: blakfy.com/iletisim