YkPos

https://github.com/ykakkaya/ykpos
Admin
YkPos is a PHP and Laravel library that unifies virtual POS integrations for Turkish banks and...
Tokens:67,876
Snippets:331
Trust Score:7.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### BINInstallmentQueryResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTO for BIN installment queries.

```APIDOC
## BINInstallmentQueryResponse

### Description
Response DTO for BIN installment queries.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `confirm` | `boolean` | Confirmation flag |
| `installment_list` | `Installment[]` | List of installment options |
| `private_response` | `string` | Raw response from the bank, useful for logging and debugging |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### AllInstallmentQueryResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTO for all installment queries.

```APIDOC
## AllInstallmentQueryResponse

### Description
Response DTO for all installment queries.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `confirm` | `boolean` | Confirmation flag |
| `installment_list` | `AllInstallment[]` | List of all installment options |
| `private_response` | `string` | Raw response from the bank, useful for logging and debugging |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### Install YKPOS package with Composer

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Installs the YKPOS package version ^1.1 using Composer. This command requires the repository block to be present in composer.json.

```bash
composer require ykakkaya/ykpos:^1.1
```

--------------------------------

### AdditionalInstallmentQueryResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTO for additional installment queries.

```APIDOC
## AdditionalInstallmentQueryResponse

### Description
Response DTO for additional installment queries.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `confirm` | `boolean` | Confirmation flag |
| `installment_list` | `AdditionalInstallment[]` | List of additional installment options |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### Install YKPOS after Packagist publication

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Installs the YKPOS package with a single Composer command once the package is published on Packagist. No repositories block is needed in this case.

```bash
composer require ykakkaya/ykpos
```

--------------------------------

### Verify installed YKPOS version

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Shows the installed YKPOS package version. Expect to see 'versions : * v1.1.1'. If v1.0.0 appears, the project uses PHP 8.3 and Composer silently downgraded the package.

```bash
composer show ykakkaya/ykpos
```

--------------------------------

### 3D Secure Satış — Vakıf Katılım ve Yapı Kredi Notu (Sale3DResponse)

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Yapı Kredi ve Vakıf Katılım'da provizyon isteğinin tutar ve para birimi bilgisi banka dönüşünde gelmediği için `Sale3DResponse` içinde ayrıca gönderilmelidir. Vakıf Katılım'da `installment` zorunludur; Yapı Kredi'de `currency` eksikse `InvalidArgumentException` fırlatılır.

```php
new Sale3DResponse(
    responseArray: $request->all(),
    currency: Currency::TRY,
    amount: 100.50,
    installment: 3,     // sadece Vakıf Katılım
);
```

--------------------------------

### Tüm Taksit Listesi Sorgulama - YkPosClient::allInstallmentQuery

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Tutar bazlı, tüm banka ve kart programları için taksit seçeneklerini döner. installment_list boş olabilir, bu yüzden ?? [] kullanılır.

```php
use Ykakkaya\YkPos\DTOs\Requests\AllInstallmentQueryRequest;

$response = YkPosClient::allInstallmentQuery(new AllInstallmentQueryRequest(
    amount: 1000.00,
    currency: Currency::TRY,
), $auth);

foreach ($response->installment_list ?? [] as $option) {
    // $option->bank_code                   → banka kodu
    // $option->cardProgram                 → CreditCardProgram (Bonus, Axess, World, …)
    // $option->count                       → taksit sayısı
    // $option->customerCostCommissionRate  → komisyon oranı
    // $option->installment_list            → [['installment' => 3, 'rate' => 0.05], ...]
}
```

--------------------------------

### BIN Bazlı Taksit Sorgulama - YkPosClient::binInstallmentQuery

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Kartın BIN numarasına göre taksit seçeneklerini sorgular. Yanıtın confirm alanı true ise installment_list üzerinde döngü kurulur.

```php
use Ykakkaya\YkPos\DTOs\Requests\BINInstallmentQueryRequest;

$response = YkPosClient::binInstallmentQuery(new BINInstallmentQueryRequest(
    BIN: '411111',          // kart numarasının ilk 6–8 hanesi
    amount: 1000.00,
    currency: Currency::TRY,
), $auth);

