Wix İş Bankası Virtual POS Technical Integration: A Comprehensive Guide from Backend to Administration

Thanks to Wix İş Bankası payment integration, installment, 3D Secure and refund transactions can be managed seamlessly.

Quick Start: Who Is This Article For?

Prepared for e-commerce site owners, developers, and those curious about technical details. We will explain step by step how İş Bankası Virtual POS is integrated with Wix, the backend structure, and payment processes.

Important: This article is a continuation of the previous "Wix İş Bankası Virtual POS Integration" article and focuses on more technical details.

Integration Architecture: How Does It Work?

1. Wix Velo Backend Infrastructure

What is Velo? Wix's JavaScript-based development platform. It allows you to write custom code, work with APIs, and perform backend operations¹.

Key Features:

Ability to write frontend and backend code²
HTTP functions
Secure storage of API keys
REST API support¹

Dev Mode Activation:

Open Wix Editor
Select "Dev Mode" from the top menu
Click "Turn on Dev Mode"
Code Panel opens²

2. Payment Flow: Three Critical Endpoints

Three basic endpoints are used in Wix İş Bankası integration³:

A. Payment Initiation Endpoint

Task: Initiates the payment process

Process:

Customer clicks "Pay" button
↓
Frontend event handler calls backend function
↓
PaymentInfo object is created in backend
↓
createPayment() function runs
↓
Payment object returns to frontend⁴

Operations Performed:

Collects order information
Calculates payment amount
Prepares parameters to be sent to İş Bankası
Creates unique transaction ID⁵

B. 3D Secure Verification Endpoint

Task: Integration with bank verification screen

Operation Scheme:

After createPayment()
↓
startPayment() function is called
↓
Customer is redirected to bank
↓
3D Secure password is entered
↓
Bank returns verification result⁴

Critical Parameters⁶:

ECI (Electronic Commerce Indicator)
CAVV (Cardholder Authentication Verification Value)
mdStatus (3D verification status)
PARes (Payment Authentication Response)

mdStatus Values:

1 = Successful verification → Payment continues
0,2,3,4 = Failed → Transaction terminated⁶

C. Callback (Feedback) Endpoint

Task: Processes results from the Bank

Callback URL Structure:

https://<account-name>.wixsite.com/
<site-name>/_functions/paymentCallback

Webhook System⁷: Wix uses HTTP endpoint to receive payment status updates.

Incoming Data:

Transaction status (successful/failed)
Transaction ID
Error codes (if any)
Authorization number
Payment amount and currency⁷

Callback Processing Steps³:

Verify webhook (digest header check)
Parse incoming data
Transfer to Wix order system
Send notification to customer
Return HTTP 200⁷

3. Payment Provider Integration with Velo

Payment Provider Service Plugin⁸: A custom plugin system to integrate payment providers not supported in Wix.

Setup Stages⁸:

Open Dev Mode
Go to Service Plugins section
Add "Payment" option
Enter name (no spaces or special characters)
Code files are automatically created

Created Files:

payment-provider.config.json (configuration)
payment-provider.js (main code)

Parameter Processing: İş Bankası Specific Details

Hash Data Creation

İş Bankası uses a two-part HASH structure for security⁹:

Step 1: Hashed Password

SHA1(authorization_password + terminal_number)
= hashedPassword

Step 2: Transaction Hash

SHA1(transaction_info + hashedPassword)
= HashData

This HashData is sent within <HashData> tag in each request⁹.

Transaction ID Management

Critical Rule: Each transaction must contain a unique TransactionID⁵.

Usage Areas:

Transaction inquiry
Cancellation transactions
Refund transactions
Pre-authorization closing⁵

İş Bankası Parameters

Mandatory Fields:

Store Number
Terminal Number
API User
API Password
3D Security Key
Transaction Amount (in kuruş)
Currency (ISO 4217 code)
Number of Installments¹⁰

Example:

12.34 TL → sent as 1234¹⁰
Cash transaction → 00
2 installments → 02¹⁰

Post-Payment Operations: Cancel, Refund, Authorization

1. Cancel (Void) Transaction

When to Use: Before end-of-day reconciliation occurs¹¹.

Features:

