Wix Integrations with VakıfBank 3D Secure: A Cornerstone of Secure Payments

Thanks to Wix VakıfBank 3D Secure integration, customers can make secure payments using the bank's verification screens.

Why Is 3D Secure So Critical?

In the e-commerce world, payment security is one of the most important factors directly affecting your business's success. One of your customers' biggest concerns when shopping online is the security of credit card information. At this very point, VakıfBank's 3D Secure system comes into play as the protector of both you and your customers. If you use VakıfBank Virtual POS on your Wix site, proper implementation of 3D Secure integration is the key to protection from fraudulent transactions and gaining customer trust.

VakıfBank GET 7/24 System: Foundation of Secure E-Commerce

VakıfBank introduced the 3D Secure system in 2007 under the name "GET 7/24" (Secure Electronic Commerce 7/24)¹. This system is based on security protocols developed by Visa and MasterCard and is one of the most advanced structures designed to increase the security of online shopping². Known as "Verified by Visa" for Visa credit cards and "SecureCode" for MasterCard credit cards, this system also supports TROY logo cards with BKM's "Secure Payment" protocol¹.

Three Dimensions of 3D Secure

The term "3D" in the system's name represents three basic actors in the payment process: cardholder, website (member merchant), and bank³. Verification of information flow between these three parties with special passwords and keys forms the foundation of the system. After your customer enters card information, they are redirected to VakıfBank's verification screen and verify their identity with the SMS approval code sent to their mobile phone by their bank². This prevents someone who is not the actual cardholder from making payment.

In traditional virtual POS systems, the payment transaction takes place in the e-commerce site's own system and connection is established with the bank in the background only for authorization. However, in 3D Secure system, credit card verification information occurs directly on the screen provided by the bank⁴. In other words, payment is made at the bank, and this multiplies security.

Callback URL Configuration in Wix Integration

One of the most critical steps of VakıfBank 3D Secure integration on Wix platform is callback URL (return address) configuration. After the customer completes 3D verification at the bank, the VakıfBank system redirects the customer to the URL address you specified and POSTs transaction results to this address⁵.

Defining Callback URLs

You need to create callback endpoints using HTTP functions in your Wix Velo backend. Generally, two separate URLs are defined: success URL for successful transactions and fail URL for failed transactions⁵. These URLs can be in this format:

Success URL: https://yoursite.wixsite.com/_functions/vakifbankCallback/success

Fail URL: https://yoursite.wixsite.com/_functions/vakifbankCallback/fail

You should be careful when reporting these addresses to VakıfBank because all return data from the bank will be POSTed to these URLs. Your callback URLs must be protected with HTTPS protocol and your SSL certificate must be valid¹. Additionally, it is critically important that these endpoints are continuously accessible - if your callback URL does not respond, the transaction may remain pending and customer experience will be negatively affected.

Data Processing at Callback Endpoint

The callback function you defined in your Velo backend should capture and process parameters from VakıfBank. An example callback function structure could be as follows:

import { ok, badRequest } from 'wix-http-functions';

export async function post_vakifbankCallbackSuccess(request) {
  try {
    const formData = await request.body.formData();
    const transactionData = {
      orderId: formData.OrderId,
      status: formData.Status,
      pares: formData.PARes,
      eci: formData.ECI,
      cavv: formData.CAVV,
      transId: formData.TransId
    };
    
    // Verification operations
    const isValid = await validateTransaction(transactionData);
    
    if (isValid) {
      await updateOrderStatus(transactionData.orderId, 'paid');
      return ok({ redirect: '/order-confirmation' });
    }
  } catch (error) {
    console.error('Callback error:', error);
    return badRequest({ error: error.message });
  }
}

The point to note in this function is that incoming data must be verified. Every parameter returned from VakıfBank should be checked and the authenticity of the transaction should be confirmed.

Hash Check: First Layer of Security

One of the most important elements of security in VakıfBank 3D Secure integration is hash checking. Hash basically creates a mathematical fingerprint of your data and allows you to understand whether the data has been altered in transit⁶. Hash calculation in VakıfBank system is generally done using SHA-1 or SHA-256 algorithms.

Hash Calculation Process

When a transaction is initiated, specified parameters are combined to create a string and the hash algorithm runs on this string. For example, hash value can be created by combining order number, amount, currency, and security key:

import crypto from 'crypto';

function calculateHash(orderId, amount, currency, secretKey) {
  const dataString = orderId + amount + currency + secretKey;
  const hash = crypto
    .createHash('sha1')
    .update(dataString)
    .digest('hex')
    .toUpperCase();
  return hash;
}

At the callback stage, you should compare the hash value from VakıfBank with the hash you calculated yourself. If the two values match, you can be sure that the data has not been manipulated⁶. Continuing the payment process without this check creates serious security risks.

PARes and VERes: Heart of Verification Messages