if ($response->confirm) {
    foreach ($response->installment_list as $installment) {
        // $installment->count                      → taksit sayısı
        // $installment->customerCostCommissionRate → müşteriye yansıyan komisyon oranı
    }
}
```

--------------------------------

### Fork & Clone Komutları

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Projeyi fork'layıp klonlamak ve upstream remote eklemek için kullanılan bash komutları.

```bash
git clone https://github.com/KULLANICI_ADINIZ/ykpos.git
cd ykpos

git remote add upstream https://github.com/ykakkaya/ykpos.git
```

--------------------------------

### Kod Stili Komutları

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Laravel Pint ile kod stilini kontrol etmek ve otomatik düzeltmek için kullanılan bash komutları.

```bash
composer lint-test

composer lint
```

--------------------------------

### Run Composer test, coverage, and lint commands

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Composer script commands for testing, coverage, and linting. Run tests with Pest, generate coverage reports, format code with Laravel Pint, and check formatting without changes.

```bash
composer test           # vendor/bin/pest --testdox
composer test-coverage  # kapsam raporu
composer lint           # Laravel Pint ile kod formatı
composer lint-test      # formatı değiştirmeden kontrol
```

--------------------------------

### PHP: YKPos ile satış işlemi başlatma

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

YKPos istemcisiyle 3D'siz bir satış işlemi başlatır. MerchantAuth ve SaleRequest yapılandırmasını, test platformu bayrağını ve yanıt durumunun nasıl kontrol edileceğini gösterir. Başarılı yanıtta işlem kimliği ekrana yazdırılır.

```php
use Ykakkaya\YkPos\YkPosClient;
use Ykakkaya\YkPos\DTOs\{MerchantAuth, SaleInfo, Payment3DConfig};
use Ykakkaya\YkPos\DTOs\Requests\SaleRequest;
use Ykakkaya\YkPos\Enums\{Currency, SaleResponseStatus};
use Ykakkaya\YkPos\Services\BankService;

$auth = new MerchantAuth(
    bank_code: BankService::IS_BANKASI,
    merchant_id: 'magaza-kodu',
    merchant_user: 'api-kullanicisi',
    merchant_password: 'api-sifresi',
    merchant_storekey: '3d-storekey',
    test_platform: true,
);

$response = YkPosClient::sale(new SaleRequest(
    order_number: dechex(time()),
    customer_ip_address: '1.1.1.1',
    sale_info: new SaleInfo(
        card_name_surname: 'TEST KART',
        card_number: '4022780520669303',
        card_expiry_month: 1,
        card_expiry_year: 2050,
        card_cvv: '988',
        currency: Currency::TRY,
        amount: 10.00,
        installment: 1,
    ),
    payment_3d: new Payment3DConfig(confirm: false),
), $auth);

if ($response->status === SaleResponseStatus::Success) {
    echo "Ödeme alındı: {$response->transaction_id}";
}
```

--------------------------------

### Push Komutu

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Branch'i uzak depoya göndermek için kullanılan bash komutu.

```bash
git push origin feat/yeni-ozellik
```

--------------------------------

### Ek Taksit Kampanyası Sorgulama - YkPosClient::additionalInstallmentQuery

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Payten (MSU) üzerinde tanımlı kampanyalar ile İş Bankası/QNB Finansbank anlık banka kampanyalarını döner. Kampanya bilgileri installment_list içinde listelenir.

```php
use Ykakkaya\YkPos\DTOs\Requests\AdditionalInstallmentQueryRequest;

$response = YkPosClient::additionalInstallmentQuery(
    new AdditionalInstallmentQueryRequest(sale_info: $saleInfo),
    $auth,
);