Must be done within the same day
Does not appear on card statement
Does not reflect on customer account¹¹

API Parameters:

Transaction Type: VOID
TransactionID: Original transaction number
Amount: Amount to be cancelled

Caution: Cancellation cannot be cancelled! If accidentally cancelled, transaction must be redone¹¹.

2. Refund Transaction

When to Use: After end-of-day reconciliation has passed¹¹.

Process:

Transaction reflects on customer card within 2-7 business days¹²
Visible on card statement
Full or partial refund can be made¹³

API Call:

Transaction Type: REFUND
TransactionID: Original transaction number
Amount: Amount to be refunded (optional)
Currency: TRY, EUR, USD, etc.

Important: Amount to be refunded must include VAT¹³.

3. Pre-Authorization Operations

Pre-Authorization (Pre-Auth)

Usage Areas:

Hotel reservations
Car rental
High-amount transactions¹⁴

Operation:

Auth Transaction → Block placed on card
↓ (within 3-75 days)
Capture → Amount is withdrawn
or
Cancel → Block is removed¹⁴

Post-Authorization (Pre-Authorization Closing)

API Operation:

Transaction Type: POSTAUTH/CAPTURE
HostLogKey: Pre-authorization ID
Amount: Amount to be withdrawn

Special Case: Capture amount cannot exceed pre-authorization¹⁴.

4. Reversal (Technical Cancellation)

When Needed: When response cannot be received from POS⁶.

Purpose: To reverse a pending transaction.

Usage: Only for technical cancellation of financial transactions⁶.

Wix Order System Integration

Order Management API

Wix's eCommerce API provides order management¹⁵.

Capabilities:

Cart management
Checkout process
Order tracking
Payment status update¹⁵

Payment-Order Synchronization³:

Callback arrives
↓
Payment status is parsed
↓
Order Status API is called
↓
Order status is updated
(Pending → Paid / Failed)

Status Code Mapping

Bank → Wix Mapping:

İş Bankası Code	Wix Order Status	Description
00	Paid	Successful
01-99	Failed	Declined³
3030	Canceled	Customer abandoned³
Pending	Pending	Awaiting verification³

Reason Codes³

Wix uses reason codes to indicate payment statuses.

Examples:

5001 → General decline
5002 → Insufficient balance
5003 → Invalid card
3030 → Cancelled by customer³

Dual Panel Management: Business Advantages

1. Management from Wix Panel

Accessible Features:

Order list and details
Payment statuses
Refund requests
Customer information
Sales reports¹⁵

Dashboard Widgets:

Daily/monthly sales charts
Best-selling products
Failed payment rates

2. İş Bankası Virtual POS Panel

https://spos.isbank.com.tr/isbank/report/user.login

Available Operations:

View authorization transactions
Manually initiate cancel/refund
End-of-day reports
API user management
3D settings control¹⁶

Special Reports:

Transaction-based details
Commission calculations
Installment distribution
Success/failure rates

3. Dual Panel Advantages

Security:

Two separate log systems
Cross-check capability
Easy fraud detection

Transparency:

Each transaction visible on both sides
Inconsistencies noticed immediately
Reconciliation becomes easier

Flexibility:

Automatic from Wix
Manual from İş Bankası
Can choose based on need

Security Measures

1. Secrets Manager²

Storing Sensitive Data:

import { getSecret } from 'wix-secrets-backend';

export async function getAPIKey() {
  const key = await getSecret("isbankAPIKey");
  return key;
}

Why Important: API keys are not visible in browser².

2. HTTPS and SSL

Requirement:

All requests over HTTPS
Minimum 128-bit SSL⁵
Certificate validity check

3. Digest Header Validation³

Webhook Security:

const digestHeader = request.headers['Digest'];
const isValid = validateJWT(digestHeader);

if (!isValid) {
  return { status: 401 };
}

This verifies that webhooks actually come from Wix/İş Bankası³.

4. PCI-DSS Compliance

İş Bankası Guarantee: All transactions pass through PCI-DSS Level 1 certified systems¹⁷.

This Means:

Card data is encrypted
Secure data storage
Regular security testing
Fraud detection algorithms¹⁷

Testing and Going Live

