Wix Finansbank 3D Secure Settings

Configuring QNB Finansbank 3D Secure settings on Wix is a critical step in maximizing payment security. These settings create a verification flow where bank return URLs, hash verification values, merchant information, and transaction result codes are checked. A properly configured 3D Secure system minimizes the risk of fraudulent transactions and makes users feel secure.

What is 3D Secure 2.0 and why is it important?

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

The security advantages offered by 3D Secure include cardholder authentication, confirming that the transaction is being made by the actual cardholder. Fraud protection prevents unauthorized transactions. Chargeback reduction lowers the rate of disputed transactions. Legal compliance ensures adherence to PSD2 and local regulations. Customer trust is enhanced, offering a secure payment experience with familiar bank screens.

When comparing 3D Secure 2.0 and 1.0, version 1.0 only used SMS codes for authentication methods, while version 2.0 includes SMS, biometric, and app verification options. In terms of user experience, 1.0 required redirection for every transaction, while 2.0 implements risk-based intelligent redirection. Regarding mobile compatibility, 1.0 offered limited support, while 2.0 provides full mobile optimization. In terms of data sharing, 1.0 involved minimal data transmission, while 2.0 includes rich risk assessment data.

Basic 3D Secure Parameters

The basic parameters required for QNB Finansbank 3D Secure integration are provided by the bank and must be configured correctly.

The required parameters are 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).

Transaction parameters include OrderId (Unique Order Number), PurchAmount (Transaction Amount - Including Cents), Currency (Currency Code - for 949 TL), InstallmentCount (Number of Installments), OkUrl (Successful Transaction Return URL), and FailUrl (Failed Transaction Return URL).

Hash (Verification hash value), Rnd (Random value - unique in each transaction), and TxnType (Transaction type - Auth, PreAuth, PostAuth) are used as security parameters .

Callback URL Configuration

The most critical configuration in the 3D Secure process is the correct definition of the bank return URLs. These URLs enable the processing of the payment result.

URL requirements include mandatory HTTPS, and all URLs must be SSL certified. Public accessibility must be ensured, and URLs must be accessible from bank servers. A static structure is preferred; dynamic parameters should be in the POST body, not the URL.

Suggested URL formats arehttps://www.yourwebsite.com/_functions/finansbank-success for OkUrl and https://www.yourwebsite.com/_functions/finansbank-fail for FailUrl.

The Wix HTTP Functions configuration involves creating the http-functions.js file in the backend folder. Endpoints that accept the POST method are defined. Functions to process the incoming data are written. User redirection logic is created.

Hash Calculation and Verification

Hash values are a cornerstone of transaction security. They guarantee the accuracy of both sent and received data.

The parameter order for generating a hash is MbrId + OrderId + PurchAmount + OkUrl + FailUrl + TxnType + InstallmentCount + Rnd + SecureKey. These parameters are combined to encrypt using the SHA-512 algorithm and encoded in Base64.

The hash calculation rules state that parameters must be combined in the specified order. Spaces or separators should not be used. The amount must be written including cents, without periods or commas. Encoding must be UTF-8.

The hash verification process involves retrieving the hash value from the bank's response. A new hash is calculated using the same parameters. The two hash values are compared. If there is no match, the transaction is rejected.

3D Secure Payment Process Details

When a customer initiates a payment, the system processes the transaction within a defined workflow.

The workflow steps are as follows: The customer enters their card information and an order is created. The backend calculates the hash value and prepares the form data. The customer is automatically redirected to the QNB Finansbank 3D Secure page. The customer confirms the transaction with an SMS code, QNB Mobile confirmation, or biometric verification. The bank POSTs the transaction result to OkUrl or FailUrl. The backend receives the data and performs hash verification. The order status is updated according to the transaction result. The customer is redirected to the success or failure page.

In 3D Secure response parameters , ProcReturnCode is the transaction result code, with 00 indicating a successful transaction. Response is the transaction status and takes the values Approved or Declined. AuthCode is the provisioning code for successful transactions. TransId is the transaction reference number. ErrMsg is a description message in case of an error. mdStatus indicates the 3D Secure authentication status.

mdStatus Values and Meanings

mdStatus indicates the outcome of the 3D Secure verification process. This value determines how the transaction will be evaluated.

mdStatus values are as follows: A value of 1 indicates full authentication; the cardholder and the issuing bank have participated in the verification, and the transaction is secure. A value of 2 means only the cardholder is not registered in the system; the issuing bank supports 3D Secure, but the cardholder is not registered. A value of 3 means the issuing bank is not registered in the system and does not support 3D Secure. A value of 4 means an authentication attempt was made; the cardholder was prompted to enter their PIN. A value of 5 means authentication failed; the authentication did not occur due to technical problems. A value of 0 indicates authentication failed; the cardholder did not pass the authentication, and the transaction should be rejected.

