Garanti BBVA Virtual POS
Laravel Paketi Dokümantasyonu

pay(array $orderData, array $cardData, string $type = 'sales'): array PROVAUT

Standart satış işlemi. Taksitli satış için installment alanını doldurun.

Parametreler

Örnek — Peşin Satış

use Developertugrul\GarantiPos\Facades\GarantiPos;

$response = GarantiPos::pay(
    [
        'order_id'    => 'SIPARIS-' . uniqid(),
        'amount'      => '10000',      // 100,00 TL
        'installment' => '',           // Peşin
        'ip_address'  => request()->ip(),
        'email'       => 'musteri@ornek.com',
    ],
    [
        'number'       => '5400111111111111',
        'expire_month' => '12',
        'expire_year'  => '28',
        'cvv'          => '123',
    ]
);

if ($response['ProcReturnCode'] === '00') {
    // Ödeme başarılı
    $authCode   = $response['AuthCode'];
    $retrefNum  = $response['RetrefNum'];
}

Örnek — Taksitli Satış (3 Taksit)

$response = GarantiPos::pay(
    [
        'order_id'    => 'SIPARIS-TAK-001',
        'amount'      => '30000',   // 300,00 TL
        'installment' => '3',
    ],
    $cardData
);

Örnek Başarılı Yanıt

Karşılık Gelen GVP XML — Type

preAuth(array $orderData, array $cardData): array PROVAUT

Ön provizyon — kart limitini bloke eder ancak tahsilat yapmaz. Otel, araç kiralama gibi gecikmiş tahsilat senaryolarında kullanılır.

// Adım 1: Ön provizyon al
$preResponse = GarantiPos::preAuth(
    ['order_id' => 'PREAUTH-001', 'amount' => '50000'],
    ['number' => '5400111111111111', 'expire_month' => '12', 'expire_year' => '28', 'cvv' => '123']
);

$retrefNum = $preResponse['RetrefNum'];

postAuth(string $orderId, string $amount): array PROVAUT

Ön provizyon kapama — gerçek tahsilatı gerçekleştirir. Tutar, ön provizyon tutarından küçük veya eşit olabilir.

// Adım 2: Ön provizyonu kapat (örn. 3 gün sonra)
$postResponse = GarantiPos::postAuth(
    orderId: 'PREAUTH-001',
    amount:  '45000'    // Gerçek harcama — ön provizyon tutarından az olabilir
);

GVP XML Karşılıkları

cancel(string $orderId, string $originalRetrefNum = '', string $amount = '1'): array PROVRFN

Aynı gün içinde gerçekleşen bir işlemi iptal eder. Garanti GVP, iptal için Type=void kullanır (cancel değil).

$response = GarantiPos::cancel(
    orderId:           'SIPARIS-001',
    originalRetrefNum: '406310073566',   // preResponse'dan alınan RetrefNum
    amount:            '10000'
);

if ($response['ProcReturnCode'] === '00') {
    // İptal başarılı
}

refund(string $orderId, string $amount, string $originalRetrefNum = ''): array PROVRFN

Önceki günlere ait bir işlemi iade eder. Kısmi iade desteklenir — orijinal tutardan az bir miktar gönderilebilir.

// Tam iade
$response = GarantiPos::refund(
    orderId:           'SIPARIS-001',
    amount:            '10000',
    originalRetrefNum: '406310073566'
);

// Kısmi iade (100 TL'lik işlemden 30 TL iade)
$response = GarantiPos::refund('SIPARIS-001', '3000', '406310073566');

if ($response['ProcReturnCode'] === '00') {
    // İade başarılı
}

postAuthVoid(string $orderId, string $originalRetrefNum = '', string $amount = '1'): array PROVRFN

Ön provizyon kapamanın iptali.

$response = GarantiPos::postAuthVoid('PREAUTH-001', $retrefNum);

refundVoid(string $orderId, string $originalRetrefNum = '', string $amount = '1'): array PROVRFN

Yapılmış bir iadenin iptali.

$response = GarantiPos::refundVoid('SIPARIS-001', $retrefNum);

build3DForm(array $orderData, array $cardData, string $successUrl, string $errorUrl, string $type = 'sales'): string

