Ziraat Bank Virtual POS Integration for Wix: Complete Technical Guide

For businesses operating e-commerce sites on the Wix platform, Ziraat Bank Virtual POS integration offers the opportunity to use Turkey's most established and trusted bank's payment infrastructure. This integration provides businesses seeking to accept payments with state bank guarantee the chance to increase customer trust while benefiting from competitive commission rates.

What is Ziraat Bank Virtual POS?

Ziraat Bank Virtual POS is the online payment solution offered by Turkey's oldest and most widespread bank for e-commerce businesses. The system stands out with its state bank status, extensive customer base, and robust infrastructure, creating a 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, you can go beyond standard Wix payment methods and benefit from all features of Ziraat Bank.

Key features of Ziraat Bank Virtual POS include state bank guarantee and institutional reliability, enhanced transaction security with 3D Secure 2.0, Visa, Mastercard, and Troy card support, flexible installment options and campaign management, competitive commission rates, on-site support opportunities through extensive branch network, and 24/7 technical support service.

When evaluating the advantages of Ziraat Bank POS, access to Turkey's most widespread bank card user base, the trust effect created by state bank perception, advantageous commission rates for SMEs, special campaigns for agriculture and production sectors, and widespread ATM and branch network support stand out.

Ziraat Bank Virtual POS Application Process

Before integration, a virtual POS application must be submitted to and approved by Ziraat Bank. 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 bank account details (having a Ziraat Bank account provides advantages).

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 Ziraat Bank relationship.

Information received after application approval includes Merchant ID (Business Number), Terminal ID (Terminal Number), POSNET ID, 3D Secure Encryption Key (ENCKEY), and API user credentials.

Required API Information for Integration

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

Basic API parameters include Merchant ID (MID - Business Number), Terminal ID (TID - Terminal Number), POSNET ID (POS identification number), ENCKEY (3D Secure encryption key), API username, and API password.

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 setmpos.ykb.com/PosnetWebService/XML for test environment, www.posnet.ykb.com/PosnetWebService/XML for production environment. For 3D Secure redirection, setmpos.ykb.com/3DSWebService/YKBPaymentService in test environment and www.posnet.ykb.com/3DSWebService/YKBPaymentService in production environment are valid.

Wix Velo Development Environment Setup

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 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 ZIRAAT_MERCHANT_ID, ZIRAAT_TERMINAL_ID, ZIRAAT_POSNET_ID, ZIRAAT_ENCKEY.

Required modules and packages include wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data, crypto-js, and xml2js (for XML processing), which should be installed or imported.

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 ziraatPOS.jsw in Wix's backend folder. This file includes payment initiation function, XML request creation function, MAC (Message Authentication Code) calculation function, Ziraat API communication function, 3D Secure callback verification function, and order update function.

Stage Two: MAC calculation algorithm - This is the most critical component of integration. Ziraat Bank requires a MAC (Message Authentication Code) value to ensure transaction security. The MAC value creation sequence is MerchantID + TerminalID + Amount + Currency + InstallmentCount + XID + ENCKEY. These parameters are combined, encrypted with SHA-256 algorithm, and Base64 encoded.

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 dynamic pages to be created on your Wix site.

Stage Four: XML request structure - Ziraat Bank POSNET system uses XML-based communication. Standard XML templates should be prepared for payment initiation, verification, and refund operations.

Stage Five: Creating callback endpoint - HTTP functions are written to process responses from Ziraat Bank. These functions perform parsing of incoming XML data, MAC verification, evaluation of transaction results, and updating of order status.

3D Secure Payment Flow Details

3D Secure is a security protocol that provides cardholder verification in online payments. Ziraat Bank'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 creates OOS (Online Payment System) record in the background and prepares necessary parameters. Customer is automatically redirected to Ziraat Bank 3D Secure page. Transaction is verified with SMS code or mobile banking approval. After successful verification, Ziraat posts transaction result to callback URL. Backend parses incoming XML response and performs MAC verification. Order is moved to confirmed status and stock is updated. Customer is redirected to successful payment page.

