README

TrinkPOS Sanal POS (Virtual POS) API'si için resmi PHP istemci kütüphanesi.

Durum: v0.x — API yüzeyi WooCommerce eklentisi entegrasyonu tamamlanana kadar değişebilir. 1.0.0 ile SemVer garantisi başlar.

Gereksinimler

• PHP 8.1+
• ext-curl, ext-json
• Sıfır üçüncü parti runtime bağımlılığı

Kurulum

Composer (önerilen)

composer require pratikislem/trinkpos-php

Composer olmadan

Repoyu indirip bootstrap dosyasını dahil edin:

require '/path/to/trinkpos-php/TrinkposBootstrap.php';
TrinkposBootstrap::init();

Hızlı başlangıç

use Trinkpos\Enum\Currency;
use Trinkpos\Enum\TransactionType;
use Trinkpos\Options;
use Trinkpos\Request\PaymentRequest;
use Trinkpos\TrinkposClient;

$client = new TrinkposClient(Options::sandbox('API_KEY', 'SECRET_KEY'));
// Canlı ortam: Options::production('API_KEY', 'SECRET_KEY')

$response = $client->payment(new PaymentRequest(
    transactionType: TransactionType::Auth,
    orderId: 'ORDER-12345',
    amount: 100.00,
    currency: Currency::TRY,
    cardNumber: '4000000000000001',
    cardHolderName: 'John Doe',
    expYear: 2030,
    expMonth: 12,
    cvv: '000',
    installment: 1,
    is3d: false,
));

if ($response->isApproved()) {
    echo $response->transactionId();
}

Daha fazla örnek: samples/ — NonSecure satış, 3D akışı ve tüm endpoint'leri gezen samples/sandbox-smoke.php.

3D Secure akışı

// 1) Başlat: is3d: true, okUrl/failUrl verin → müşteriyi yönlendirin.
$response = $client->payment($request3d);
header('Location: ' . $response->htmlUrl()); // 15 dakika geçerli

// 2) Banka, ok_url/fail_url'e form POST'u yapar:
$callback = \Trinkpos\ThreeD\CallbackResult::fromPost($_POST);

// 3) ⚠️ Callback İMZASIZDIR — tek başına asla güvenmeyin.
//    Onay kararını daima sunucudan-sunucuya doğrulamayla verin:
$verification = $client->verifyCallback($callback);
if ($verification->isApproved() && $callback->amountMatches($orderAmount)) {
    // siparişi onayla
}

Hata modeli

İki katman vardır; ikisini karıştırmayın:

use Trinkpos\Enum\ErrorSubCodes;
use Trinkpos\Enum\GatewayCodes;
use Trinkpos\Exception\ApiException;

try {
    $response = $client->payment($request);
    if (!$response->isApproved()) {
        // Banka reddi: '51' yetersiz bakiye, '54' süresi dolmuş kart…
        $code = $response->gatewayCode();        // GatewayCodes sabitleriyle karşılaştırın
        $mesaj = $response->gatewayMessageTr();  // veya gatewayMessageEn()
    }
} catch (ApiException $e) {
    if ($e->errorSubCode === ErrorSubCodes::DUPLICATE_ORDER_ID) {
        // sipariş no zaten kullanılmış
    }
}

Desteklenen operasyonlar

Sandbox

make smoke   # sandbox'a karşı uçtan uca duman testi

Geliştirme

make install   # composer install
make test      # phpunit
make lint      # php -l

Lisans

MIT — bkz. LICENSE.