Kullanıcıyı bankanın 3D kimlik doğrulama sayfasına yönlendiren, otomatik gönderimli HTML form döner. Bu formu echo ile sayfaya basın; JavaScript otomatik submit yapar.

// routes/web.php
Route::get('/odeme/baslat', [PaymentController::class, 'start3D']);
Route::post('/odeme/basarili', [PaymentController::class, 'success3D'])->name('payment.success');
Route::post('/odeme/hata', [PaymentController::class, 'error3D'])->name('payment.error');

// app/Http/Controllers/PaymentController.php
public function start3D(Request $request): string
{
    return GarantiPos::build3DForm(
        [
            'order_id'       => 'ORDER-' . uniqid(),
            'amount'         => '15000',        // 150,00 TL
            'installment'    => '',
            'security_level' => '3D_PAY',       // 3D_PAY | 3D_FULL | 3D_HALF
            'ip_address'     => $request->ip(),
            'email'          => 'musteri@ornek.com',
        ],
        [
            'number'       => '5400111111111111',
            'expire_month' => '12',
            'expire_year'  => '28',
            'cvv'          => '123',
        ],
        route('payment.success'),   // Başarı URL'i (POST ile geri döner)
        route('payment.error')      // Hata URL'i
    );
}

parse3DResponse(array $postData, array $expected = []): array

Garanti'nin geri POST ettiği callback verilerini doğrular. Hash, MD status, işlem kodu, sipariş kimliği ve tutarı ayrı ayrı raporlar.

public function success3D(Request $request): Response
{
    $check = GarantiPos::parse3DResponse(
        $request->all(),
        [
            'order_id' => session('order_id'),
            'amount'   => session('order_amount'),  // Kuruş cinsinden
        ]
    );

    // Tüm kontroller
    if (! $check['hash_valid']) {
        abort(400, 'Hash doğrulama başarısız');
    }
    if (! $check['md_status_accepted']) {
        abort(400, '3D kimlik doğrulama reddedildi: mdstatus=' . $check['md_status']);
    }
    if (! $check['order_matches']) {
        abort(400, 'Sipariş uyuşmazlığı');
    }

    // Buraya kadar her şey tamam — provizyona geçin
    return $this->finalizePayment($request->all());
}

Dönüş Değerleri

pay3DModel(array $orderData, array $cardData, array $threeDResponse): array

3D_FULL veya 3D_HALF güvenlik seviyesinde, banka callback'inden sonra provizyonu siz alırsınız. Bu metod callback verilerini kullanarak bankaya ikinci XML isteği gönderir.

// parse3DResponse kontrollerinden geçtikten sonra:
$response = GarantiPos::pay3DModel(
    [
        'order_id' => session('order_id'),
        'amount'   => session('order_amount'),
    ],
    [],          // Kart bilgisi gerekmez — bankadan gelen mddata kullanılır
    $request->all()  // Tüm 3D callback POST verisi
);

if ($response['ProcReturnCode'] === '00') {
    // Provizyon başarılı
    $authCode = $response['AuthCode'];
}

buildOOSForm(array $orderData, string $successUrl, string $errorUrl, string $type = 'sales'): string PROVOOS

$formHtml = GarantiPos::buildOOSForm(
    [
        'order_id'       => 'OOS-001',
        'amount'         => '10000',
        'security_level' => 'OOS_PAY',
        'ip_address'     => request()->ip(),
    ],
    route('payment.success'),
    route('payment.error')
);

echo $formHtml;

Ticari Kart OOS

use Developertugrul\GarantiPos\Enums\TransactionType;

$formHtml = GarantiPos::buildOOSForm(
    ['order_id' => 'COMMERCIAL-001', 'amount' => '50000'],
    route('payment.success'),
    route('payment.error'),
    TransactionType::COMMERCIAL_CARD   // txntype=commercialcard
);

build3DOOSForm(array $orderData, string $successUrl, string $errorUrl, string $type = 'sales'): string PROVOOS

3D doğrulama ile birleştirilmiş OOS akışı.

$formHtml = GarantiPos::build3DOOSForm(
    [
        'order_id'       => '3DOOS-001',
        'amount'         => '20000',
        'security_level' => '3D_OOS_PAY',    // 3D_OOS_PAY | 3D_OOS_FULL | 3D_OOS_HALF
        'installment'    => '',
    ],
    route('payment.success'),
    route('payment.error')
);