foreach ($response->installment_list ?? [] as $campaign) {
    // $campaign->count               → ek taksit sayısı
    // $campaign->campaign_code       → satışta SaleInfo::$campaign_code olarak gönderilir
    // $campaign->campaignName
    // $campaign->campaignDescription
    // $campaign->required            → kampanyanın zorunlu olup olmadığı
}
```

--------------------------------

### Use path repository for local development

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Configures a path repository with symlink for local development so changes to the package are immediately reflected. Used instead of the VCS repository when working on the package.

```json
{
  "repositories": [
    { "type": "path", "url": "../ykpos", "options": { "symlink": true } }
  ]
}
```

--------------------------------

### Laravel Facade Kullanımı - YkPos::sale, cancel, refund, saleQuery

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

YkPos facade üzerinden satış, iptal, iade ve işlem sorgulama işlemleri yapılabilir. Her metod ilgili istek nesnesini ve auth parametresini alır.

```php
use Ykakkaya\YkPos\Facades\YkPos;

$response = YkPos::sale($saleRequest, $auth);
$response = YkPos::cancel($cancelRequest, $auth);
$response = YkPos::refund($refundRequest, $auth);
$response = YkPos::saleQuery(new SaleQueryRequest('ORDER-001'), $auth);
```

--------------------------------

### 3D'siz Direkt Satış (payment_3d->confirm = false)

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

3D doğrulaması olmadan satış yapar ve sonucu doğrudan döndürür. `payment_3d->confirm = false` gönderilir. Yanıt durumu `Success` veya `Error` olabilir.

```php
use Ykakkaya\YkPos\YkPosClient;
use Ykakkaya\YkPos\DTOs\{MerchantAuth, SaleInfo, CustomerInfo, Payment3DConfig};
use Ykakkaya\YkPos\DTOs\Requests\SaleRequest;
use Ykakkaya\YkPos\Services\BankService;
use Ykakkaya\YkPos\Enums\{Currency, Country};

$auth = new MerchantAuth(
    bank_code: BankService::QNBPAY,
    merchant_user: 'uygulama-anahtari',
    merchant_password: 'uygulama-parolasi',
    merchant_storekey: 'merchant-key',
    test_platform: true,
);

$customerInfo = new CustomerInfo(
    name: 'Ahmet',
    surname: 'Yılmaz',
    email_address: 'test@test.com',
    phone_number: '5551112233',
    tax_number: '1111111111',
    tax_office: 'Maltepe',
    country: Country::TUR,
    city_name: 'İstanbul',
    town_name: 'Maltepe',
    address_description: 'Adres satırı',
    post_code: '34000',
);

$saleRequest = new SaleRequest(
    order_number: dechex(time()),
    customer_ip_address: '1.1.1.1',
    sale_info: new SaleInfo(
        card_name_surname: 'TEST KART',
        card_number: '4022780520669303',
        card_expiry_month: 1,
        card_expiry_year: 2050,
        card_cvv: '988',
        currency: Currency::TRY,
        amount: 10.00,
        installment: 1,
    ),
    invoice_info: $customerInfo,
    shipping_info: $customerInfo,
    payment_3d: new Payment3DConfig(confirm: false),
);

$response = YkPosClient::sale($saleRequest, $auth);

echo "Durum   : {$response->status->name}\n";   // Success | Error
echo "Mesaj   : {$response->message}\n";
echo "İşlem ID: {$response->transaction_id}\n";
```

--------------------------------

### CreditCardBinQueryResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTO for credit card BIN queries.

```APIDOC
## CreditCardBinQueryResponse

### Description
Response DTO for credit card BIN queries.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `bin_number` | `string` | BIN number of the card |
| `bank_code` | `string` | Bank code |
| `card_type` | `string` | Type of the card |
| `card_brand` | `string` | Brand of the card |
| `commercial_card` | `string` | Whether the card is a commercial card |
| `card_program` | `string` | Card program |
| `banks_with_installments` | `string` | Banks offering installments |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### Hata Yönetimi: try-catch ile YkPosClient::sale

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

YkPosClient::sale çağrısını saran try-catch bloğu. HttpRequestException ağ hatası, timeout veya SSL sorunlarında; InvalidArgumentException validasyon hatalarında veya tanımsız banka kodunda yakalanır. Yanıt durumu SaleResponseStatus::Error olduğunda banka isteği reddetmiştir ve $response->message ile $response->private_response alanlarına bakılmalıdır.