3D Secure response codes and meanings are: Value 1 indicates successful verification (Authenticated) and transaction should be approved. Value 2 indicates cardholder or card not registered in system. Value 3 indicates verification could not be performed. Value 4 indicates verification attempt was made. Value 5 indicates verification failed. Value 0 indicates transaction was declined.

Installment Configuration and Campaign Management

Ziraat Bank Virtual POS offers comprehensive installment options and campaign management capabilities. Special advantages are available particularly for Bankkart and Ziraat Bank cards.

Installment parameters include the InstallmentCount parameter specifying installment count. For single payment, this value is sent as 00 or empty. For installment transactions, values 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12 are used.

Ziraat Bank card advantages include special additional installment opportunities for Bankkart holders, point earning with Bankkart Combo, special campaigns for agricultural cards, and advantageous commission rates for SME cards.

When integrating campaigns, campaigns defined from Ziraat POS panel can be queried via API. Card-specific discounts are automatically applied. BIN-based campaign control can be performed.

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 Ziraat Bank error codes and descriptions are: Code 0 indicates successful transaction, code 1 indicates transaction declined by bank, code 2 indicates suspicious transaction (call bank), code 3 indicates invalid merchant, code 4 indicates pick up card warning, code 5 indicates unapproved transaction, code 12 indicates invalid transaction, code 13 indicates invalid amount, code 14 indicates invalid card number, code 33 indicates expired card, code 36 indicates restricted card, code 41 indicates lost card, code 43 indicates stolen card, code 51 indicates insufficient funds, code 54 indicates card expiration date passed, code 57 indicates transaction not permitted to cardholder, code 58 indicates transaction not permitted to terminal, code 61 indicates daily limit exceeded, code 62 indicates restricted card, code 65 indicates daily transaction count exceeded, code 75 indicates incorrect PIN attempt count exceeded, code 91 indicates no response from bank, and code 96 indicates system malfunction.

Error logging strategy should log all API requests and responses, never log sensitive information (card number, CVV, PIN), 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 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, performing MAC 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.

Ziraat Bank additional security layers include OOS (Online Payment System) security infrastructure, transaction-based MAC verification, IP restriction capability, daily transaction limits, and suspicious transaction alert system.

Testing Process and Going Live

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

Test environment information is provided through test endpoint address setmpos.ykb.com. Test card numbers and other test information are communicated by Ziraat Bank after application approval.

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, 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 Ziraat 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 - tranType: return), partial refund (portion of transaction amount - tranType: return with specified amount), and authorization cancellation (same day, before end of day - tranType: void).

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

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

Reporting and Reconciliation

After successful integration, payment activities can be monitored from both Wix and Ziraat 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 Ziraat POS panel, daily transaction summary, installment distribution report, card type-based analysis (Bankkart, 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 Ziraat POS panel. Daily reconciliation report can be sent via email. Weekly settlement payments can be tracked.

Common Issues and Solutions

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

For MAC verification error, check parameter ordering compliance with documentation, verify encoding (UTF-8), check amount format (in kuruş), confirm ENCKEY value accuracy, and apply Base64 encoding correctly.

For XML parse error, check XML structure compliance with POSNET schema, verify special characters are escaped, check namespace declarations, and add encoding declaration.

For 3D Secure redirect issue, check callback URL accessibility, verify SSL certificate, confirm OOS record was created successfully, and check that XID value is unique.

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

Conclusion

Ziraat Bank Virtual POS integration brings Turkey's most trusted bank's payment infrastructure to your Wix e-commerce site. State bank guarantee, competitive commission rates, and access to extensive customer base provide significant advantages to businesses. When properly configured, you can offer 3D Secure 2.0 security, flexible installment options, and seamless customer experience. Due to technical complexity and security requirements, it is recommended that this integration be performed by an experienced developer.