buildGarantiPayForm(array $orderData, string $successUrl, string $errorUrl): string PROVOOS

GarantiPay hosted formunu oluşturur. Güvenlik seviyesi CUSTOM_PAY olarak gönderilir. Hash txntype=gpdatarequest ile hesaplanır.

$formHtml = GarantiPos::buildGarantiPayForm(
    [
        'order_id'    => 'GP-' . uniqid(),
        'amount'      => '25000',         // 250,00 TL
        'company_name' => 'Örnek Mağaza',
        'bnsuseflag'  => 'Y',             // Bonus kullanım izni
        'installments' => [
            ['number' => '1', 'amount' => '25000'],
            ['number' => '2', 'amount' => '25000'],
            ['number' => '3', 'amount' => '25000'],
        ],
        'items' => [
            [
                'number'       => '1',
                'product_id'   => 'SKU-001',
                'quantity'     => '1',
                'price'        => '25000',
                'total_amount' => '25000',
                'name'         => 'Ürün Adı',
            ],
        ],
    ],
    route('payment.garantipay.success'),
    route('payment.garantipay.error')
);

echo $formHtml;

garantiPayDataRequest(array $orderData): array PROVAUT

GarantiPay XML DataRequest — bankanın ödeme sayfasını açmak için gerekli bağlantıyı döner. Type=gpdatarequest, SubType=sales ile çalışır.

$response = GarantiPos::garantiPayDataRequest([
    'order_id'              => 'GP-DATA-001',
    'amount'                => '25000',
    'company_name'          => 'Örnek Mağaza',
    'return_server_url'     => route('payment.garantipay.server'),
    'return_url'            => route('payment.garantipay.return'),
    'gsm_number'            => '5XXXXXXXXX',
    'total_installment_count' => '3',
    'items' => [
        ['number' => '1', 'product_id' => 'SKU-001', 'quantity' => '1', 'price' => '25000'],
    ],
]);

// Yanıt içindeki GarantiPay bağlantısını müşteriye gönderin
$garantiPayUrl = $response['GarantiPaY']['Url'] ?? null;

pointInquiry(array $cardData): array PROVAUT

Kartın mevcut bonus/puan bakiyesini sorgular. Type=rewardinq ile çalışır.

$response = GarantiPos::pointInquiry([
    'order_id'     => 'PUAN-SORGU-' . uniqid(),
    'number'       => '4282209004348015',
    'expire_month' => '05',
    'expire_year'  => '28',
    'cvv'          => '123',
]);

// Yanıtta puan bilgileri:
$bonusAmount = $response['RewardInqResult']['ChequeInfo'] ?? null;

rewardUsage(array $orderData, array $cardData, string $pointAmount): array PROVAUT

Ödeme sırasında bonus/puan kullanımı. Type=sales + RewardList/Reward bloğu ile çalışır.

$response = GarantiPos::rewardUsage(
    [
        'order_id'    => 'BONUS-001',
        'amount'      => '20000',        // 200,00 TL
        'reward_type' => 'BNS',          // BNS=Bonus, CHQ=Çek, PTS=Puan
    ],
    [
        'number'       => '4282209004348015',
        'expire_month' => '05',
        'expire_year'  => '28',
        'cvv'          => '123',
    ],
    '5000'   // Kullanılacak puan (50,00 TL değerinde)
);

// Kalan tutar kart ile tahsil edilir: 200 - 50 = 150 TL

$response = GarantiPos::pay(
    [
        'order_id'    => 'FBB-001',
        'amount'      => '50000',
        'reward_list' => [
            ['type' => 'BNS', 'used_amount' => '5000', 'gained_amount' => '0'],
            ['type' => 'CHQ', 'used_amount' => '2000', 'gained_amount' => '0'],
        ],
    ],
    $cardData
);

dccInquiry(string $orderId, string $cardNumber, string $amount): array PROVAUT

Kartın yabancı para birimi kurunu sorgular. Type=dccinq ile çalışır.