```php
use Ykakkaya\YkPos\Exceptions\HttpRequestException;
use Ykakkaya\YkPos\Enums\SaleResponseStatus;

try {
    $response = YkPosClient::sale($saleRequest, $auth);

    if ($response->status === SaleResponseStatus::Error) {
        // Banka isteği reddetti — $response->message ve $response->private_response'a bakın
    }
} catch (HttpRequestException $e) {
    // Ağ hatası, timeout, SSL sorunu vb.

```

--------------------------------

### MerchantAuth Oluşturma (PHP)

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

MerchantAuth sınıfını kullanarak bir sanal POS için API bilgilerini yapılandırır. bank_code olarak BankService::SIPAY, kullanıcı adı olarak 'app-id', şifre olarak 'app-secret', store key olarak 'merchant-key' ve test ortamı için test_platform: true kullanılır. installment_commission_policy olarak InstallmentCommissionPolicy::ChargeToCustomer seçilmiştir. Bu örnek, yapılandırma veya veritabanından oluşturma yerine doğrudan kurucu metod ile kullanılır.

```php
use Ykakkaya\YkPos\Enums\InstallmentCommissionPolicy;

$auth = new MerchantAuth(
    bank_code: BankService::SIPAY,
    merchant_user: 'app-id',
    merchant_password: 'app-secret',
    merchant_storekey: 'merchant-key',
    test_platform: true,
    installment_commission_policy: InstallmentCommissionPolicy::ChargeToCustomer,
);
```

--------------------------------

### Test Komutları

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Tüm testleri, belirli bir test dosyasını ve kod coverage'ı çalıştırmak için kullanılan bash komutları.

```bash
composer test

vendor/bin/pest tests/Unit/BankServiceTest.php

composer test-coverage
```

--------------------------------

### 3D Secure Satış — 2. Adım (callback) Sale3DResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

3D doğrulaması sonrası bankadan gelen callback'i işler. `Sale3DResponse` ile yanıt alınır; `status`, `message`, `transaction_id` ve `private_response` alanları kullanılır. Başarılıysa başarılı, değilse hatalı görünüm döndürülür.

```php
use Ykakkaya\YkPos\DTOs\Requests\Sale3DResponse;
use Ykakkaya\YkPos\Enums\SaleResponseStatus;

public function virtualPOS3DResponse(Request $request)
{
    $response = YkPosClient::sale3DResponse(
        new Sale3DResponse(responseArray: $request->all()),
        $auth,
    );

    // $response->status                        → Success | Error
    // $response->message                       → sonuç mesajı
    // $response->transaction_id                → banka işlem numarası
    // $response->private_response['response_1'] → bankadan gelen ham callback verisi
    // $response->private_response['response_2'] → varsa provizyon/tamamlama yanıtı

    return $response->status === SaleResponseStatus::Success
        ? view('payment.success', compact('response'))
        : view('payment.failed', compact('response'));
}
```

--------------------------------

### 3D Secure Satış — 1. Adım (SaleRequest ve Payment3DConfig)

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

3D Secure akışını başlatır. `payment_3d->confirm = true` gönderilir ve `return_url` bankanın sonucu POST edeceği adrestir. Yanıt durumuna göre kullanıcı yönlendirilir veya HTML formu gösterilir.

```php
$saleRequest = new SaleRequest(
    order_number: dechex(time()),
    customer_ip_address: request()->ip(),
    sale_info: new SaleInfo(/* ... */),
    invoice_info: $customerInfo,
    shipping_info: $customerInfo,
    payment_3d: new Payment3DConfig(
        confirm: true,
        return_url: 'https://example.com/payment/3d-response',
        is_desktop: true,
    ),
);

$response = YkPosClient::sale($saleRequest, $auth);

use Ykakkaya\YkPos\Enums\SaleResponseStatus;

return match ($response->status) {
    // $response->message bir URL'dir → kullanıcıyı yönlendirin
    SaleResponseStatus::RedirectURL  => redirect()->away($response->message),
    // $response->message bir HTML formudur → tarayıcıda basıp submit edin
    SaleResponseStatus::RedirectHTML => response($response->message),
    default => back()->withErrors($response->message),
};
```

