Garanti BBVA Virtual POS Laravel Paketi

1. Kurulum

Paketi Composer aracılığıyla projenize dahil edin:

composer require developertugrul/garanti-pos

2. Yapılandırma

Ayar dosyasını dışa aktarın:

php artisan vendor:publish --provider="Developertugrul\GarantiPos\GarantiPosServiceProvider"

.env dosyanıza bankadan aldığınız bilgileri ekleyin:

GARANTI_POS_MODE=PROD # veya TEST
GARANTI_POS_TERMINAL_ID=12345678
GARANTI_POS_PROV_USER_ID=PROVAUT
GARANTI_POS_PROV_PASSWORD=Sifre123
GARANTI_POS_MERCHANT_ID=1234567
GARANTI_POS_STORE_KEY=3DSecureAnahtari
GARANTI_POS_CURRENCY=949 # TL: 949, USD: 840, EUR: 978

3. Normal Satış (Non-3D)

use Developertugrul\GarantiPos\Facades\GarantiPos;

$response = GarantiPos::pay([
    'order_id' => 'Siparis123',
    'amount' => '100', // 1.00 TL için 100 kuruş gönderilir
    'installment' => '', 
], [
    'number' => '5400111122223333',
    'expire_month' => '12',
    'expire_year' => '25',
    'cvv' => '123'
]);

Örnek Başarılı Yanıt (Response):

{
    "Transaction": {
        "Response": {
            "ReasonCode": "00",
            "Message": "Approved",
            "ErrorMsg": "",
            "SysErrMsg": ""
        },
        "RetrefNum": "21300000001",
        "AuthCode": "123456"
    }
}

4. 3D Secure Satış (3D Pay)

Müşteriyi Garanti bankasının 3D doğrulama ekranına yönlendirir. Doğrulama bitince doğrudan tahsilat (payment) yapılır.

$formHtml = GarantiPos::build3DForm(
    ['order_id' => 'Siparis123', 'amount' => '100', 'security_level' => '3D_PAY'],
    ['number' => '5400...', 'expire_month' => '12', 'expire_year' => '25', 'cvv' => '123'],
    route('payment.success'),
    route('payment.error')
);
// HTML formu Blade şablonunda {!! $formHtml !!} şeklinde basılır.

5. Satış (Ortak Ödeme Sayfası - 3D OOS Pay)

Kart bilgilerinin sizin sitenizde DEĞİL, bankanın güvenli Ortak Ödeme Sayfasında (OOS) girildiği senaryodur.

$formHtml = GarantiPos::build3DOOSForm(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    route('payment.success'),
    route('payment.error')
);

6. Satış (3D Model Otorizasyonu)

Güvenlik seviyesi 3D seçildiğinde, müşteri 3D doğrulamasını başarıyla tamamlayıp sitenize dönse bile para çekilmez. İkinci adımda otorizasyon gönderilmelidir.

use Developertugrul\GarantiPos\Services\HashGenerator;

if (!HashGenerator::validate3DHash($request->all(), config('garanti-pos.store_key'))) {
    die("Hash Hatası!");
}

$response = GarantiPos::pay3DModel(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    $request->all() // Bankadan dönen POST verileri (md, cavv, eci vb.)
);

7. İptal İşlemi (Cancel)

Gün sonu alınmamış işlemlerin iptal edilmesi.

$response = GarantiPos::cancel('Siparis123');

Örnek Yanıt:

{ "Transaction": { "Response": { "ReasonCode": "00", "Message": "Approved" } } }

8. İade İşlemi (Refund) & İade İptali

Gün sonu alınmış eski işlemlerin iadesi.

$response = GarantiPos::refund('Siparis123', '100'); // 1.00 TL İade

Yapılan bir iade işlemini iptal etmek isterseniz:

$response = GarantiPos::refundVoid('Siparis123', 'IadeRetrefNum');

9. Ön Provizyon (Pre-Auth)

Kartta belirli bir tutarı bloke (bekletme) işlemi yapar.

$response = GarantiPos::preAuth(
    ['order_id' => 'Siparis123', 'amount' => '100'], 
    $cardData
);

10. Ön Provizyon Kapama (Post-Auth) & İptali

Bloke edilen tutarın tahsilata (gerçek satışa) dönüştürülmesidir.

$response = GarantiPos::postAuth('Siparis123', '100');

Kapatılan ön provizyonu iptal etmek için:

$response = GarantiPos::postAuthVoid('Siparis123', 'OrjinalRetrefNum');

11. Puan Sorgulama (Reward Inquiry)

Kredi kartındaki kazanılmış mevcut Bonus puanlarını listeler.

$response = GarantiPos::pointInquiry($cardData);
// Puan tutarı: $response['Transaction']['RewardList']['Reward']['RewardAmount']

12. Puan Kullanımı (Reward Usage)

Müşterinin kredi kartındaki puanları ödeme olarak tahsil etme işlemi.