There are two critical message types in VakıfBank GET 7/24 system: VERes (Verification Response) and PARes (Payer Authentication Response)⁷. These messages are created at different stages of the 3D Secure process and are vitally important for secure completion of the transaction.

VERes Message: Card's 3D Secure Registration

When a transaction is initiated, first the VEReq (Verification Request) message is sent to the Visa/MasterCard directory server. This message queries whether the card used is registered in the 3D Secure program⁷. The directory server responds with the VERes message.

The "Status" field in the VERes message can take three different values⁷:

Y (Yes): Card is registered in 3D Secure program, transaction can continue
N (No): Card is not registered, business can continue as "half secure" if desired
U (Unable): Card status could not be determined, transaction should be terminated

When Status value is "Y," the process proceeds to PARes stage. If "N" or "U" returns, although the business is free to continue the transaction according to its own risk policy, VakıfBank does not verify such transactions, so responsibility lies with the member merchant in possible disputes⁷.

PARes Message: Identity Verification Result

When VERes Status value is "Y," the customer is redirected to the ACS (Access Control Server) server of the bank that issued the card⁷. ACS asks the customer to enter the one-time password sent via SMS. When the customer enters this password, the ACS server creates the PARes message and returns to the member merchant.

The "Status" field in the PARes message is also critically important⁸:

Y (Yes): Identity verification successful, authorization transaction can proceed
A (Attempted): Verification attempted but not fully successful, risky
N (No): Verification failed, transaction should be terminated
U (Unable): Verification could not be performed, transaction should be terminated
E (Error): Error occurred, transaction should be terminated

VakıfBank's recommendation is clear: if PARes Status value is anything other than "Y" or "A," the transaction should not be sent to authorization stage⁸. Because in this case, the 3D Secure process has not been successfully completed and responsibility will belong to the business in customer disputes.

ECI and CAVV: Critical Parameters of Authorization Message

After successfully completing the 3D Secure process, you must include two important parameters when sending your authorization message to VakıfBank: ECI (Electronic Commerce Indicator) and CAVV (Cardholder Authentication Verification Value)⁸.

ECI (Electronic Commerce Indicator)

ECI is a code indicating the security level of the transaction. Different ECI values are used for different card schemes. For example, for Visa cards, ECI value is "05" in full 3D Secure transactions, while for MasterCard it is "02"⁸. This value affects how the bank evaluates the transaction.

When processing the PARes message in your Wix backend, you should extract the correct ECI value and include it in your authorization request:

function determineECI(pares, cardType) {
  const paresStatus = pares.Status;
  
  if (cardType === 'VISA') {
    if (paresStatus === 'Y') return '05';
    if (paresStatus === 'A') return '06';
  } else if (cardType === 'MASTERCARD') {
    if (paresStatus === 'Y') return '02';
    if (paresStatus === 'A') return '01';
  }
  
  return null; // Transaction should be rejected
}

CAVV (Cardholder Authentication Verification Value)

CAVV is an encrypted value containing the cardholder identity verification result. If communicated by GET 7/24 MPI in the PARes message, you should add this value to your authorization message⁸. CAVV enables the bank to verify that the transaction actually went through the 3D Secure process.

An important note: If PARes Status value is not "Y" or "A," CAVV value may not exist or may be invalid. In this case, you should not send authorization message⁸.

Transaction Number Matching: Tracking and Reconciliation

In VakıfBank 3D Secure process, each transaction is identified with a unique transaction number (TransactionID)⁹. This number is used in all stages from the beginning to the end of the transaction and enables tracking of the transaction between different systems.

TransactionID Life Cycle

When you initiate a transaction, you generate a TransactionID in your Wix backend. This ID generally consists of a combination of timestamp and a random string:

function generateTransactionID() {
  const timestamp = Date.now();
  const random = Math.random().toString(36).substr(2, 9);
  return `VAKIF_${timestamp}_${random}`;
}

This TransactionID is included in the first request message you send to VakıfBank. This ID is preserved throughout the 3D Secure process and returns to you at the callback stage. You determine which order it belongs to by matching the TransactionID you received in callback with the ID you stored in your own database⁹.

Reconciliation and Troubleshooting

Transaction number matching is critical not only for order tracking but also for reconciliation and troubleshooting. When a customer says "I made payment but order was not created," you can check from VakıfBank panel by querying transaction number whether payment actually came¹⁰. If payment came but order was not created in Wix, you understand there was a problem in the callback process.

Similarly, you should ensure that the same TransactionID is not used multiple times in case of repeated payment attempts. Otherwise, VakıfBank system may reject the transaction or confusion may occur⁹.

Authorization Response Verification: Final Check

After all verifications are successful at the callback stage, you should also check the authorization response from VakıfBank. The authorization response indicates whether the transaction has been approved by the bank.

Meaning of Response Codes