--------------------------------

### İptal İşlemi (CancelRequest)

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Aynı gün içinde yapılan işlemler için iptal yapar. `CancelRequest` ile sipariş numarası, işlem kimliği ve para birimi gönderilir. Yanıt başarılıysa iptal edilen tutar ekrana yazdırılır.

```php
use Ykakkaya\YkPos\DTOs\Requests\CancelRequest;
use Ykakkaya\YkPos\Enums\ResponseStatus;

$response = YkPosClient::cancel(new CancelRequest(
    customer_ip_address: request()->ip(),
    order_number: 'ORDER-001',
    transaction_id: 'TXN-001',
    currency: Currency::TRY,
), $auth);

if ($response->status === ResponseStatus::Success) {
    echo "İptal edilen tutar: {$response->refund_amount}";
}
```

--------------------------------

### Branch Oluşturma Komutları

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Güncel main'den yeni bir branch açmak için kullanılan bash komutları.

```bash
git checkout main
git pull upstream main
git checkout -b feat/yeni-ozellik
```

--------------------------------

### SaleQueryResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTO for sale queries.

```APIDOC
## SaleQueryResponse

### Description
Response DTO for sale queries.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `status` | `string` | Status of the query |
| `message` | `string` | Message from the gateway |
| `order_number` | `string` | Unique order number |
| `transaction_id` | `string` | Transaction identifier |
| `transactionDate` | `string` | Date of the transaction |
| `transactionStatus` | `string` | Status of the transaction |
| `amount` | `float` | Transaction amount |
| `private_response` | `string` | Raw response from the bank, useful for logging and debugging |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### Geliştirme Komutları

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Bağımlılıkları kurmak, testleri çalıştırmak ve kod stilini kontrol etmek için kullanılan bash komutları.

```bash
composer install

composer test

composer lint-test

composer lint
```

--------------------------------

### Payment3DConfig

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

DTO for configuring 3D payment settings.

```APIDOC
## Payment3DConfig

### Description
Configuration for 3D payment flow.

### Parameters

| Field | Type | Description |
|-------|------|-------------|
| `confirm` | `bool` | `true` - 3D flow, `false` - direct charge |
| `return_url` | `string` | URL to POST the 3D result |
| `is_desktop` | `bool` | Desktop/mobile 3D template selection. Default: `true` |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### İşlem Sorgulama - YkPosClient::saleQuery

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Sipariş numarasına göre işlem durumunu sorgular. Yanıt durumu SaleQueryResponseStatus::Found ise işlem detaylarına erişilir.

```php
use Ykakkaya\YkPos\DTOs\Requests\SaleQueryRequest;
use Ykakkaya\YkPos\Enums\{SaleQueryResponseStatus, SaleQueryTransactionStatus};

$response = YkPosClient::saleQuery(new SaleQueryRequest('ORDER-001'), $auth);

if ($response->status === SaleQueryResponseStatus::Found) {
    $response->transaction_id;    // banka işlem numarası
    $response->amount;            // çekilen tutar
    $response->transactionDate;   // işlem tarihi
    $response->transactionStatus; // Paid | Refunded | PartialRefunded | Voided
}
```

--------------------------------

### Gateway Şablonu

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Yeni bir banka/ödeme kuruluşu eklerken kullanılacak PHP sınıf şablonu.

```php
<?php

namespace Ykakkaya\YkPos\Gateways\Banks;

use Ykakkaya\YkPos\Contracts\VirtualPOSServiceInterface;

class YeniBankaGateway implements VirtualPOSServiceInterface
{
    // Tüm interface metodlarını implemente edin
}
```

--------------------------------

### SaleInfo

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

DTO reference for sale information.

