Installing Yapı Kredi POS on Wix

For businesses operating e-commerce sites on the Wix platform, Yapı Kredi Virtual POS integration offers the opportunity to use the reliable payment infrastructure of one of Turkey's established banks. Standing out with its World card ecosystem, strong technological infrastructure, and wide customer base, Yapı Kredi provides a valuable payment solution for e-commerce businesses.

What is Yapı Kredi Virtual POS?

Yapı Kredi Virtual POS is an enterprise-level online payment solution developed for e-commerce sites. The technological infrastructure of Yapı Kredi, one of Turkey's largest private banks, offers a reliable and fast payment experience.

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 Yapı Kredi.

Key features of Yapı Kredi Virtual POS include transaction security reinforced with 3D Secure 2.0, World card program advantages and point system, support for Visa, Mastercard, Troy, and American Express cards, flexible installment options ranging from 2 to 12 months, advanced fraud protection systems, fast provision, low transaction time, and 24/7 technical support service.

When the advantages of Yapı Kredi POS are evaluated, access to the World card customer base offers a great opportunity. Customer loyalty can be increased with Worldpuan integration. Competitive commission rates provide a cost advantage. Its modern and developer-friendly API structure facilitates integration. There are special advantages for SME Credit Card holders.

Yapı Kredi Virtual POS Application Process

Before integration, a virtual POS application must be made to Yapı Kredi 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 content information, and Yapı Kredi account details (advantage for existing customers).

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 Yapı Kredi relationship.

Application channels include Yapı Kredi branches, the online application portal, commercial banking representatives, and the Yapı Kredi business banking line.

Information to be received after application approval includes Merchant ID, Terminal ID, POSNET ID, Store Key (3D Secure Key), API user information, and endpoint URLs.

API Information Required for Integration

After virtual POS approval is received from Yapı Kredi, 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 MerchantId, TerminalId, PosnetId, EncKey (3D Secure encryption key), and API user information.

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 setmpos.ykb.com/PosnetWebService/XML for the test environment and posnet.yapikredi.com.tr/PosnetWebService/XML for the production environment. For 3D Secure redirection, setmpos.ykb.com/3DSWebService/YKBPaymentService for test and posnet.yapikredi.com.tr/3DSWebService/YKBPaymentService 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, YKB_MERCHANT_ID, YKB_TERMINAL_ID, YKB_POSNET_ID, YKB_ENCKEY.

Necessary modules and packages such as wix-secrets-backend, wix-fetch, wix-stores-backend, wix-data, crypto-js, and xml2js (for XML processing) 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 yapikrediPOS.jsw in Wix's backend folder. This file contains the payment initiation function, XML request creation function, MAC (Message Authentication Code) calculation function, Yapı Kredi API communication function, 3D Secure callback verification function, and order update function.

Second stage: MAC calculation algorithm is the most critical component of the integration. The Yapı Kredi POSNET system requires a MAC value to ensure transaction security. The MAC value creation order is MerchantId + TerminalId + Amount + Currency + InstallmentCount + XID + EncKey. These parameters are combined and encrypted with the SHA-256 algorithm.

Third stage: 3D Secure redirection configuration involves defining two callback URLs. The Success URL (MerchantReturnURL) 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: XML request structure. The Yapı Kredi POSNET system uses XML-based communication. Standard XML templates should be prepared for payment initiation (OOS - Online Payment System), verification, and refund transactions.

Fifth stage: Creating callback endpoint involves writing HTTP functions that will process responses coming from Yapı Kredi. These functions perform parsing of incoming XML data, MAC verification, evaluation of the transaction result, and updating of the order status.

3D Secure Payment Flow Details

3D Secure is a security protocol that provides cardholder verification in online payments. Yapı Kredi's 3D Secure 2.0 infrastructure offers advanced security features and World card integration.

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 creates an OOS (Online Payment System) record in the background. Necessary MAC values are calculated, and an XML request is prepared. The customer is automatically redirected to the Yapı Kredi 3D Secure page. The transaction is verified via SMS code or Yapı Kredi Mobile approval. After successful verification, the bank POSTs the transaction result to the callback URL. The backend parses the incoming XML response and performs MAC verification. The provision process is completed, and the order status is changed to approved. The customer is redirected to the successful payment page.

