PHPackages                             tcgunel/omnipay-kuveytturk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. tcgunel/omnipay-kuveytturk

ActiveLibrary[Payment Processing](/categories/payments)

tcgunel/omnipay-kuveytturk
==========================

Omnipay extension for Kuveyt Turk

v3.0.3(1mo ago)011MITPHPPHP ^8.3CI passing

Since Mar 23Pushed 1mo agoCompare

[ Source](https://github.com/tcgunel/omnipay-kuveytturk)[ Packagist](https://packagist.org/packages/tcgunel/omnipay-kuveytturk)[ Docs](https://github.com/tcgunel/omnipay-kuveytturk)[ RSS](/packages/tcgunel-omnipay-kuveytturk/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (18)Versions (7)Used By (0)

Omnipay: KuveytTurk
===================

[](#omnipay-kuveytturk)

[![Tests](https://github.com/tcgunel/omnipay-kuveytturk/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/tcgunel/omnipay-kuveytturk/actions/workflows/tests.yml)[![Latest Stable Version](https://camo.githubusercontent.com/0ff1a42138c0770eb412568f18654a1263e71935bd383dcb8b4e05aebf4b7110/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746367756e656c2f6f6d6e697061792d6b75766579747475726b2e7376673f6c6162656c3d737461626c65)](https://packagist.org/packages/tcgunel/omnipay-kuveytturk)[![Total Downloads](https://camo.githubusercontent.com/3d4bbb81053cd6d015279c09f3d760d8359d92578516a8b94e02985dd6796d7d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746367756e656c2f6f6d6e697061792d6b75766579747475726b2e737667)](https://packagist.org/packages/tcgunel/omnipay-kuveytturk)[![PHP Version](https://camo.githubusercontent.com/fb912413c0dfdf451e8ccbf5c9976e6f2dab86c58a23a4448deec3af6954eefe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f746367756e656c2f6f6d6e697061792d6b75766579747475726b2e737667)](https://packagist.org/packages/tcgunel/omnipay-kuveytturk)[![License](https://camo.githubusercontent.com/ea115be7953b29ade9d6eb20df64a54dbc58561b03e09a164149b17d6b818c14/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f746367756e656c2f6f6d6e697061792d6b75766579747475726b2e737667)](LICENSE)

**KuveytTurk sanal pos gateway for the Omnipay PHP payment processing library.**

[Omnipay](https://github.com/thephpleague/omnipay) is a framework agnostic, multi-gateway payment processing library for PHP. This package implements KuveytTurk (Kuveyt Türk Bankası) support for Omnipay.

> **v3.0 — Breaking change.** v3 migrates to KuveytTurk's new `KTPay/*` JSON endpoints with the HMAC-SHA512 hash. The 3D callback now reads `Result_MD` / `Result_OrderId` / `Result_MerchantOrderId` instead of `AuthenticationResponse`. See [UPGRADING.md](#upgrading-from-v2x).

Installation
------------

[](#installation)

```
composer require tcgunel/omnipay-kuveytturk:^3.0
```

Usage
-----

[](#usage)

### Gateway Parameters

[](#gateway-parameters)

ParameterDescription`merchantId`Merchant ID`customerId`Customer ID`userName`API Username`password`API Password (plain text — hashed internally)`installment`Installment count (0 or 1 = single payment)`secure`Use 3D Secure (true / false)### Non-3D Purchase

[](#non-3d-purchase)

```
use Omnipay\Omnipay;

$gateway = Omnipay::create('KuveytTurk');

$gateway->setMerchantId('YOUR_MERCHANT_ID');
$gateway->setCustomerId('YOUR_CUSTOMER_ID');
$gateway->setUserName('YOUR_USERNAME');
$gateway->setPassword('YOUR_PASSWORD');
$gateway->setTestMode(true);

$response = $gateway->purchase([
    'secure'        => false,
    'amount'        => '12.34',
    'currency'      => 'TRY',
    'transactionId' => 'ORDER-001',
    'installment'   => 0,
    'card'          => [
        'firstName'   => 'John',
        'lastName'    => 'Doe',
        'number'      => '4111111111111111',
        'expiryMonth' => '12',
        'expiryYear'  => '2030',
        'cvv'         => '123',
    ],
])->send();

if ($response->isSuccessful()) {
    echo "Payment successful! Code: " . $response->getCode();
} else {
    echo "Payment failed: " . $response->getMessage();
}
```

### 3D Secure Purchase

[](#3d-secure-purchase)

**Step 1 — server-to-server call to the bank, then stream the bank's HTML auto-submit form to the browser.**

```
$response = $gateway->purchase([
    'secure'        => true,
    'amount'        => '12.34',
    'currency'      => 'TRY',
    'transactionId' => 'ORDER-001',
    'installment'   => 0,
    'returnUrl'     => 'https://yoursite.com/payment/success',
    'cancelUrl'     => 'https://yoursite.com/payment/failure',
    'card'          => [
        'firstName'   => 'John',
        'lastName'    => 'Doe',
        'number'      => '4111111111111111',
        'expiryMonth' => '12',
        'expiryYear'  => '2030',
        'cvv'         => '123',
        'email'       => 'customer@example.com',
        'phone'       => '+905551112233',
    ],
])->send();

if ($response->isRedirect()) {
    // Bank returned an HTML auto-submit form. Echo it to the user's browser.
    echo $response->getRedirectResponse()->getContent();
    exit;
}

// Otherwise the bank returned a JSON error
echo "3D init failed: " . $response->getMessage();
```

**Step 2 — bank POSTs back to your `returnUrl` with `Result_MD`, `Result_OrderId`, `Result_MerchantOrderId`. Capture the funds via Provision.**

```
$response = $gateway->completePurchase([
    'merchantId'    => 'YOUR_MERCHANT_ID',
    'customerId'    => 'YOUR_CUSTOMER_ID',
    'userName'      => 'YOUR_USERNAME',
    'password'      => 'YOUR_PASSWORD',
    'transactionId' => $_POST['Result_MerchantOrderId'],
    'orderId'       => $_POST['Result_OrderId'],
    'md'            => $_POST['Result_MD'],
    'amount'        => '12.34',
    'currency'      => 'TRY',
    'returnUrl'     => 'https://yoursite.com/payment/success',
    'cancelUrl'     => 'https://yoursite.com/payment/failure',
])->send();

if ($response->isSuccessful()) {
    echo "3D Payment successful!";
} else {
    echo "3D Payment failed: " . $response->getMessage();
}
```

### Onus Card Check (BIN)

[](#onus-card-check-bin)

```
$response = $gateway->isOnusCard([
    'cardNumber' => '5400612345678901',
    'testMode'   => true,
])->send();

if ($response->isSuccessful() && $response->isOnus()) {
    // Show installment options for KuveytTurk-issued cards.
}
```

### Merchant Installment Definition

[](#merchant-installment-definition)

Returns the installment counts the merchant is allowed to offer. Rates are configured separately on the merchant side.

```
$response = $gateway->installmentDefinition([
    'merchantId' => 'YOUR_MERCHANT_ID',
    'testMode'   => true,
])->send();

if ($response->isSuccessful()) {
    foreach ($response->getInstallments() as $row) {
        // Row shape depends on the API; usually contains the installment count and any limits.
        var_dump($row);
    }
}
```

Supported Methods
-----------------

[](#supported-methods)

MethodDescription`purchase()`Non-3D or 3D sale (based on `secure` param)`completePurchase()`Complete 3D payment after bank callback (provision)`isOnusCard()`Check whether a card is KuveytTurk-issued (Onus)`installmentDefinition()`Fetch the merchant's allowed installment countsCurrency Codes (4-digit, ISO 4217 numeric, zero-padded)
-------------------------------------------------------

[](#currency-codes-4-digit-iso-4217-numeric-zero-padded)

CurrencyCodeTRY0949USD0840EUR0978GBP0826Amount Format
-------------

[](#amount-format)

Amounts are passed as standard decimal values (e.g., `12.34`). The package internally converts them to the integer kuruş format required by KuveytTurk (e.g., `1234`).

Hash Algorithm
--------------

[](#hash-algorithm)

KTPay endpoints use **HMAC-SHA512** with the SHA1Base64-encoded password as the key.

```
hashPassword = Base64(SHA1(password))
message      = hashValue . hashPassword
hashData     = Base64(HMAC-SHA512(message, hashPassword))

```

Where `hashValue` is the field concatenation:

- **Non-3D / Provision:** `MerchantId + MerchantOrderId + Amount + UserName`
- **3D:** `MerchantId + MerchantOrderId + Amount + OkUrl + FailUrl + UserName`

Endpoints
---------

[](#endpoints)

EnvironmentTypeURLTest3D PaymentTest3D ProvisionTestNon-3DTestOnus Card CheckTestInstallment DefinitionProduction3D PaymentProduction3D ProvisionProductionNon-3DProductionOnus Card CheckProductionInstallment DefinitionUpgrading from v2.x
-------------------

[](#upgrading-from-v2x)

ChangeBefore (v2)After (v3)3D init endpoint`/Home/ThreeDModelPayGate``/KTPay/Payment` (server-to-server JSON)3D provision endpoint`/Home/ThreeDModelProvisionGate``/KTPay/Provision`3D init request formatHTML form auto-submit (browser)JSON, server-side; bank returns HTML to relay3D callback payload`AuthenticationResponse` (URL-encoded XML)`Result_MD`, `Result_OrderId`, `Result_MerchantOrderId`Hash algorithmSHA1HMAC-SHA512 (key = SHA1Base64(password))Currency code`0949` (4-digit)`0949` (4-digit, unchanged)`completePurchase()` parameters`authenticationResponse`, `md``transactionId`, `orderId`, `md`, `amount`, `currency`Non-3D `/Home/Non3DPayGate` is still XML-based and still works, but uses the same HMAC-SHA512 hash and 3-digit currency codes.

Not Implemented
---------------

[](#not-implemented)

Cancel and Refund operations are not implemented.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance90

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~9 days

Total

6

Last Release

49d ago

Major Versions

v1.0.0 → v2.0.02026-03-23

v2.0.0 → v3.0.02026-05-08

PHP version history (2 changes)v1.0.0PHP ^8.0

v2.0.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/36dffe883e88aeef07c26067af3d6a7eda1c2a81f1ae45fdd430b721665131da?d=identicon)[Mobius Studio](/maintainers/Mobius%20Studio)

---

Top Contributors

[![tcgunel](https://avatars.githubusercontent.com/u/3923425?v=4)](https://github.com/tcgunel "tcgunel (12 commits)")

---

Tags

paymentgatewayomnipaysanal-pos3d-securekuveytturkkuveyt türk

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tcgunel-omnipay-kuveytturk/health.svg)

```
[![Health](https://phpackages.com/badges/tcgunel-omnipay-kuveytturk/health.svg)](https://phpackages.com/packages/tcgunel-omnipay-kuveytturk)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)