```APIDOC
## SaleInfo

### Description
Represents sale information for a payment transaction. All fields are named parameters and the class supports a `fromArray()` factory method.

### Parameters

| Field | Type | Description |
|-------|------|-------------|
| `card_name_surname` | `string` | Name on the card (Turkish characters are automatically simplified) |
| `card_number` | `string` | 15-19 digits |
| `card_expiry_month` | `int` | 1-12 |
| `card_expiry_year` | `int` | 4 digits (e.g., `2050`) |
| `card_cvv` | `string` | 3-4 digits |
| `currency` | `?Currency` | Currency |
| `amount` | `float` | Must be greater than zero |
| `point` | `float` | Points to use (on supported POS devices) |
| `installment` | `int` | 1-15. Use `1` for cash payment |
| `campaign_code` | `string` | Additional installment campaign code (Payten) |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### SaleResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTO for sale operations.

```APIDOC
## SaleResponse

### Description
Response DTO for sale operations.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `status` | `SaleResponseStatus` | Status of the sale |
| `message` | `string` | Message from the gateway |
| `order_number` | `string` | Unique order number |
| `transaction_id` | `string` | Transaction identifier |
| `private_response` | `string` | Raw response from the bank, useful for logging and debugging |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### Banka Listesi - YkPosClient::allBankList

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Tüm bankaları veya filtreli olarak aktif bankaları ve toplu POS'ları listeler. Bank alanları arasında bank_code, bank_name, collective_vpos, commissionAutoAdd, installment_api ve gatewayClass bulunur.

```php
use Ykakkaya\YkPos\DTOs\Bank;

$banks = YkPosClient::allBankList();

// Sadece entegrasyonu hazır olanlar
$aktif = YkPosClient::allBankList(
    fn (Bank $bank) => $bank->gatewayClass !== null,
);

// Sadece taksit API'si olan toplu POS'lar
$toplu = YkPosClient::allBankList(
    fn (Bank $bank) => $bank->collective_vpos && $bank->installment_api,
);
```

--------------------------------

### Commit Örnekleri

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Conventional Commits kurallarına uygun örnek commit mesajları.

```bash
git commit -m "feat(gateway): Enpara sanal pos entegrasyonu"
git commit -m "fix(akbank): 3D secure hash hesaplama düzeltildi"
git commit -m "test: VakifbankGateway unit testleri eklendi"
git commit -m "docs: kurulum adımları güncellendi"
```

--------------------------------

### Commit Mesajı Formatı

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Conventional Commits standardına uygun commit mesajı formatı.

```text
<tip>(<kapsam>): <açıklama>
```

--------------------------------

### Publish YKPOS config file

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Publishes the YKPOS package's config file using Laravel's vendor:publish Artisan command. This registers the package's configuration for customization.

```bash
php artisan vendor:publish --provider="Ykakkaya\YkPos\YkPosServiceProvider"
```

--------------------------------

### Breaking Change Commit Örneği

Source: https://github.com/ykakkaya/ykpos/blob/main/CONTRIBUTING.md

Breaking change içeren bir commit için örnek.

```bash
git commit -m "feat!: MerchantAuth constructor parametreleri değişti"
```

--------------------------------

### YkPosClient API Metotları

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

YkPosClient sınıfı üzerinden çağrılabilen tüm statik metotların API referansı.