$dccInfo = GarantiPos::dccInquiry(
    orderId:    'DCC-SORGU-001',
    cardNumber: '4111111111111111',   // Yabancı kart numarası
    amount:     '10000'              // TL cinsinden tutar
);

// Yanıtta kur ve yabancı para tutarı gelir
$foreignAmount   = $dccInfo['DccInfo']['Amount'] ?? null;
$foreignCurrency = $dccInfo['DccInfo']['CurrencyCode'] ?? null;

payDcc(array $orderData, array $cardData): array PROVAUT

DCC ödemesi gerçekleştirir. SubType=dcc ve DCC/Currency bloğu ile çalışır.

$response = GarantiPos::payDcc(
    [
        'order_id'     => 'DCC-001',
        'amount'       => '10000',       // TL tutarı
        'dcc_currency' => '840',         // Yabancı para birimi kodu (840=USD)
    ],
    [
        'number'       => '4111111111111111',
        'expire_month' => '12',
        'expire_year'  => '28',
        'cvv'          => '456',
    ]
);

Adım 1: paySms(array $orderData, array $cardData): array

SubType=sms ile preauth/sales isteği gönderir; banka müşteriye SMS atar.

// Adım 1: SMS gönder
$response = GarantiPos::paySms(
    ['order_id' => 'SMS-001', 'amount' => '10000'],
    ['number' => '5400111111111111', 'expire_month' => '12', 'expire_year' => '28', 'cvv' => '123']
);

Adım 2: smsPostAuth(array $orderData, string $smsPassword): array

Müşterinin girdiği SMS kodunu bankaya doğrulatır ve provizyonu tamamlar.

// Adım 2: Müşteri SMS kodunu girdi → tamamla
$response = GarantiPos::smsPostAuth(
    ['order_id' => 'SMS-001', 'amount' => '10000'],
    '123456'   // Müşterinin girdiği SMS şifresi
);

if ($response['ProcReturnCode'] === '00') {
    // SMS doğrulama + ödeme başarılı
}

payExtre(array $orderData, array $cardData, string $extreInfo): array

// Ekstre doğrulama ile satış
$response = GarantiPos::payExtre(
    ['order_id' => 'EXTRE-001', 'amount' => '10000'],
    $cardData,
    '123456789'   // Ekstre/hesap bilgisi
);

preAuthExtre(array $orderData, array $cardData, string $extreInfo): array

// Ekstre doğrulama ile ön provizyon
$response = GarantiPos::preAuthExtre(
    ['order_id' => 'EXTRE-002', 'amount' => '10000'],
    $cardData,
    '123456789'
);

postAuthExtre(array $orderData, string $extreInfo, array $cardData = []): array

// Ekstre doğrulama ile ön provizyon kapama
$response = GarantiPos::postAuthExtre(
    ['order_id' => 'EXTRE-002', 'amount' => '10000'],
    '123456789'
);

identifyInquiry(array $orderData, array $cardData, string $tckn): array PROVAUT

$response = GarantiPos::identifyInquiry(
    ['order_id' => 'TCKN-001', 'amount' => '100'],
    [
        'number'       => '5400111111111111',
        'expire_month' => '12',
        'expire_year'  => '28',
        'cvv'          => '123',
    ],
    '12345678901'   // TC Kimlik Numarası
);

$matched = $response['ProcReturnCode'] === '00';

payCepBank(array $orderData, array $cepBankData): array PROVAUT

CepBank/GSMNumber/PaymentType/HashDate/HashValue XML bloğu ile çalışır.

$response = GarantiPos::payCepBank(
    [
        'order_id' => 'CEP-001',
        'amount'   => '10000',
    ],
    [
        'gsm_number'   => '5XXXXXXXXX',
        'payment_type' => 'K',                   // K=Kredi kartı bakiye
        'hash_date'    => date('Ymd'),           // YYYYMMDD
        'hash_value'   => 'BANKA_TARAFINDAN_URETILMIS_HASH',
    ]
);

payUtility(array $orderData, array $cardData, array $utilityPaymentData): array PROVAUT

Su, elektrik, doğalgaz gibi fatura ödemeleri. UtilityPayment XML bloğu kullanılır.