As a transaction decision logic , a transaction can be approved if mdStatus values are 1, 2, 3, or 4. A transaction should be rejected if mdStatus is 0 or 5. Additionally, a ProcReturnCode check should be performed.

Security Settings and Controls

Additional controls and settings must be configured to enhance 3D Secure security.

For hash security, SecureKey should never be present in the frontend code. Wix Secrets Manager should be used. Hash calculation should only be performed in the backend. A unique Rnd value should be generated for each operation.

As part of IP control, requests from QNB Finansbank IP addresses should be accepted. Requests from suspicious IPs should be logged and rejected. The IP whitelist should be kept up-to-date.

For timeout settings , a 3D Secure redirection timeout period should be defined (recommended 15-20 minutes), a callback waiting period should be defined, and session timeout management should be configured.

For SSL/TLS requirements, TLS 1.2 or higher is mandatory. A valid SSL certificate must be present. Mixed content must be blocked.

Error Codes and Management

It's important to know the error codes and solutions that may be encountered during the 3D Secure process.

Common 3D Secure error codes are as follows: Code 99 indicates a general error and the system logs should be checked. Code 98 indicates a hash mismatch and the parameter order and values should be checked. Code 97 indicates a timeout and the transaction time has been exceeded; a retry should be made. Code 96 indicates a system error and the bank should be contacted. Code 95 means an invalid transaction and the parameters should be checked. Code 94 indicates a duplicate transaction and the same OrderId has been used.

User-friendly messages should be displayed as part of the error management strategy . Technical details should be logged. A notification system should be established for critical errors. A retry mechanism should be implemented (for timeout errors).

Test Environment Configuration

Testing 3D Secure settings is mandatory before going live.

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 following test scenarios should be performed: successful 3D Secure authentication (mdStatus: 1), cardholder not registered scenario (mdStatus: 2), bank not registered scenario (mdStatus: 3), authentication attempt scenario (mdStatus: 4), failed authentication scenario (mdStatus: 0), timeout scenario, hash error scenario, and callback URL accessibility test.

The test checklist should include testing all mdStatus values, verifying hash calculations, ensuring callback URLs are working, checking error messages, verifying order status updates, and testing user redirects.

Wix Panel Integration

Integration settings must be configured for 3D Secure results to be displayed correctly in the Wix admin panel.

In order status matching , mdStatus 1 + ProcReturnCode 00 status is marked as "Payment Confirmed", mdStatus 0 or ProcReturnCode error status is marked as "Payment Failed", and timeout status is marked as "Payment Timeout".

The order notes section includes the 3D Secure verification status, authorization code (AuthCode), transaction reference number (TransId), mdStatus value, and any error messages.

Notification settings include a confirmation email for successful 3D Secure transactions, a notification for unsuccessful transactions, and an alert to the administrator for suspicious transactions.

Performance and Optimization

The performance of the 3D Secure process directly impacts user experience.

Hash calculation should be optimized for speed optimization . API calls should be asynchronous. Unnecessary data transfer should be minimized. CDN usage should be evaluated.

Loading indicators should be added to improve user experience . Information about waiting times should be provided. Clear guidance should be given in case of errors. Mobile compatibility must be guaranteed.

Monitoring and logging should include tracking 3D Secure transaction times, success and failure rates, and the mdStatus distribution. Error patterns should be identified.

Troubleshooting

Common problems and their solutions encountered in 3D Secure integration should be known.

For hash validation errors, the parameter order should be checked to ensure it conforms to the documentation. The amount format should be confirmed to be correct (including cents, no separator). Encoding should be verified as UTF-8. The SecureKey value should be checked to ensure it is up-to-date.

To address redirection issues , check that callback URLs are HTTPS. Verify that URLs are publicly accessible. Check firewall rules. Confirm SSL certificate validity.

To address the timeout issue , the transaction start time should be checked. Session management should be reviewed. Network latency should be analyzed. The status of the bank's system should be investigated.

Properly configuring QNB Finansbank 3D Secure settings on Wix forms the foundation of a secure payment experience. Correctly setting up critical components such as hash calculation, callback URL configuration, mdStatus evaluation, and error handling minimizes the risk of fraudulent transactions and ensures user security. With a properly configured 3D Secure system, a Wix store offers a secure and stable payment flow fully compatible with QNB Finansbank POS.

For Wix Finansbank 3D Secure settings and e-commerce solutions, contact Blakfy: blakfy.com/iletisim