# Turkish Bank Virtual POS Modules

https://docs.wisecp.com/fr/turkish-bank-virtual-pos-modules

Configure Turkish bank virtual POS modules and check their account, installment, test and refund requirements.

## Reaching the Screen

Open **Settings → Financial → Payment Gateways → All Modules** and select your bank. `{admin}/modules/payment?module=Garanti`

## What Is on the Screen

Each bank has its own form. Akbank and AkbankPayten use different credentials. Card storage, automatic payments and subscriptions are unavailable.

## Before You Configure It

Obtain a virtual POS agreement, merchant approval, API user and 3D access from your bank. Request distinct test credentials and confirm the module’s protocol and endpoints. Saved values are not usable test credentials.

## Fields

Bank-specific labels remain Turkish in both panel languages. Unless marked optional, enter your bank-issued values; there are no ready-to-use account credentials.

### Garanti

- **Sanal Pos Tipi (3D Security Level)**: Choose the bank-approved 3D_FULL, 3D_PAY or 3D_HALF; initially blank.
- **Mağaza Numarası (Merchant ID)**: Merchant number.
- **Provizyon Şifresi**: Provisioning password.
- **Store Key**: 3D authentication key.
- **Terminal ID**: Terminal number.

### Akbank

- **Pos Tipi**: Defaults to 3D PAY; 3D MODEL and PAY HOSTING are alternatives.
- **Güvenli Üye İş Yeri numarası**: Management → Merchant Operations → Merchant Information.
- **Güvenli Terminal Numarası**: Management → Terminal Operations → Terminal Safe ID.
- **Secret Key**: Management → Security Keys.

### AkbankPayten

- **Pos Tipi**: Choose 3D PAY HOSTING or 3D PAY; initially blank.
- **Mağaza Numarası**: Payten merchant number.
- **Kullanıcı Adı**: API user.
- **Parola**: API user password.
- **Store Key**: 3D store key.

### İş Bankası

- **Pos Tipi**: Choose 3D PAY HOSTING, 3D PAY or 3D MODEL.
- **Mağaza Numarası**: Merchant number.
- **Kullanıcı Adı**: API user.
- **Parola**: API user password.
- **Store Key**: 3D store key.

### Yapı Kredi

- **Store Key (ENC Key)**: POSNET ENC key.
- **POSTNET ID**: Bank-issued POSNET identifier.
- **Üye İşyeri No**: Merchant number.
- **Terminal No**: Terminal number.
- **Kullanıcı Adı**: Optional; unused by this payment flow.
- **Parola**: Optional; unused by this payment flow.

### Finansbank

- **Üye İşyeri Numarası (MerchantID)**: QNB merchant number.
- **Terminal Numarası (TerminalID)**: Terminal number.
- **Kullanıcı Adı (User Code)**: API user code.
- **Kullanıcı Şifre (User Password)**: API user password.
- **3D üye İşyeri Anahtarı (MerchantPass)**: 3D merchant key; distinct from the user password.

### Ziraat

- **POX Request URL**: Required HTTPS provisioning address; bank domain only.
- **3D Secure Enrollment URL**: Required HTTPS enrollment address; bank domain only.
- **Merchant ID (Üye İşyeri Numarası)**: Merchant number.
- **Merchant Password (Üye İşyeri Şifresi)**: Merchant password.

### Kuveyt Türk

- **Mağaza Numarası**: Merchant number.
- **Müşteri Numarası**: Customer number.
- **API Kullanıcı Adı**: API user.
- **API Parola**: API password.

### Shared Options

- **Taksit Seçeneği**: Off initially; all banks except Kuveyt Türk offer installments.
- **Taksit Komisyonu**: Blank initially. Enter one count : percentage per line, for example 2 : 2.50.
- **Taksit Sınırı**: Defaults to 12; restrict to bank-approved counts. Garanti also checks the card bank.
- **Test Modu**: Off by fallback. Ziraat has no switch; QNB does not switch endpoints. Check saved settings.

Ziraat defaults: `https://sanalpos.ziraatbank.com.tr/v4/v3/Vposreq.aspx`; `https://mpi.ziraatbank.com.tr/Enrollment.aspx`. Only HTTPS addresses under ziraatbank.com.tr are accepted.

Status, fees and amount/country limits follow [Payment Modules](https://docs.wisecp.com/en/payment-modules).

## Tasks

### Connect and Enable a Bank

1. Obtain the credentials above from your bank’s merchant portal. For Garanti, request the appropriate provisioning user and 3D Store Key.
2. Select the matching POS mode. Enter the credentials, enable **Status** and click **Save Changes**.
3. Under **Payment Gateways → Initial → Enabled Module Selection**, select the bank and click **Save Changes**.
4. Use an invoice in the bank-supported currency. Shared conversion is not applied consistently; Yapı Kredi’s return flow uses TRY.

### Test the Payment and Return

1. Use bank-approved test credentials. Confirm QNB’s test arrangement and Ziraat’s two test URLs with the bank before submitting any card.
2. As the invoice’s client, select the bank and click **Pay Now**. Test successful, rejected and cancelled 3D payments.
3. Keep the same browser session through the return. Compare bank approval, reference, amount and installments with the invoice payment.
4. Resolve missing or uncertain results with the bank before retrying. After acceptance, save live credentials and the correct environment settings.

### Refund a Payment

Only AkbankPayten, İş Bankası and Finansbank provide invoice gateway refunds. Other banks require a bank-side refund.

Open `{admin}/invoices/detail?id={invoice}`. Under **Summary → Change Status**, choose **Refunded** and **Refund via payment gateway**, then **Update Status**.

The request uses the invoice’s recorded payment share. Verify the bank result. For external or custom partial refunds, record the outcome without requesting a second gateway refund.

## Things to Watch

> **Confirm Compatibility**
> 
> Garanti and Kuveyt Türk contain older endpoint/protocol choices. QNB’s Test Modu does not select an isolated endpoint. Confirm compatibility before enabling live payments.

3D return addresses are generated automatically. Do not invent a webhook field. Some returns depend on the browser session; returning to a page alone does not prove payment.

## Required Privileges

Settings: **Modules → Payment Gateways** (`MODULES_PAYMENT_SETTINGS`). Refunds: **Billing → Edit** (`INVOICES_OPERATION`).

## Related Articles

- [Payment Modules](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail Overview](https://docs.wisecp.com/en/invoice-detail-overview)
- [Garanti BBVA Integration](https://dev.garantibbva.com.tr/sanalpos-satis-on-otorizasyon-3dli)
- [QNB Integration](https://vpos.qnb.com.tr/Help/apiIntegrationDocument)