$response = GarantiPos::rewardUsage(
    ['order_id' => 'Siparis123'], 
    $cardData, 
    '50' // 0.50 TL Puan Kullanımı
);

13. Sipariş Sorgulama (Order Inquiry)

Daha önceden gerçekleşmiş bir işlemin (tahsilatın) bankadaki durumunu ve akıbetini sorgular.

$response = GarantiPos::orderInquiry('Siparis123');

if ($response['Transaction']['Response']['ReasonCode'] == '00') {
    echo "İşlem başarılı olarak kaydedilmiş. Tutarı: " . $response['Transaction']['Amount'];
}

14. Satış (GarantiPay)

Müşteriyi doğrudan GarantiPay ile (QR kod / mobil onay) ödeme yapabileceği 3D formuna yönlendirir.

$formHtml = GarantiPos::buildGarantiPayForm(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    route('payment.success'),
    route('payment.error')
);

15. Satış (CepBank)

CepBank uygulaması üzerinden gönderilmiş bir havalenin onaylanarak tahsil edilmesi.

$response = GarantiPos::payCepBank(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    ['gsm_number' => '5551234567', 'payment_type' => 'K'] // K: Kredi Kartı, D: Debit, V: Vadesiz
);

15.1 SMS & DCC Satış Onayları

SMS veya DCC onayı için paySms ve payDcc fonksiyonlarını kullanabilirsiniz.

// SMS Ödemesi
$response = GarantiPos::paySms(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    $cardData
);

// DCC Ödemesi
$response = GarantiPos::payDcc(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    $cardData
);

16. İşlem Detay Sorgulama (Order History Inquiry)

Belirtilen siparişe ait iptal, iade vb. tüm işlem hareketlerini (history) listeler.

$response = GarantiPos::orderHistoryInquiry('Siparis123');

17. Tekrarlayan Satış (Recurring Payment)

Abonelik sistemlerinde kullanılabilecek, bankanın karttan belirli periyotlarla otomatik para çekmesini sağlayan komut.

$response = GarantiPos::payRecurring(
    ['order_id' => 'Siparis123', 'amount' => '1000'],
    $cardData,
    [
        'total_payment_num' => '5', // Toplam çekim sayısı
        'frequency_type' => 'M', // M: Ay, W: Hafta, D: Gün
        'frequency_interval' => '1', // 1 ayda bir
        'start_date' => '20261201' // Başlangıç YYYYMMDD
    ]
);

18. TCKN Doğrulama (Identify Inquiry)

Kişinin TCKN bilgisiyle banka altyapısında kimlik doğrulaması yapmak için kullanılır.

$response = GarantiPos::identifyInquiry(
    ['order_id' => 'Siparis123', 'amount' => '100'],
    $cardData,
    '12345678901' // Müşterinin T.C. Kimlik Numarası
);

19. Tüketici Kredisi & Ticari Kart Taksit İşlemleri

Müşterinin kredi faiz oranları ile veya ticari kartlara özel ötelemeli / vadeli işlem yapmasını sağlayan çok spesifik metodlardır. Normal "pay" metodundan farkı, Transaction tipinin `extendedcredit` veya `commercialcardextendedcredit` olmasıdır.

// Tüketici Kredisi
$response = GarantiPos::payExtendedCredit(['order_id' => '123', 'amount' => '1000'], $cardData);

// Ticari Kart Vadeli İşlem
$response = GarantiPos::payCommercialCardExtendedCredit(['order_id' => '123', 'amount' => '1000'], $cardData);

// Tüketici Kredisi Sorgulama
$response = GarantiPos::extendedCreditInquiry('123');

20. Diğer Spesifik Uç Noktalar

Kredi kartı detaylarını, gün sonu batch işlemlerini veya nadir senaryoları kapsayan API metodları:

// 1. BIN Sorgulama (Kartın ilk 6/8 hanesi ile tipi, bankası vb.)
$response = GarantiPos::binInquiry('540011');

// 2. DCC (Dinamik Kur) Sorgulama
$response = GarantiPos::dccInquiry('Siparis123', '540011...', '100'); // 1.00 TL

// 3. Gün Sonu Batch İşlemleri Sorgulama
$response = GarantiPos::batchInquiry();

// 4. Kampanya Kodu Sorgulama
$response = GarantiPos::campaignCodeInquiry('KAMPANYA2026');

// 5. Sipariş Listesi Sorgulama
$response = GarantiPos::orderListInquiry();

// 6. Tekrarlı Satış (Recurring) Tutar Güncelleme
// Mevcut bir abonelikteki gelecek ödemelerin tutarını güncellemek için
$response = GarantiPos::recurringUpdate('Siparis123', [
    ['PaymentNum' => 3, 'Amount' => '2244'], // 3. çekim tutarı 22.44 TL
    ['PaymentNum' => 5, 'Amount' => '1637']
]);

// 7. Tekrarlı Satış / Abonelik Komple İptali
$response = GarantiPos::recurringCancel('Siparis123');