```APIDOC
## [sale] 

### Description
Karttan çekim işlemi gerçekleştirir. payment_3d->confirm ile 3D'li veya 3D'siz ödeme seçilebilir.

### Method
sale

### Endpoint
YkPosClient::sale(SaleRequest, MerchantAuth)

### Parameters
#### Request Body
- **SaleRequest** (object) - Gerekli - Satış isteği nesnesi. `order_number`, `customer_ip_address`, `sale_info` ve `payment_3d` alanlarını içerir.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri. `bank_code`, `merchant_id`, `merchant_user`, `merchant_password`, `merchant_storekey`, `test_platform` alanlarını içerir.

### Response
#### Success Response
- **SaleResponse** (object) - Satış sonucu. `status` (SaleResponseStatus) ve `transaction_id` alanlarını içerir.

### Response Example
```php
if ($response->status === SaleResponseStatus::Success) {
    echo "Ödeme alındı: {$response->transaction_id}";
}
```

## [sale3DResponse] 

### Description
3D callback'ini doğrular ve çekimi tamamlar.

### Method
sale3DResponse

### Endpoint
YkPosClient::sale3DResponse(Sale3DResponse, MerchantAuth)

### Parameters
#### Request Body
- **Sale3DResponse** (object) - Gerekli - 3D yanıt nesnesi.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **SaleResponse** (object) - Satış sonucu. `status` ve `transaction_id` alanlarını içerir.

## [binInstallmentQuery] 

### Description
Tek bir BIN için taksit seçeneklerini sorgular.

### Method
binInstallmentQuery

### Endpoint
YkPosClient::binInstallmentQuery(BINInstallmentQueryRequest, MerchantAuth)

### Parameters
#### Request Body
- **BINInstallmentQueryRequest** (object) - Gerekli - BIN taksit sorgulama isteği.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **BINInstallmentQueryResponse** (object) - Taksit seçenekleri. `confirm` ve `message` alanlarını içerir.

## [allInstallmentQuery] 

### Description
Tutar bazlı, tüm banka/kart programları için taksit listesi döner.

### Method
allInstallmentQuery

### Endpoint
YkPosClient::allInstallmentQuery(AllInstallmentQueryRequest, MerchantAuth)

### Parameters
#### Request Body
- **AllInstallmentQueryRequest** (object) - Gerekli - Taksit sorgulama isteği.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **AllInstallmentQueryResponse** (object) - Taksit listesi. `confirm` ve `message` alanlarını içerir.

## [additionalInstallmentQuery] 

### Description
Ek taksit kampanyalarını sorgular.

### Method
additionalInstallmentQuery

### Endpoint
YkPosClient::additionalInstallmentQuery(AdditionalInstallmentQueryRequest, MerchantAuth)

### Parameters
#### Request Body
- **AdditionalInstallmentQueryRequest** (object) - Gerekli - Ek taksit sorgulama isteği.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **AdditionalInstallmentQueryResponse** (object) - Ek taksit kampanyaları. `confirm` ve `message` alanlarını içerir.

## [cancel] 

### Description
Aynı gün yapılan işlemin iptalini gerçekleştirir.

### Method
cancel

### Endpoint
YkPosClient::cancel(CancelRequest, MerchantAuth)

### Parameters
#### Request Body
- **CancelRequest** (object) - Gerekli - İptal isteği.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **CancelResponse** (object) - İptal sonucu. `status` ve `message` alanlarını içerir.

## [refund] 

### Description
Tam veya kısmi iade işlemi gerçekleştirir.

### Method
refund

### Endpoint
YkPosClient::refund(RefundRequest, MerchantAuth)

### Parameters
#### Request Body
- **RefundRequest** (object) - Gerekli - İade isteği.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **RefundResponse** (object) - İade sonucu. `status` ve `message` alanlarını içerir.

## [saleQuery] 

### Description
Sipariş numarasıyla işlem sorgulama yapar.

### Method
saleQuery

### Endpoint
YkPosClient::saleQuery(SaleQueryRequest, MerchantAuth)

### Parameters
#### Request Body
- **SaleQueryRequest** (object) - Gerekli - Sipariş numarası içeren istek.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **SaleQueryResponse** (object) - İşlem bilgileri. `status` ve `message` alanlarını içerir.

## [creditCardBinQuery] 

### Description
Gömülü BIN veritabanından kart bilgisi döner. Ağ isteği yapmaz.

### Method
creditCardBinQuery

### Endpoint
YkPosClient::creditCardBinQuery(CreditCardBinQueryRequest, MerchantAuth)

### Parameters
#### Request Body
- **CreditCardBinQueryRequest** (object) - Gerekli - BIN sorgulama isteği.
- **MerchantAuth** (object) - Gerekli - Banka kimlik doğrulama bilgileri.

### Response
#### Success Response
- **?CreditCardBinQueryResponse** (object) - Kart bilgisi veya null. `status` ve `message` alanlarını içerir.

## [allCreditCardBinList] 

### Description
Gömülü BIN veritabanının tamamını döner.

### Method
allCreditCardBinList

### Endpoint
YkPosClient::allCreditCardBinList()

### Parameters
Bu metot parametre almaz.

### Response
#### Success Response
- **CreditCardBinQueryResponse[]** (array) - Tüm kart bilgileri.

## [allBankList] 

### Description
Tanımlı 48 banka/kuruluş kaydını döner. Opsiyonel filtre fonksiyonu alır.

### Method
allBankList

### Endpoint
YkPosClient::allBankList(?callable $filter)

### Parameters
#### Query Parameters
- **filter** (?callable) - Opsiyonel - Banka listesini filtrelemek için kullanılan callback.

### Response
#### Success Response
- **Bank[]** (array) - Banka listesi.

```