$response = GarantiPos::payUtility(
    ['order_id' => 'FATDIR-001', 'amount' => '25000'],
    $cardData,
    [
        'invoice_id'  => 'FAT-2026-001',
        'invoice_type' => '1',   // 1=Elektrik, 2=Su, 3=Doğalgaz
        'subscriber_no' => '1234567890',
    ]
);

payGsmUnitSales(array $orderData, array $cardData, array $gsmUnitSalesData): array PROVAUT

GSM kontör/paket satışı. GSMUnitSales XML bloğu kullanılır.

$response = GarantiPos::payGsmUnitSales(
    ['order_id' => 'GSM-001', 'amount' => '5000'],
    $cardData,
    [
        'gsm_quantity'    => '2',
        'operator_code'   => 'TURKCELL',
        'subscriber_msisdn' => '5XXXXXXXXX',
    ]
);

payMoneyCard(array $orderData, array $cardData, array $moneyCardData): array PROVAUT

MoneyCard / hediye kartı ödemesi. MoneyCard XML bloğu kullanılır.

$response = GarantiPos::payMoneyCard(
    ['order_id' => 'MONEY-001', 'amount' => '10000'],
    $cardData,
    [
        'money_invoice'   => '10000',
        'money_card_no'   => 'HEDIYE-KART-12345',
    ]
);

payRecurring(array $orderData, array $cardData, array $recurringData): array PROVAUT

Sabit Tutarlı Tekrarlı Satış

$response = GarantiPos::payRecurring(
    [
        'order_id' => 'REC-001',
        'amount'   => '9900',   // Her ay çekilecek tutar (99,00 TL)
    ],
    $cardData,
    [
        'type'               => 'R',         // R=Tekrarlı
        'total_payment_num'  => '12',        // Toplam taksit sayısı
        'frequency_type'     => 'MONTHLY',   // MONTHLY | WEEKLY | DAILY
        'frequency_interval' => '1',         // Her 1 ayda bir
        'start_date'         => '20260701',  // İlk çekim tarihi YYYYMMDD
    ]
);

Değişken Tutarlı Tekrarlı Satış

$response = GarantiPos::payRecurring(
    ['order_id' => 'REC-VAR-001', 'amount' => '1000'],
    $cardData,
    [
        'type'               => 'G',         // G=Değişken
        'total_payment_num'  => '3',
        'frequency_type'     => 'MONTHLY',
        'frequency_interval' => '1',
        'start_date'         => '20260701',
    ]
);

recurringUpdate(string $orderId, array $paymentList): array PROVAUT

Bekleyen tekrarlı taksit tutarlarını günceller. Type=recurringupdate kullanılır.

// Bekleyen 2 taksitin tutarını güncelle
$response = GarantiPos::recurringUpdate(
    'REC-VAR-001',
    [
        ['Amount' => '12000'],   // 1. taksit: 120 TL
        ['Amount' => '15000'],   // 2. taksit: 150 TL
    ]
);

recurringCancel(string $orderId, string $amount = '100'): array PROVAUT

Bekleyen tüm tekrarlı taksitleri iptal eder. Type=recurringvoid, PROVAUT (PROVRFN değil) kullanılır.

$response = GarantiPos::recurringCancel('REC-001');

payExtendedCredit(array $orderData, array $cardData): array PROVAUT

Tüketici kredisi / vadeli taksit. Type=extendedcredit ile çalışır.

$response = GarantiPos::payExtendedCredit(
    [
        'order_id'    => 'KREDIT-001',
        'amount'      => '100000',    // 1.000,00 TL
        'installment' => '12',
    ],
    $cardData
);

payDownPaymentSale(array $orderData, array $cardData): array PROVAUT

Peşinatlı taksitli satış. Type=sales + DownPaymentRate alanı ile çalışır.

$response = GarantiPos::payDownPaymentSale(
    [
        'order_id'          => 'PESINAT-001',
        'amount'            => '50000',
        'installment'       => '6',
        'down_payment_rate' => '20',    // %20 peşinat
    ],
    $cardData
);

payDelayedSale(array $orderData, array $cardData): array PROVAUT

Otelemeli satış — tahsilat belirli gün sonra yapılır. Type=sales + DelayDayCount ile çalışır.

