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)087↓100%MITPHPPHP ^8.1|^8.2|^8.3|^8.4 Since Apr 17Pushed 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 1w ago READMEChangelogDependencies (5)Versions (2)Used By (0) Kuveyt Türk Virtual POS Laravel SDK =================================== [](#kuveyt-türk-virtual-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) A comprehensive Laravel SDK for Kuveyt Türk Virtual POS (Sanal Pos) integration with full **3D Secure 2.0** support. Features -------- [](#features) - ✅ **3D Secure 2.0 Full Support** — Two-phase payment flow - ✅ **Two-Phase Payment**: Card verification (Kart Doğrulama) + Provision (Ödeme Alma) - ✅ **Installment (Taksit) Support** — Up to 24 installments - ✅ **Deferred Payment (Harcama Öteleme)** — Flexible payment scheduling - ✅ **Hash Data Validation** — SHA1-based request authentication - ✅ **Test & Production Environments** — Separate endpoints - ✅ **Sale / Cancel / Refund / Partial Refund Operations** — Full transaction lifecycle - ✅ **WCF SOAP Service Integration** — For cancel/refund operations - ✅ **Comprehensive Error Handling** — All Kuveyt Türk error codes - ✅ **Laravel 12.x & 13.x Compatible** - ✅ **PHP 8.1, 8.2, 8.3, 8.4 Support** Installation ------------ [](#installation) ``` composer require emre-tarhan/kuveytturk-vpos-laravel-sdk ``` ### Publish Configuration [](#publish-configuration) ``` php artisan vendor:publish --tag=kuveytturk-vpos-config ``` Or use the install command: ``` php artisan kuveytturk:install ``` This will publish the config file to `config/kuveytturk-vpos.php`. Configuration ------------- [](#configuration) Add your Kuveyt Türk credentials to `.env`: ``` KUVEYTTURK_MERCHANT_ID=your_merchant_id KUVEYTTURK_CUSTOMER_ID=your_customer_id KUVEYTTURK_USERNAME=your_api_username KUVEYTTURK_PASSWORD=your_api_password KUVEYTTURK_ENVIRONMENT=test # or 'production' ``` Or configure in `config/kuveytturk-vpos.php`: ``` 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), ]; ``` Usage ----- [](#usage) ### Basic Sale (Complete 3D Flow) [](#basic-sale-complete-3d-flow) ``` use EmreTarhan\KuveytTurkVPos\Services\KuveytTurkVPos; use EmreTarhan\KuveytTurkVPos\Dto\SaleRequest; use EmreTarhan\KuveytTurkVPos\Enums\CurrencyCode; // Inject via service container or resolve from app $vpos = app(KuveytTurkVPos::class); $request = new SaleRequest( merchantOrderId: 'ORDER-' . time(), amount: 100.00, // 100 TL - will be converted to 10000 internally okUrl: 'https://yoursite.com/payment/success', failUrl: 'https://yoursite.com/payment/fail', cardHolderName: 'John Doe', cardNumber: '5188961939192544', cardExpireDateYear: '2025', cardExpireDateMonth: '06', cardCVV2: '929', email: 'customer@example.com', clientIp: request()->ip(), billAddrCity: 'Istanbul', billAddrCountry: '792', // Turkey country code billAddrLine1: 'Sample Street No:123', billAddrPostCode: '34000', billAddrState: '34', Cc: 'John Doe', subscriber: 'customer@example.com', currencyCode: CurrencyCode::TRY, installmentCount: 0, // 0 = no installment, 1-24 for installment ); $response = $vpos->sale($request); if ($response->isSuccessful()) { // Payment successful echo "Transaction approved! Order ID: " . $response->orderId; } else { // Payment failed echo "Payment failed: " . $response->responseMessage; } ``` ### Two-Phase Payment (Manual Control) [](#two-phase-payment-manual-control) If you need more control over the payment flow: #### Phase 1: Card Verification [](#phase-1-card-verification) ``` use EmreTarhan\KuveytTurkVPos\Dto\VerifyCardRequest; $verifyRequest = new VerifyCardRequest( merchantOrderId: 'ORDER-' . time(), amount: 150.00, okUrl: 'https://yoursite.com/payment/success', failUrl: 'https://yoursite.com/payment/fail', cardHolderName: 'John Doe', cardNumber: '5188961939192544', cardExpireDateYear: '2025', cardExpireDateMonth: '06', cardCVV2: '929', email: 'customer@example.com', clientIp: request()->ip(), billAddrCity: 'Istanbul', billAddrCountry: '792', billAddrLine1: 'Sample Street No:123', billAddrPostCode: '34000', billAddrState: '34', Cc: 'John Doe', subscriber: 'customer@example.com', currencyCode: CurrencyCode::TRY, installmentCount: 3, // 3 months installment ); $verifyResponse = $vpos->verifyCard($verifyRequest); // Store MD value for Phase 2 $mdValue = $verifyResponse->md; // You'll need this for provision $orderId = $verifyResponse->orderId; ``` #### Phase 2: Provision (Complete Payment) [](#phase-2-provision-complete-payment) ``` use EmreTarhan\KuveytTurkVPos\Dto\ProvisionRequest; $provisionRequest = new ProvisionRequest( merchantOrderId: 'ORDER-' . time(), amount: 150.00, md: $mdValueFromPhase1, okUrl: 'https://yoursite.com/payment/success', failUrl: 'https://yoursite.com/payment/fail', currencyCode: CurrencyCode::TRY, installmentCount: 3, ); $provisionResponse = $vpos->provision($provisionRequest); if ($provisionResponse->isSuccessful()) { // Payment completed echo "Provision successful! RRN: " . $provisionResponse->rrn; } ``` ### Cancel Transaction (Same-Day) [](#cancel-transaction-same-day) ``` use EmreTarhan\KuveytTurkVPos\Dto\CancelRequest; use EmreTarhan\KuveytTurkVPos\Enums\CurrencyCode; $cancelRequest = new CancelRequest( merchantOrderId: 'ORDER-12345', amount: 100.00, provisionNumber: '123456', // From original sale rrn: '789012345', // Reference number stan: '654321', // System trace number orderId: 'original-order-id', currencyCode: CurrencyCode::TRY, ); $cancelResponse = $vpos->cancel($cancelRequest); if ($cancelResponse->isSuccessful()) { echo "Transaction cancelled successfully!"; } ``` ### Refund (After Batch Close) [](#refund-after-batch-close) ``` use EmreTarhan\KuveytTurkVPos\Dto\RefundRequest; $refundRequest = new RefundRequest( merchantOrderId: 'ORDER-12345', amount: 100.00, provisionNumber: '123456', rrn: '789012345', stan: '654321', orderId: 'original-order-id', currencyCode: CurrencyCode::TRY, ); $refundResponse = $vpos->refund($refundRequest); if ($refundResponse->isSuccessful()) { echo "Refund processed successfully!"; } ``` ### Partial Refund [](#partial-refund) ``` use EmreTarhan\KuveytTurkVPos\Dto\PartialRefundRequest; $partialRefundRequest = new PartialRefundRequest( merchantOrderId: 'ORDER-12345', amount: 50.00, // Partial amount provisionNumber: '123456', rrn: '789012345', stan: '654321', orderId: 'original-order-id', currencyCode: CurrencyCode::TRY, ); $partialRefundResponse = $vpos->partialRefund($partialRefundRequest); if ($partialRefundResponse->isSuccessful()) { echo "Partial refund processed!"; } ``` Response Objects ---------------- [](#response-objects) ### SaleResponse [](#saleresponse) PropertyDescription`isSuccessful()`Boolean - true if transaction approved`responseCode`Kuveyt Türk response code ("00" = success)`responseMessage`Human-readable response message`orderId`Bank's order ID`provisionNumber`Authorization number`rrn`Reference number`stan`System trace number`transactionTime`Transaction timestamp`merchantOrderId`Your order ID`md`3D Secure MD value### Error Handling [](#error-handling) ``` use EmreTarhan\KuveytTurkVPos\Services\KuveytTurkVPos; use EmreTarhan\KuveytTurkVPos\Exceptions\KuveytTurkVPosException; use EmreTarhan\KuveytTurkVPos\Enums\ErrorCode; try { $response = $vpos->sale($request); if ($response->isSuccessful()) { // Handle success } else { // Handle business failure $errorCode = ErrorCode::fromString($response->responseCode); echo "Error: " . $errorCode->label(); } } catch (KuveytTurkVPosException $e) { // Handle connection/validation errors echo "Error: " . $e->getMessage(); } ``` Error Codes ----------- [](#error-codes) CodeTurkishEnglish00Otorizasyon verildiTransaction approved01Geçersiz kart numarasıInvalid card number05Yetersiz bakiyeInsufficient balance12Geçersiz üye işyeriInvalid merchant14Geçersiz işlem / CVVInvalid transaction / CVV17Kart limiti aşıldıCard limit exceeded54Kart süresi dolmuşCard expired59Sahtekarlık şüphesiFraud suspected70Mükerrer siparişDuplicate order91Zaman aşımıTimeout96Sistem hatasıSystem error99Hashdata uyuşmazlığıHash mismatchAmount Format ------------- [](#amount-format) All amounts must be provided as actual values (e.g., 100.50 for 100 TL 50 kurus). The SDK automatically converts to bank's format (amount × 100, e.g., 10050 for 100.50 TL). ``` // Both work the same: $request = new SaleRequest(..., amount: 100.50, ...); $request = new SaleRequest(..., amount: '100.50', ...); $request = new SaleRequest(..., amount: 10050, ...); // Already in bank's format ``` Test Environment ---------------- [](#test-environment) Use the following test card for sandbox testing: FieldValueCard Number5188 9619 3919 2544CVV929Expiry06/253D Password123456**Test Endpoints:** - Card Verification: `https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelPayGate` - Provision: `https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelProvisionGate` **Production Endpoints:** - Card Verification: `https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelPayGate` - Provision: `https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelProvisionGate` Testing ------- [](#testing) ``` composer test ``` Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. License ------- [](#license) The MIT License (MIT). Please see [LICENSE](LICENSE) for more information. Support ------- [](#support) For issues and questions, please open an issue on GitHub: Email: ### Health Score 42 — FairBetter than 88% of packages Maintenance89 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity51 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 Unknown Total 1 Last Release 53d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/d59d7ad60617bc6c81c589a1779a557ffadfe756b4f05ffa0d001a2690dd9c24?d=identicon)[emretarhan](/maintainers/emretarhan) --- Top Contributors [![emre-tarhan](https://avatars.githubusercontent.com/u/106887102?v=4)](https://github.com/emre-tarhan "emre-tarhan (2 commits)") --- Tags laravelpaymentBankposturkeysanal-posvpos3d-securekuveytturkvirtualpos ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/emre-tarhan-kuveytturk-vpos-laravel-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/emre-tarhan-kuveytturk-vpos-laravel-sdk/health.svg)](https://phpackages.com/packages/emre-tarhan-kuveytturk-vpos-laravel-sdk) ``` ### Alternatives [api-platform/laravel API Platform support for Laravel 59156.3k10](/packages/api-platform-laravel)[dena-a/iran-payment a Laravel package to handle Internet Payment Gateways for Iran Banking System 312.4k1](/packages/dena-a-iran-payment)[tomshaw/electricgrid A feature-rich Livewire package designed for projects that require dynamic, interactive data tables. 119.2k](/packages/tomshaw-electricgrid)[parsisolution/gateway A Laravel package for connecting to all Iraninan payment gateways 231.7k](/packages/parsisolution-gateway) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)