PHPackages                             emre-tarhan/kuveytturk-vpos-laravel-sdk - 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. emre-tarhan/kuveytturk-vpos-laravel-sdk

ActiveLibrary[Payment Processing](/categories/payments)

emre-tarhan/kuveytturk-vpos-laravel-sdk
=======================================

Kuveyt Türk Sanal Pos (Virtual POS) Laravel SDK with 3D Secure 2.0 support

1.0.0(1mo ago)01MITPHPPHP ^8.1|^8.2|^8.3|^8.4

Since Jun 12Pushed 1mo agoCompare

[ Source](https://github.com/emre-tarhan/kuveytturk-vpos-laravel-sdk)[ Packagist](https://packagist.org/packages/emre-tarhan/kuveytturk-vpos-laravel-sdk)[ Docs](https://github.com/emre-tarhan/kuveytturk-vpos-laravel-sdk)[ RSS](/packages/emre-tarhan-kuveytturk-vpos-laravel-sdk/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

Kuveyt Turk Sanal POS Laravel SDK
=================================

[](#kuveyt-turk-sanal-pos-laravel-sdk)

[![Latest Version](https://camo.githubusercontent.com/e701e51b74c6550ac9a1b920b3cb4dcc24928b61e9258f393de0eb89db44b230/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f656d72652d74617268616e2f6b75766579747475726b2d76706f732d6c61726176656c2d73646b2e737667)](https://packagist.org/packages/emre-tarhan/kuveytturk-vpos-laravel-sdk)[![PHP](https://camo.githubusercontent.com/90dedce4f9932cf1b949d610f69c1cb17b23818343d43e71bbf94252140f6af3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f656d72652d74617268616e2f6b75766579747475726b2d76706f732d6c61726176656c2d73646b2e737667)](https://packagist.org/packages/emre-tarhan/kuveytturk-vpos-laravel-sdk)[![License](https://camo.githubusercontent.com/4ce6118828cbd1dec74f90a19d191bff5c712e3ba77c29b3a692709df5059f6e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f656d72652d74617268616e2f6b75766579747475726b2d76706f732d6c61726176656c2d73646b2e737667)](https://packagist.org/packages/emre-tarhan/kuveytturk-vpos-laravel-sdk)

Kuveyt Turk Sanal POS entegrasyonu icin kapsamli Laravel SDK. Tam **3D Secure 2.0** destegi.

Ozellikler
----------

[](#ozellikler)

- **3D Secure 2.0 Tam Destek** — Iki asamali odeme akisi
- **Iki Asamali Odeme**: Kart Dogrulama + Provizyon (Odeme Alma)
- **Taksit Destegi** — 24 aya kadar taksit imkani
- **Ertelemeli Odeme (Harcama Oteleme)** — Esnek odeme planlama
- **Hash Veri Dogrulama** — SHA1 tabanli istek dogrulama
- **Test & Produksiyon Ortamlari** — Ayri endpoint'ler
- **Satis / Iptal / Iade / Kismi Iade Islemleri** — Tam islem yasam dongusu
- **WCF SOAP Servis Entegrasyonu** — Iptal/iade islemleri icin
- **Kapsamli Hata Yonetimi** — Tum Kuveyt Turk hata kodlari
- **Laravel 12.x & 13.x Uyumlu**
- **PHP 8.1, 8.2, 8.3, 8.4 Destegi**

Gereksinimler
-------------

[](#gereksinimler)

- **PHP**: 8.1, 8.2, 8.3 veya 8.4
- **Laravel**: 12.x veya 13.x
- **PHP Eklentileri**: curl, libxml, openssl

Kurulum
-------

[](#kurulum)

```
composer require emre-tarhan/kuveytturk-vpos-laravel-sdk
```

### Ayarlari Yayinlama

[](#ayarlari-yayinlama)

```
php artisan vendor:publish --tag=kuveytturk-vpos-config
```

Veya kurulum komutunu kullanin:

```
php artisan kuveytturk:install
```

Bu islem ayar dosyasini `config/kuveytturk-vpos.php` konumuna yayinlayacaktir.

Yapilandirma
------------

[](#yapilandirma)

Kuveyt Turk kimlik bilgilerinizi `.env` dosyasina ekleyin:

```
KUVEYTTURK_MERCHANT_ID=uye_isyeri_numaraniz
KUVEYTTURK_CUSTOMER_ID=musteri_numaraniz
KUVEYTTURK_USERNAME=api_kullanici_adiniz
KUVEYTTURK_PASSWORD=api_sifreniz
KUVEYTTURK_ENVIRONMENT=test # veya 'production'
```

Veya `config/kuveytturk-vpos.php` dosyasindan yapilandirin:

```
return [
    'merchant_id' => env('KUVEYTTURK_MERCHANT_ID', ''),
    'customer_id' => env('KUVEYTTURK_CUSTOMER_ID', ''),
    'username' => env('KUVEYTTURK_USERNAME', ''),
    'password' => env('KUVEYTTURK_PASSWORD', ''),
    'environment' => env('KUVEYTTURK_ENVIRONMENT', 'test'),
    'timeout' => env('KUVEYTTURK_TIMEOUT', 60),
    'connect_timeout' => env('KUVEYTTURK_CONNECT_TIMEOUT', 30),
];
```

Kullanim
--------

[](#kullanim)

### Temel Satis (Tam 3D Akis)

[](#temel-satis-tam-3d-akis)

```
use EmreTarhan\KuveytTurkVPos\Services\KuveytTurkVPos;
use EmreTarhan\KuveytTurkVPos\Dto\SaleRequest;
use EmreTarhan\KuveytTurkVPos\Enums\CurrencyCode;

// Servis konteynerinden enjekte et veya app'ten cozumle
$vpos = app(KuveytTurkVPos::class);

$request = new SaleRequest(
    merchantOrderId: 'ORDER-' . time(),
    amount: 100.00, // 100 TL - dahili olarak 10000'e donusturulur
    okUrl: 'https://siteniz.com/odeme/basarili',
    failUrl: 'https://siteniz.com/odeme/basarisiz',
    cardHolderName: 'Ahmet Yilmaz',
    cardNumber: '5188961939192544',
    cardExpireDateYear: '25',
    cardExpireDateMonth: '06',
    cardCVV2: '929',
    email: 'musteri@ornek.com',
    clientIp: request()->ip(),
    billAddrCity: 'Istanbul',
    billAddrCountry: '792', // Turkiye ulke kodu
    billAddrLine1: 'Ornek Sokak No:123',
    billAddrPostCode: '34000',
    billAddrState: '34',
    Cc: 'Ahmet Yilmaz',
    subscriber: 'musteri@ornek.com',
    currencyCode: CurrencyCode::TRY,
    installmentCount: 0, // 0 = taksitsiz, 1-24 arasi taksit
);

$response = $vpos->sale($request);

if ($response->isSuccessful()) {
    // Odeme basarili
    echo "Islem onaylandi! Siparis No: " . $response->orderId;
} else {
    // Odeme basarisiz
    echo "Odeme basarisiz: " . $response->responseMessage;
}
```

### Iki Asamali Odeme (Manuel Kontrol)

[](#iki-asamali-odeme-manuel-kontrol)

Odeme akisi uzerinde daha fazla kontrole ihtiyaciniz varsa:

#### Asama 1: Kart Dogrulama

[](#asama-1-kart-dogrulama)

```
use EmreTarhan\KuveytTurkVPos\Dto\VerifyCardRequest;

$verifyRequest = new VerifyCardRequest(
    merchantOrderId: 'ORDER-' . time(),
    amount: 150.00,
    okUrl: 'https://siteniz.com/odeme/basarili',
    failUrl: 'https://siteniz.com/odeme/basarisiz',
    cardHolderName: 'Ahmet Yilmaz',
    cardNumber: '5188961939192544',
    cardExpireDateYear: '25',
    cardExpireDateMonth: '06',
    cardCVV2: '929',
    email: 'musteri@ornek.com',
    clientIp: request()->ip(),
    billAddrCity: 'Istanbul',
    billAddrCountry: '792',
    billAddrLine1: 'Ornek Sokak No:123',
    billAddrPostCode: '34000',
    billAddrState: '34',
    Cc: 'Ahmet Yilmaz',
    subscriber: 'musteri@ornek.com',
    currencyCode: CurrencyCode::TRY,
    installmentCount: 3, // 3 ay taksit
);

$verifyResponse = $vpos->verifyCard($verifyRequest);

// Asama 2 icin MD degerini saklayin
$mdValue = $verifyResponse->md; // Provizyon icin gerekli
$orderId = $verifyResponse->orderId;
```

#### Asama 2: Provizyon (Odeme Tamamlama)

[](#asama-2-provizyon-odeme-tamamlama)

```
use EmreTarhan\KuveytTurkVPos\Dto\ProvisionRequest;

$provisionRequest = new ProvisionRequest(
    merchantOrderId: 'ORDER-' . time(),
    amount: 150.00,
    md: $asama1denGelenMdDegeri,
    okUrl: 'https://siteniz.com/odeme/basarili',
    failUrl: 'https://siteniz.com/odeme/basarisiz',
    currencyCode: CurrencyCode::TRY,
    installmentCount: 3,
);

$provisionResponse = $vpos->provision($provisionRequest);

if ($provisionResponse->isSuccessful()) {
    // Odeme tamamlandi
    echo "Provizyon basarili! RRN: " . $provisionResponse->rrn;
}
```

### Islem Iptali (Ayni Gun)

[](#islem-iptali-ayni-gun)

```
use EmreTarhan\KuveytTurkVPos\Dto\CancelRequest;
use EmreTarhan\KuveytTurkVPos\Enums\CurrencyCode;

$cancelRequest = new CancelRequest(
    merchantOrderId: 'ORDER-12345',
    amount: 100.00,
    provisionNumber: '123456', // Orijinal satis isleminden
    rrn: '789012345',          // Referans numarasi
    stan: '654321',            // Sistem iz numarasi
    orderId: 'orijinal-siparis-no',
    currencyCode: CurrencyCode::TRY,
);

$cancelResponse = $vpos->cancel($cancelRequest);

if ($cancelResponse->isSuccessful()) {
    echo "Islem basariyla iptal edildi!";
}
```

### Iade (Gun Sonu Sonrasi)

[](#iade-gun-sonu-sonrasi)

```
use EmreTarhan\KuveytTurkVPos\Dto\RefundRequest;

$refundRequest = new RefundRequest(
    merchantOrderId: 'ORDER-12345',
    amount: 100.00,
    provisionNumber: '123456',
    rrn: '789012345',
    stan: '654321',
    orderId: 'orijinal-siparis-no',
    currencyCode: CurrencyCode::TRY,
);

$refundResponse = $vpos->refund($refundRequest);

if ($refundResponse->isSuccessful()) {
    echo "Iade basariyla gerceklestirildi!";
}
```

### Kismi Iade

[](#kismi-iade)

```
use EmreTarhan\KuveytTurkVPos\Dto\PartialRefundRequest;

$partialRefundRequest = new PartialRefundRequest(
    merchantOrderId: 'ORDER-12345',
    amount: 50.00, // Kismi tutar
    provisionNumber: '123456',
    rrn: '789012345',
    stan: '654321',
    orderId: 'orijinal-siparis-no',
    currencyCode: CurrencyCode::TRY,
);

$partialRefundResponse = $vpos->partialRefund($partialRefundRequest);

if ($partialRefundResponse->isSuccessful()) {
    echo "Kismi iade basariyla gerceklestirildi!";
}
```

Gercek Entegrasyon Ornegi (3D Secure Akisi)
-------------------------------------------

[](#gercek-entegrasyon-ornegi-3d-secure-akisi)

Asagida produksiyon ortaminda kullanilan, tam 3D Secure odeme akisi ornegi bulunmaktadir. Bu akis 5 asamadan olusur: odeme baslatma, bankaya yonlendirme, callback karsilama, provizyon tamamlama ve siparisi sonuclandirma.

### Asama 1: Servis Konteynerine Kayit

[](#asama-1-servis-konteynerine-kayit)

```
// App\Providers\AppServiceProvider::register()
use EmreTarhan\KuveytTurkVPos\Services\KuveytTurkVPos;

$this->app->singleton(KuveytTurkVPos::class, function () {
    return KuveytTurkVPos::fromConfig(config('kuveytturk-vpos'));
});
```

### Asama 2: Odeme Baslatma (Controller)

[](#asama-2-odeme-baslatma-controller)

Kart dogrulama islemi bankadan HTML dondurur. Bu HTML'i tarayicida render etmeniz gerekir — otomatik olarak bankanin 3D Secure sayfasina yonlendiren bir form icerir.

```
use EmreTarhan\KuveytTurkVPos\Services\KuveytTurkVPos;
use EmreTarhan\KuveytTurkVPos\Dto\VerifyCardRequest;
use EmreTarhan\KuveytTurkVPos\Enums\CurrencyCode;

public function odeme(Request $request, KuveytTurkVPos $vpos)
{
    $verifyRequest = new VerifyCardRequest(
        merchantOrderId: 'ORDER-' . time(),
        amount: 100.00,
        okUrl: route('odeme.callback.basarili'),
        failUrl: route('odeme.callback.basarisiz'),
        cardHolderName: $request->input('kart_sahibi'),
        cardNumber: $request->input('kart_numarasi'),
        cardExpireDateYear: $request->input('kart_yil'),   // 2 haneli: '28'
        cardExpireDateMonth: $request->input('kart_ay'),    // 2 haneli: '12'
        cardCVV2: $request->input('kart_cvv'),
        email: $request->input('email'),
        clientIp: $request->ip(),
        billAddrCity: 'Istanbul',
        billAddrCountry: '792',
        billAddrLine1: 'Ornek Sokak',
        billAddrPostCode: '34000',
        billAddrState: '34',
        Cc: $request->input('kart_sahibi'),
        subscriber: $request->input('email'),
        currencyCode: CurrencyCode::TRY,
        installmentCount: 0,
    );

    $hashCalculator = $vpos->getHashCalculator();
    $hashData = $verifyRequest->generateHash($hashCalculator);
    $xml = $verifyRequest->toXml($hashData);

    // Bankanin kart dogrulama endpoint'ine gonder
    $response = Http::withHeaders([
        'Content-Type' => 'application/xml',
    ])->withBody($xml, 'application/xml')
      ->post($vpos->getCardVerificationUrl());

    $body = $response->body();

    // Banka 3D Secure yonlendirme HTML'i dondurur — session'a kaydet ve tarayicida render et
    if (str_contains($body, '