Test Environment Setup

İş Bankası Test Endpoints:

Test API: https://sanalpostest.isbank.com.tr/fim/api
Test 3D Gateway: https://sanalpostest.isbank.com.tr/fim/est3Dgate
Test Cards: Provided by bank (e.g., 5440231234567890)

Integration Test Checklist

✅ Basic Operations:

[ ] Cash sale (successful)
[ ] Cash sale (failed - insufficient balance)
[ ] Installment sale
[ ] 3D Secure verification
[ ] 3D Secure abandonment

✅ Cancel/Refund:

[ ] Same day cancellation
[ ] Next day refund
[ ] Partial refund
[ ] Installment transaction refund

✅ Pre-Authorization:

[ ] Auth transaction
[ ] Capture transaction
[ ] Cancel transaction

✅ Error Scenarios:

[ ] Timeout handling
[ ] Network interruption
[ ] Invalid response
[ ] Webhook retry

Going Live Procedure

1. Endpoint Change:

const PRODUCTION_API = 
  "https://spos.isbank.com.tr/fim/api";
const PRODUCTION_3D = 
  "https://spos.isbank.com.tr/fim/est3Dgate";

2. Credential Update:

Remove test API keys
Add production keys to Secrets Manager
Verify 3D_PAY model¹⁶

3. Final Checks:

Is SSL certificate active?
Is callback URL correct?
Is error catching working?
Is log system active?

Performance Optimization

1. Caching Strategies

Transaction State Cache:

// Cache frequently queried transactions
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

What to Cache:

Installment rates (update once per day)
Card BIN information
Bank last status queries

2. Asynchronous Operations

Webhook Processing:

export async function paymentCallback(request) {
  // Quick verification
  const isValid = validateDigest(request);
  
  // Return HTTP 200 immediately
  wixData.insert("pendingWebhooks", request.body);
  
  return { status: 200 };
}

// Process in background
async function processWebhook() {
  const pending = await wixData.query(
    "pendingWebhooks"
  ).find();
  
  for (const webhook of pending.items) {
    await updateOrder(webhook);
    await wixData.remove("pendingWebhooks", 
      webhook._id);
  }
}

3. Rate Limiting

API Call Limits:

İş Bankası: 100 requests/minute
Wix webhook: Retry logic (1s, 5s, 30s)⁷

Recommendations:

Add delay in batch operations
Use exponential backoff
Apply circuit breaker pattern

Common Technical Issues

Problem: Webhook Not Received

Solutions:

Check firewall rules
Is HTTPS certificate valid?
Is callback URL written correctly?
Are there requests in logs?

Test:

curl -X POST https://site-name.wixsite.com/
_functions/callback -H "Content-Type: 
application/json" -d '{"test": true}'

Problem: 3D_PAY Error

Reason: Wrong 3D model type¹⁶

Solution: In İş Bankası panel:

Management → 3D Settings → 
Model: Should be "3D_PAY"

Problem: Transaction ID Collision

Reason: Multiple requests with same ID

Solution:

function generateUniqueTransactionID() {
  return `WIX_${Date.now()}_${
    Math.random().toString(36).substr(2, 9)
  }`;
}

Problem: Timeout

İş Bankası Timeout: 30 seconds

Solutions:

Prepare data before request
Establish reversal mechanism⁶
Determine retry policy

Future: Wix SDK Transition

Important Information: Wix is transitioning from Velo APIs to Wix JavaScript SDK¹⁵.

What Will Change:

More modern API structure
Application development with Blocks
Better documentation

Transition Process:

Velo APIs will continue to work
Gradual transition recommended
New projects should use SDK¹⁵

Conclusion and Recommendations

For Technical Success:

✓ Set up endpoint structure correctly
✓ Process callbacks securely
✓ Make error management robust
✓ Approach test coverage to 100%
✓ Keep monitoring and logging active

For Business Success:

✓ Regularly check both panels
✓ Prioritize customer experience
✓ Monitor payment success rate
✓ Optimize refund processes
✓ Follow security updates

Final Advice: Have the integration done by a professional team or work with an experienced Wix Partner. Payment systems are critical infrastructures and even the smallest error can cause major losses.