POSNET response codes and meanings are as follows: Value 1 indicates a successful transaction (Approved). Value 0 indicates a failed transaction. ApprovedCode contains the provision code in successful transactions. HostLogKey is the transaction reference number and is used in refund transactions.

Installment Configuration and World Advantages

Yapı Kredi Virtual POS offers comprehensive installment options and World card program advantages. Campaigns specific to World cardholders increase conversion rates.

As installment parameters, the InstallmentCount parameter specifies the number of installments. For single payments, this value is sent as 00. For installment transactions, values 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12 are used.

Within the scope of World card advantages, additional installment opportunities are offered to World cardholders. Worldpuan earning and spending opportunities are provided. There are special campaigns for World Elite and World Business. There is an alternative payment option with Chip-para integration.

For BIN-based campaign inquiry, using the first 6 digits (BIN) of the card number, campaigns applicable to that card can be queried. This query ensures special offers are shown to the customer.

While performing campaign integration, campaigns defined from the Yapı Kredi POS panel can be queried via API. Card-specific discounts and additional installments are applied automatically. The payment option with Worldpuan can be activated.

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 Yapı Kredi POSNET error codes and descriptions are: Code 0 indicates a failed transaction, 1 indicates a successful transaction, 00 indicates an approved transaction (with provision code), 01 indicates call the issuing bank, 02 indicates call the issuing bank, 03 indicates invalid merchant, 04 indicates capture card, 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 fraud suspicion, 36 indicates a restricted card, 41 indicates a lost card, 43 indicates a stolen card, 51 indicates insufficient funds, 54 indicates the card has expired, 57 indicates a transaction not permitted to cardholder, 58 indicates a transaction not permitted to terminal, 61 indicates daily limit exceeded, 65 indicates daily transaction count exceeded, and 91 indicates no response from the bank.

As an error logging strategy, all API requests and responses should be logged, sensitive information (card number, CVV) 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.

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 MAC 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.

Yapı Kredi additional security features include OOS (Online Payment System) security infrastructure, transaction-based MAC verification, advanced fraud detection system, velocity check mechanism, and suspicious transaction warning system.

Testing Process and Going Live

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

Test environment information is provided via the test endpoint address setmpos.ykb.com. Test card information is transmitted by Yapı Kredi after application approval.

As a test scenario checklist, successful single payment, successful 3-installment payment, successful 6-installment payment, successful 12-installment payment, payment with World card, payment with Worldpuan (if active), insufficient funds 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 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 Yapı Kredi 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 - tranType: return), partial refund (part of the transaction amount - tranType: return by specifying the amount), and provision cancellation (within the same day, before end-of-day - tranType: void).

For automatic refund integration, Yapı Kredi's refund API is used. The call is made with the original transaction reference number (HostLogKey). The refund amount and currency are specified. Refund transactions are generally reflected in the cardholder's account within 1-3 business days.

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

Reporting and Reconciliation

After successful integration, payment movements can be monitored from both the Wix and Yapı Kredi 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 Yapı Kredi POS panel, daily transaction summaries, installment distribution reports, card type-based analysis (World, Visa, Mastercard), Worldpuan transaction reports, 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 Yapı Kredi 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 MAC verification error, compliance of parameter order with POSNET documentation should be checked, encoding (UTF-8) verified, amount format checked (in YTL, without dots or commas), accuracy of EncKey value confirmed, and hash algorithm verified to be SHA-256.

For XML parse error, compliance of XML structure with POSNET schema should be checked, special characters verified to be escaped, namespace definitions checked, and encoding declaration added.

For OOS record error, accuracy of MerchantId and TerminalId should be checked, whether the PosnetId value is active confirmed, whitelist check performed if there is IP restriction, and compliance of transaction amount with limits verified.

For 3D Secure redirection problem, accessibility of callback URLs should be checked, SSL certificate verified, and XID value checked to be unique.

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

Yapı Kredi Virtual POS integration provides your Wix e-commerce site with the reliable payment infrastructure of one of Turkey's established banks. The World card ecosystem, Worldpuan integration, competitive commission rates, and strong technological infrastructure provide significant advantages to businesses. When configured correctly, you can offer 3D Secure 2.0 safety, flexible installment options, 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.