$response = GarantiPos::payDelayedSale(
    [
        'order_id'       => 'OTELEME-001',
        'amount'         => '30000',
        'delay_day_count' => '7',     // 7 gün sonra tahsil et
    ],
    $cardData
);

payCommercialCardExtendedCredit(array $orderData, array $cardData): array PROVAUT

Ticari kart ile vadeli işlem. Type=commercialcardextendedcredit ve CommercialCardExtendedCredit/PaymentList XML bloğu kullanılır.

$response = GarantiPos::payCommercialCardExtendedCredit(
    [
        'order_id' => 'TIC-001',
        'amount'   => '60000',
        'payments' => [
            ['number' => '1', 'amount' => '20000'],  // 1. ödeme: 200 TL
            ['number' => '2', 'amount' => '20000'],  // 2. ödeme: 200 TL
            ['number' => '3', 'amount' => '20000'],  // 3. ödeme: 200 TL
        ],
    ],
    $cardData
);

orderInquiry(string $orderId, string $amount = '100'): array

Belirli bir siparişin son durumunu sorgular. Type=orderinq

$response = GarantiPos::orderInquiry('SIPARIS-001');

$status    = $response['ProcReturnCode'];
$authCode  = $response['AuthCode'] ?? null;
$retrefNum = $response['RetrefNum'] ?? null;

Örnek Yanıt

orderHistoryInquiry(string $orderId, string $amount = '100'): array

Bir siparişin tüm işlem geçmişini listeler (iade, iptal vb.). Type=orderhistoryinq

$response = GarantiPos::orderHistoryInquiry('SIPARIS-001');

orderListInquiry(?string $startDate, ?string $endDate, int $listPageNum = 1, string $orderId = '', string $amount = '100'): array

Tarih aralığına göre sipariş listesi sorgular. Type=orderlistinq — StartDate/EndDate Order altında, ListPageNum Transaction altında gönderilir.

// Belirli tarih aralığı
$response = GarantiPos::orderListInquiry(
    startDate:   '01/06/2026',   // GG/AA/YYYY formatı
    endDate:     '14/06/2026',
    listPageNum: 1
);

// İkinci sayfa
$response = GarantiPos::orderListInquiry('01/06/2026', '14/06/2026', 2);

batchInquiry(?string $batchNum = null, int $listPageNum = 1, string $orderId = '', string $amount = '100'): array

Günsonu (batch) sorgulama. Type=batchinq — BatchNum ve ListPageNum Transaction altında.

// Mevcut batch (bugünkü)
$response = GarantiPos::batchInquiry();

// Belirli batch numarası
$response = GarantiPos::batchInquiry('004063');

// Sayfalı listeleme
$response = GarantiPos::batchInquiry(null, 2);

binInquiry(string $binNumber = '', string $amount = '100'): array

Kart BIN (ilk 6-8 hane) bilgisini sorgular; kart tipi, banka, yurt içi/dışı bilgisi döner. Type=bininq

$response = GarantiPos::binInquiry('540011');

$cardType   = $response['CardInfo']['CardType'] ?? null;     // 'KREDI' / 'DEBIT'
$bankName   = $response['CardInfo']['BankName'] ?? null;
$issuerId   = $response['CardInfo']['IssuerID'] ?? null;

campaignCodeInquiry(string $campaignCode, string $amount = '100'): array

Kampanya kodu ile kampanya detaylarını sorgular. Type=campaigncodeinq

$response = GarantiPos::campaignCodeInquiry('KAMPANYA2026');

extendedCreditInquiry(string $orderId, string $amount = '100'): array

Tüketici kredisi / vadeli taksit sorgusu. Type=extendedcreditinq

$response = GarantiPos::extendedCreditInquiry('KREDIT-001');

settlementInquiry(string $date, array $transactionSummaries = [], array $options = []): array

Mutabakat sorgusu. Root SettlementInq bloğu ile çalışır (diğer sorgulardan farklı yapı).

$response = GarantiPos::settlementInquiry(
    date:                '20260614',  // YYYYMMDD
    transactionSummaries: [
        ['Type' => 'sales',  'Count' => '5', 'Amount' => '50000', 'CurrencyCode' => '949'],
        ['Type' => 'refund', 'Count' => '1', 'Amount' => '10000', 'CurrencyCode' => '949'],
    ]
);