--------------------------------

### CustomerInfo

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

DTO for customer information used in invoice and shipping.

```APIDOC
## CustomerInfo

### Description
Customer information used for both invoice and shipping. Fields are automatically simplified before sending.

### Parameters

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Customer's first name |
| `surname` | `string` | Customer's surname |
| `email_address` | `string` | Customer's email |
| `phone_number` | `string` | Customer's phone number |
| `tax_number` | `string` | Customer's tax number |
| `tax_office` | `string` | Customer's tax office |
| `country` | `Country` (enum) | Customer's country |
| `city_name` | `string` | Customer's city |
| `town_name` | `string` | Customer's town |
| `address_description` | `string` | Customer's address description |
| `post_code` | `string` | Customer's postcode |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields. Can be used as invoice_info or shipping_info.
```

--------------------------------

### Kredi Kartı BIN Sorgulama - YkPosClient::creditCardBinQuery ve allCreditCardBinList

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Pakete gömülü 9.957 kayıtlık BIN veritabanı üzerinden kart bilgilerini sorgular. 8 haneli BIN için tam eşleşme bulunamazsa ilk 6 hane ile tekrar aranır; kayıt yoksa null döner.

```php
use Ykakkaya\YkPos\DTOs\Requests\CreditCardBinQueryRequest;

$bin = YkPosClient::creditCardBinQuery(new CreditCardBinQueryRequest('404308'));

if ($bin !== null) {
    $bin->bank_code;               // "0062"
    $bin->card_type;               // CreditCardType::Credit
    $bin->card_brand;              // CreditCardBrand::Visa
    $bin->card_program;            // CreditCardProgram::Bonus
    $bin->commercial_card;         // false
    $bin->banks_with_installments; // bu programa taksit yapabilen banka kodları
}

// Tüm kart kayıtları
$all = YkPosClient::allCreditCardBinList();
```

--------------------------------

### Add VCS repository to composer.json

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Adds the YKPOS GitHub repository as a VCS repository in composer.json so Composer can find the package before it is published on Packagist. Required for every project that uses the package.

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/ykakkaya/ykpos"
    }
  ]
}
```

--------------------------------

### CancelResponse / RefundResponse

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Response DTOs for cancel and refund operations.

```APIDOC
## CancelResponse / RefundResponse

### Description
Response DTOs for cancel and refund operations.

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `status` | `ResponseStatus` | Status of the operation |
| `message` | `string` | Message from the gateway |
| `refund_amount` | `double` | Amount refunded |
| `private_response` | `string` | Raw response from the bank, useful for logging and debugging |

### Factory Method
- `fromArray()` - Creates an instance from an array of fields.
```

--------------------------------

### Require local YKPOS dev version

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Requires the YKPOS package in dev mode (@dev) when using a path repository for local development. This pairs with the path repository configuration.

```bash
composer require ykakkaya/ykpos:@dev
```

--------------------------------

### İade İşlemi - YkPosClient::refund

Source: https://github.com/ykakkaya/ykpos/blob/main/README.md

Tam veya kısmi iade yapmak için kullanılır. RefundRequest nesnesi ile iade tutarı ve işlem bilgileri gönderilir.

```php
use Ykakkaya\YkPos\DTOs\Requests\RefundRequest;

$response = YkPosClient::refund(new RefundRequest(
    customer_ip_address: request()->ip(),
    order_number: 'ORDER-001',
    transaction_id: 'TXN-001',
    refund_amount: 50.00,
    currency: Currency::TRY,
), $auth);
```
Tokens:
Raw