VakıfBank sends a response code in the authorization response. Code "00" represents successful transaction; all other codes indicate various rejection reasons⁹. For example:

00: Successful
01: Could not connect with issuing bank
05: Unauthorized transaction
12: Invalid transaction
51: Insufficient balance
54: Card expiration date has passed

You should evaluate these codes in your Wix backend and show the appropriate message to the customer:

function interpretResponseCode(code) {
  const messages = {
    '00': 'Your payment has been completed successfully.',
    '51': 'Insufficient balance. Please try another card.',
    '54': 'Your card expiration date has passed.',
    '05': 'Transaction rejected. Please contact your bank.'
  };
  
  return messages[code] || 'Transaction failed. Please try again.';
}

Feedback in Error Situations

If the authorization response is unsuccessful, you should show the customer a clear and helpful message. Instead of a general message like "Transaction failed," specify the specific problem if possible (insufficient balance, card expired, etc.). This improves customer experience and reduces support calls.

Also, log failed transactions and review them periodically. If you're constantly receiving the same error code, there may be a problem with your integration¹⁰.

Reducing Fraudulent Transaction Risks

Proper implementation of VakıfBank 3D Secure integration significantly reduces fraudulent transaction (fraud) risks. There are several reasons for this.

Cardholder Verification

The first and most important reason is verification by the customer's bank². In traditional virtual POS, only card number, expiration date, and CVV code are sufficient. However, in 3D Secure, in addition to these, the one-time password sent to the customer's mobile phone is also required. This makes it almost impossible for someone who stole the card or copied its information to make payment².

Chargeback Protection

In transactions made with 3D Secure, when a customer disputes by saying "I did not make this transaction," the bank sees that the transaction went through 3D verification process and rejects the dispute¹¹. Because only the customer can know the password sent to their mobile phone. This way, chargeback risk arising from "I didn't do it" disputes transfers to the bank and the business is protected¹¹.

In merchants not using 3D Secure, the situation is different. When the customer disputes, the business needs to provide proof that the transaction was made by them. Since there is usually no such proof, the bank refunds the amount to the customer and takes it back from the business¹¹.

Fraud Detection Systems

VakıfBank GET 7/24 system runs advanced fraud detection algorithms in the background. It evaluates many data such as device information, transaction amount, user behavior, and past payment habits to determine whether the transaction is suspicious. It applies additional checks or directly rejects suspicious transactions¹².

Customer Experience and Transaction Completion Rates

Proper implementation of 3D Secure integration is critical not only for security but also for customer experience. When customers see the bank's own screen, they feel more secure and are more comfortable completing the purchase³.

Trust Factor

Research shows that in a study conducted by Visa Europe in Germany, Spain, and the UK, security provided by Verified by Visa encourages 47% of people who do not shop on the internet to shop and 56% of people who do not shop frequently to shop more¹³. These figures show that security directly affects customer behavior.

When your customers see VakıfBank's logo and familiar verification screen during payment stage, they think your site is reliable. Especially in Turkey, seeing the name of an established bank like VakıfBank increases customer trust.

Things to Watch for Seamless Experience

Since 3D Secure process is an extra step for the customer, it's important that this step passes as quickly and smoothly as possible. Some tips:

Don't Use Pop-ups: As clearly stated in VakıfBank integration guide, use of pop-up windows in 3D Secure flow is definitely not recommended⁷. Because browsers' pop-up blocking tools can close this window and the customer cannot complete the transaction. Instead, redirect in the same tab or in a new tab.

Mobile Compatibility: The vast majority of your customers shop from mobile devices. Make sure VakıfBank's verification screen displays properly on mobile and SMS code can be easily entered.

Error Messages: If the customer enters SMS code incorrectly or timeout occurs, show clear and helpful error messages. Offer a "try again" button and don't require the customer to re-enter card information.

Loading Indicators: Show the customer a loading indicator while processing transaction results at callback stage. Otherwise, the customer may think the page is frozen and close the browser.

Conclusion: Secure and Reliable E-Commerce

Proper implementation of VakıfBank 3D Secure integration on Wix is an indispensable element of modern e-commerce. This integration includes many technical steps from callback URL configuration to hash checking, from verifying PARes messages to processing authorization responses. Each step must be carefully implemented because even the smallest error can cause the payment process to fail.

The value you gain when you complete integration is very clear: fraudulent transaction risks are reduced to minimal level, you are protected from chargeback losses, customer trust increases, and your transaction completion rates rise. Thanks to VakıfBank's reliable infrastructure and advanced features of GET 7/24 system, your business can offer a secure and professional payment experience.

Remember, 3D Secure is not just a security measure but also a trust message you give to your customers. When you tell them "your payment information is safe," you're supporting this with VakıfBank's verification. And this trust returns to you in the long term as customer loyalty and repeat sales.