Önemli: Bu paket, PayTR'nin resmi API dokümantasyonuna büyük oranda uyumlu olsa da, bazı fonksiyon ve parametrelerde farklılıklar içerebilir. Özellikle iade tutarı (kuruş/ondalık), BKM Express entegrasyonu ve sepet kodlama gibi konularda detaylı açıklamalar ilgili bölümlerde yer almaktadır. Lütfen entegrasyon öncesi bu uyarıları dikkatlice inceleyin.

PayTR Laravel Client

Laravel projeleri için güvenli, modern ve tam kapsamlı PayTR ödeme entegrasyon paketi.

Neden bu dokümantasyonu kullanmalısınız?

  • En güncel ve kapsamlı kaynak: Tüm PayTR API fonksiyonları, parametreler, hata yönetimi ve testler tek bir yerde, Türkçe ve örneklerle açıklanmıştır.
  • Gerçek dünya senaryoları: Sadece temel entegrasyon değil, kart saklama, link ile ödeme, platform transferi, webhook doğrulama gibi ileri düzey ihtiyaçlarınız için de detaylı rehberlik sunar.
  • Hızlı çözüm ve entegrasyon: Sık karşılaşılan hatalar, güvenlik ipuçları ve best practice'ler ile entegrasyon sürecinizde zamandan tasarruf edin.
  • Modern ve kullanıcı dostu: Koyu mod, responsive tasarım, kopyalanabilir kod blokları ve kolay menü ile aradığınız bilgiye anında ulaşın.
  • Test ve güvenlik odaklı: Tüm fonksiyonlar için test kapsamı ve hata yönetimi örnekleriyle, canlıya çıkmadan önce güvenle uygulamanızı test edin.
  • Topluluk ve açık kaynak desteği: MIT lisansı ile özgürce kullanın, katkı sağlayın veya kendi projenize entegre edin.
Bu dokümantasyon, PayTR ile ödeme alan tüm Laravel projelerinde, ister yeni başlıyor olun ister ileri seviye entegrasyonlar yapıyor olun, size rehberlik etmek için tasarlanmıştır.

  • ✔️ Tüm PayTR API fonksiyonları (ödeme, iade, kart, link, platform, webhook)
  • 🛡️ Gelişmiş güvenlik (HMAC, IP, SSL, signature, .env yönetimi)
  • ⚡ Kolay kurulum & hızlı entegrasyon
  • 🧪 %100 test coverage ve örnek testler
  • 🌙 Koyu mod ve responsive dokümantasyon
  • MIT Lisansı ile tamamen açık kaynak
📄 Kapsamlı Türkçe dokümantasyon:
Bu sayfa, paketin tüm fonksiyonlarını, parametrelerini, hata yönetimini ve testlerini detaylıca açıklar. Çevrimiçi erişim: https://tugrulyildirim.com/opensource/paytr-laravel-client
PayTR Logo

Kurulum

  1. Composer ile paketi yükleyin:
    composer require paytr/laravel-client
  2. Servis sağlayıcı otomatik eklenir. Gerekirse manuel ekleyin:
    // config/app.php
    'providers' => [
        Paytr\PaytrServiceProvider::class,
    ],
  3. Konfigürasyon dosyasını publish edin:
    php artisan vendor:publish --tag=paytr-config
  4. .env dosyasına PayTR bilgilerini ekleyin:
    # PayTR Konfigürasyonu
    PAYTR_MERCHANT_ID=your_merchant_id
    PAYTR_MERCHANT_KEY=your_merchant_key
    PAYTR_MERCHANT_SALT=your_merchant_salt
    PAYTR_SANDBOX=true
    PAYTR_DEBUG=true
    
    # API URL'leri
    PAYTR_API_URL=https://www.paytr.com/odeme/api/
    PAYTR_DIRECT_API_URL=https://www.paytr.com/odeme
    PAYTR_IFRAME_API_URL=https://www.paytr.com/odeme/api/get-token
    
    # Webhook ayarları
    PAYTR_WEBHOOK_SECRET=your_webhook_secret
    PAYTR_ALLOWED_IPS=
ÖNEMLİ: PAYTR_DIRECT_API_URL değeri https://www.paytr.com/odeme olmalıdır. Bu URL, Direct API ödemeleri için kullanılır.

Kullanım

PayTR servislerine facade veya dependency injection ile erişebilirsiniz. Örnekler:

// Facade ile ödeme başlatma
use Paytr\Facades\Paytr;

$result = Paytr::payment()->pay($payload);
// Dependency Injection ile
public function __construct(Paytr\Services\PaymentService $paymentService) {
    $this->paymentService = $paymentService;
}

Direct API vs iFrame API

Özellik Direct API iFrame API
Kart Bilgileri Zorunlu (sunucu tarafında) Gerekmez (kullanıcı PayTR sayfasında girer)
3D Secure Otomatik (kullanıcı banka sayfasına yönlendirilir) Otomatik (iFrame içinde)
Güvenlik Yüksek (kart bilgileri sunucuda işlenir) Yüksek (PayTR'ın güvenli sayfası)
Kullanım Kolaylığı Orta (kart bilgileri toplama gerekir) Kolay (kart bilgileri toplamaya gerek yok)
PCI DSS Gerekli (kart bilgileri işlenir) Gerekmez (kart bilgileri işlenmez)

Ödeme Yapma (pay)

ÖNEMLİ: PayTR Direct API kullanırken kart bilgileri zorunludur. Direct API, kart bilgilerini sunucu tarafında işler ve 3D Secure doğrulaması gerektirir.

pay(array $payload): array fonksiyonu, PayTR Direct API ile ödeme başlatmanızı sağlar. Direct API, kart bilgilerini sunucu tarafında işler ve 3D Secure doğrulaması gerektirir. Tüm zorunlu ve opsiyonel parametreler, dönüş değerleri ve hata yönetimi aşağıda detaylıca açıklanmıştır.

Parametreler

BİLGİ: Aşağıdaki parametreler otomatik olarak config'den alınır: merchant_id, user_ip, test_mode, debug_on, client_lang

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'token' => 'Ödeme tokeni',
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: Temel Ödeme Başlatma (Direct API)

use Paytr\Facades\Paytr;

$payload = [
    // Zorunlu parametreler (otomatik alınır: merchant_id, user_ip, test_mode, debug_on, client_lang)
    'merchant_oid' => 'TEST_' . time(), // Benzersiz sipariş numarası
    'email' => 'user@example.com',
    'payment_amount' => 100.00, // PayTR'de ondalık nokta kullanılır
    'payment_type' => 'card',
    'installment_count' => 0,
    'currency' => 'TL',
    'non_3d' => 0,
    'request_exp_date' => date('Y-m-d H:i:s', strtotime('+1 hour')),

    // Müşteri bilgileri
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',

    // URL'ler (doğru isimlendirme)
    'merchant_ok_url' => 'https://site.com/success',
    'merchant_fail_url' => 'https://site.com/fail',

    // Sepet (PayTR formatında)
    'basket' => [
        ['Test Ürün', '100.00', 1], // [ürün_adı, fiyat, adet]
    ],

    // Direct API için zorunlu kart bilgileri
    'cc_owner' => 'Test Kullanıcı',
    'card_number' => '4355084355084358', // Test kart numarası
    'expiry_month' => '12',
    'expiry_year' => '25',
    'cvv' => '000',

    // Opsiyonel parametreler
    'lang' => 'tr',
    'sync_mode' => 0, // 0: async, 1: sync
    'non3d_test_failed' => 0,
    'card_type' => '', // Boş bırakılabilir
];

try {
    $result = Paytr::payment()->pay($payload);
    // $result['token'] ile ödeme başlatılır
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Örnek: Taksitli Ödeme

$payload['installment_count'] = 3; // 3 taksit
$result = Paytr::payment()->pay($payload);

Örnek: Farklı Para Birimi ile Ödeme

$payload['currency'] = 'USD';
$result = Paytr::payment()->pay($payload);

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->pay($payload);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

iFrame ile Ödeme (createIframeToken)

BİLGİ: iFrame API kullanırken kart bilgileri gerekmez. Kullanıcı PayTR'ın güvenli ödeme sayfasında kart bilgilerini girer.

createIframeToken(array $payload): array fonksiyonu, PayTR iFrame API ile ödeme başlatmak için gerekli token'ı üretir. Bu token ile iFrame ödeme formunu sitenize kolayca entegre edebilirsiniz. iFrame API'de kart bilgileri kullanıcı tarafından PayTR'ın güvenli sayfasında girilir.

Parametreler

BİLGİ: Aşağıdaki parametreler otomatik olarak config'den alınır: merchant_id, user_ip, test_mode, debug_on, lang

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'token' => 'iFrame token',
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: iFrame ile Ödeme Token'ı Alma

use Paytr\Facades\Paytr;

$payload = [
    // Zorunlu parametreler (otomatik alınır: merchant_id, user_ip, test_mode, debug_on, lang)
    'merchant_oid' => 'TEST_' . time(), // Benzersiz sipariş numarası
    'email' => 'user@example.com',
    'payment_amount' => 100.00, // PayTR'de ondalık nokta kullanılır
    'currency' => 'TL',

    // Müşteri bilgileri
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',

    // URL'ler (doğru isimlendirme)
    'merchant_ok_url' => 'https://site.com/success',
    'merchant_fail_url' => 'https://site.com/fail',

    // Sepet (PayTR formatında)
    'basket' => [
        ['Test Ürün', '100.00', 1], // [ürün_adı, fiyat, adet]
    ],

    // Opsiyonel parametreler
    'no_installment' => 0, // Taksit kullan
    'max_installment' => 12, // Maksimum 12 taksit
    'timeout_limit' => 0, // Zaman aşımı yok
    // iFrame API'de kart bilgileri gerekmez
];

try {
    $result = Paytr::payment()->createIframeToken($payload);
    // $result['token'] ile iFrame formu oluşturulabilir
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Örnek: iFrame Formunun Entegrasyonu


Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->createIframeToken($payload);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

Ödeme Durumu Sorgulama (getPaymentStatus)

getPaymentStatus(string $merchantOid): array fonksiyonu, belirli bir siparişin (merchant_oid) ödeme durumunu PayTR API üzerinden sorgular.

Parametreler

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'payment_status' => 'paid', // veya 'pending', 'failed' vb.
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: Ödeme Durumu Sorgulama

use Paytr\Facades\Paytr;

$merchantOid = 'ORDER123';

try {
    $result = Paytr::payment()->getPaymentStatus($merchantOid);
    if ($result['payment_status'] === 'paid') {
        // Ödeme başarılı
    } elseif ($result['payment_status'] === 'pending') {
        // Ödeme beklemede
    } else {
        // Ödeme başarısız veya iptal
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->getPaymentStatus($merchantOid);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

Taksit Oranları Sorgulama (getInstallmentRates)

getInstallmentRates(string $bin): array fonksiyonu, verilen kart BIN numarasına göre taksit oranlarını PayTR API üzerinden sorgular.

Parametreler

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'installment_rates' => [
    ['count' => 1, 'rate' => 0],
    ['count' => 2, 'rate' => 1.5],
    // ...
  ],
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: Taksit Oranları Sorgulama

use Paytr\Facades\Paytr;

$bin = '454360';

try {
    $result = Paytr::payment()->getInstallmentRates($bin);
    foreach ($result['installment_rates'] as $rate) {
        echo $rate['count'] . ' taksit: ' . $rate['rate'] . "% oran\n";
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->getInstallmentRates($bin);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

BIN Sorgulama (lookupBin)

lookupBin(string $bin): array fonksiyonu, verilen kart BIN numarasına (ilk 6 hane) göre kartın ait olduğu banka, kart tipi ve diğer bilgileri PayTR API üzerinden sorgular.

Parametreler

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'bank' => 'Banka Adı',
  'card_type' => 'Kredi Kartı',
  'brand' => 'Visa',
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: BIN Sorgulama

use Paytr\Facades\Paytr;

$bin = '454360';

try {
    $result = Paytr::payment()->lookupBin($bin);
    echo 'Banka: ' . $result['bank'] . "\n";
    echo 'Kart Tipi: ' . $result['card_type'] . "\n";
    echo 'Marka: ' . $result['brand'] . "\n";
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->lookupBin($bin);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

İşlem Detayı Sorgulama (getTransactionDetail)

getTransactionDetail(string $merchantOid): array fonksiyonu, belirli bir siparişin (merchant_oid) işlem detaylarını PayTR API üzerinden sorgular.

Parametreler

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'transaction' => [
    'amount' => 10000,
    'status' => 'paid',
    'date' => '2024-01-01 12:00:00',
    // ... diğer işlem detayları
  ],
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: İşlem Detayı Sorgulama

use Paytr\Facades\Paytr;

$merchantOid = 'ORDER123';

try {
    $result = Paytr::payment()->getTransactionDetail($merchantOid);
    $transaction = $result['transaction'];
    echo 'Tutar: ' . $transaction['amount'] . "\n";
    echo 'Durum: ' . $transaction['status'] . "\n";
    echo 'Tarih: ' . $transaction['date'] . "\n";
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->getTransactionDetail($merchantOid);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

Ödeme Raporu Sorgulama (getPaymentStatement)

getPaymentStatement(array $payload): array fonksiyonu, belirli bir tarih aralığı için ödeme raporunu (statement) PayTR API üzerinden sorgular.

Parametreler

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'payments' => [
    [
      'merchant_oid' => 'ORDER123',
      'amount' => 10000,
      'status' => 'paid',
      'date' => '2024-01-01 12:00:00',
      // ... diğer ödeme detayları
    ],
    // ...
  ],
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: Ödeme Raporu Sorgulama

use Paytr\Facades\Paytr;

$payload = [
    'date_start' => '2024-01-01',
    'date_end' => '2024-01-31',
];

try {
    $result = Paytr::payment()->getPaymentStatement($payload);
    foreach ($result['payments'] as $payment) {
        echo $payment['merchant_oid'] . ': ' . $payment['amount'] . ' TL - ' . $payment['status'] . "\n";
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->getPaymentStatement($payload);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

Ödeme Detayı Sorgulama (getPaymentDetail)

getPaymentDetail(string $paymentId): array fonksiyonu, belirli bir ödeme ID'sine ait detayları PayTR API üzerinden sorgular.

Parametreler

Dönüş Değeri

Başarılı işlemde aşağıdaki gibi bir dizi döner:

[
  'status' => 'success',
  'payment' => [
    'merchant_oid' => 'ORDER123',
    'amount' => 10000,
    'status' => 'paid',
    'date' => '2024-01-01 12:00:00',
    // ... diğer ödeme detayları
  ],
  // Diğer PayTR yanıt parametreleri
]

Başarısız işlemde PaytrException fırlatılır ve hata mesajı döner.

Örnek: Ödeme Detayı Sorgulama

use Paytr\Facades\Paytr;

$paymentId = '12345';

try {
    $result = Paytr::payment()->getPaymentDetail($paymentId);
    $payment = $result['payment'];
    echo 'Sipariş: ' . $payment['merchant_oid'] . "\n";
    echo 'Tutar: ' . $payment['amount'] . "\n";
    echo 'Durum: ' . $payment['status'] . "\n";
    echo 'Tarih: ' . $payment['date'] . "\n";
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Hata Yönetimi

API veya validasyon hatalarında PaytrException fırlatılır. Hata mesajı ve kodu exception üzerinden alınabilir.

try {
    $result = Paytr::payment()->getPaymentDetail($paymentId);
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata mesajı: $e->getMessage()
    // Hata kodu: $e->getCode()
}

Ek Notlar

Ön Provizyon (preProvision)

preProvision(array $payload): array fonksiyonu, ön provizyon (pre-auth) işlemi başlatmak için kullanılır. Karttan tutar çekilmeden önce provizyon alınmasını sağlar.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'token' => 'Provizyon tokeni',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Ön Provizyon Başlatma

$payload = [
    'merchant_oid' => 'ORDER123',
    'email' => 'user@example.com',
    'payment_amount' => 10000,
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',
    'user_ip' => request()->ip(),
    'basket' => [
        ['name' => 'Ürün', 'price' => 10000, 'quantity' => 1],
    ],
];
$result = Paytr::payment()->preProvision($payload);

EFT iFrame (createEftIframe)

createEftIframe(array $payload): array fonksiyonu, EFT ile ödeme için iFrame token'ı oluşturur.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'token' => 'EFT iFrame token',
  // Diğer PayTR yanıt parametreleri
]

Örnek: EFT iFrame Token Alma

$payload = [
    'merchant_oid' => 'ORDER123',
    'email' => 'user@example.com',
    'payment_amount' => 10000,
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',
    'user_ip' => request()->ip(),
    'basket' => [
        ['name' => 'Ürün', 'price' => 10000, 'quantity' => 1],
    ],
];
$result = Paytr::payment()->createEftIframe($payload);

BKM Express ile Ödeme (payWithBkmExpress)

UYARI: Bu paket, BKM Express ödemeleri için PayTR'nin resmi API'sinden farklı olarak ayrı bir bkm/express endpoint'i kullanır. payment_type="bex" parametresi gerekmez. Entegrasyonun kolaylaştırılması için bu yol tercih edilmiştir.

payWithBkmExpress(array $payload): array fonksiyonu, BKM Express ile ödeme başlatmak için kullanılır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'token' => 'BKM Express token',
  // Diğer PayTR yanıt parametreleri
]

Örnek: BKM Express ile Ödeme Başlatma

$payload = [
    'merchant_oid' => 'ORDER123',
    'email' => 'user@example.com',
    'payment_amount' => 10000,
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',
    'user_ip' => request()->ip(),
    'basket' => [
        ['name' => 'Ürün', 'price' => 10000, 'quantity' => 1],
    ],
];
$result = Paytr::payment()->payWithBkmExpress($payload);

Sepet Kodlama (encodeBasket)

encodeBasket(array $basket): string fonksiyonu, sepet verilerini PayTR API'nin beklediği formatta kodlar.

PayTR Sepet Formatı

BİLGİ: PayTR API'de sepet verisi özel formatta gönderilmelidir: [['Ürün Adı', 'Fiyat', 'Adet'], ...]
Not: encodeBasket metodu doğrudan çağrılamaz. Bu metot protected olarak tanımlıdır ve genellikle ödeme işlemleri sırasında paket tarafından otomatik olarak kullanılır.

Parametreler

Dönüş Değeri

Base64 ile kodlanmış sepet verisi döner.

Örnek: Sepet Kodlama

Not: Sepet kodlama işlemi ödeme fonksiyonları tarafından otomatik olarak yapılır. Kendi kodunuzda kullanmak isterseniz, aşağıdaki gibi bir yardımcı fonksiyon yazabilirsiniz:
// PayTR Sepet Formatı: [['Ürün Adı', 'Fiyat', 'Adet'], ...]
$basket = [
    ['Test Ürün 1', '100.00', 1],     // [ürün_adı, fiyat, adet]
    ['Test Ürün 2', '50.50', 2],      // [ürün_adı, fiyat, adet]
    ['Test Ürün 3', '25.25', 3],      // [ürün_adı, fiyat, adet]
];

function encodeBasket(array $basket): string {
    return base64_encode(json_encode($basket));
}

$encoded = encodeBasket($basket);

Desteklenen Formatlar

// 1. PayTR Formatı (Önerilen)
$basket = [
    ['Ürün Adı', '100.00', 1],
];

// 2. Obje Formatı (Otomatik dönüştürülür)
$basket = [
    ['name' => 'Ürün Adı', 'price' => 100.00, 'quantity' => 1],
];

// 3. Karma Format
$basket = [
    ['Ürün 1', '100.00', 1],
    ['name' => 'Ürün 2', 'price' => 50.00, 'quantity' => 2],
];

Ek Notlar

İade (refund)

UYARI: Bu paket, iade tutarını kuruş (integer) cinsinden işler. Yani 10 TL için 1000 yazılmalıdır. PayTR'nin resmi API'sinde ise return_amount parametresi ondalık string (ör: "10.00") olarak gönderilir. Lütfen bu farklılığa dikkat edin.

refund(string $merchantOid): array fonksiyonu, bir ödemenin tamamının iadesini başlatır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Tam İade

use Paytr\Facades\Paytr;

$merchantOid = 'ORDER123';

try {
    $result = Paytr::refund()->refund($merchantOid);
    // İade başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Kısmi İade (partialRefund)

UYARI: Bu paket, kısmi iade tutarını kuruş (integer) cinsinden işler. Yani 10 TL için 1000 yazılmalıdır. PayTR'nin resmi API'sinde ise return_amount parametresi ondalık string (ör: "10.00") olarak gönderilir. Lütfen bu farklılığa dikkat edin.

partialRefund(string $merchantOid, int $amount): array fonksiyonu, bir ödemenin belirli bir tutarının iadesini başlatır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Kısmi İade

$merchantOid = 'ORDER123';
$amount = 5000; // 50 TL

try {
    $result = Paytr::refund()->partialRefund($merchantOid, $amount);
    // Kısmi iade başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

İade Durumu Sorgulama (getRefundStatus)

getRefundStatus(string $merchantOid): array fonksiyonu, bir iade işleminin güncel durumunu sorgular.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'refund_status' => 'completed', // veya 'pending', 'failed' vb.
  // Diğer PayTR yanıt parametreleri
]

Örnek: İade Durumu Sorgulama

$merchantOid = 'ORDER123';

try {
    $result = Paytr::refund()->getRefundStatus($merchantOid);
    if ($result['refund_status'] === 'completed') {
        // İade tamamlandı
    } elseif ($result['refund_status'] === 'pending') {
        // İade beklemede
    } else {
        // İade başarısız veya iptal
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

İptal (cancel)

cancel(string $merchantOid): array fonksiyonu, bir ödemenin tamamının iptalini başlatır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Tam İptal

use Paytr\Facades\Paytr;

$merchantOid = 'ORDER123';

try {
    $result = Paytr::cancel()->cancel($merchantOid);
    // İptal başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Kısmi İptal (partialCancel)

partialCancel(string $merchantOid, int $amount): array fonksiyonu, bir ödemenin belirli bir tutarının iptalini başlatır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Kısmi İptal

$merchantOid = 'ORDER123';
$amount = 5000; // 50 TL

try {
    $result = Paytr::cancel()->partialCancel($merchantOid, $amount);
    // Kısmi iptal başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    // Hata yönetimi
    echo $e->getMessage();
}

Kart Kaydet (storeCard)

storeCard(array $cardData): array fonksiyonu, kullanıcının kart bilgisini güvenli şekilde PayTR sistemine kaydeder.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'token' => 'Kart tokeni',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Kart Kaydetme

$cardData = [
    'customer_id' => 'USER123',
    'cc_owner' => 'Test Kullanıcı',
    'card_number' => '4111111111111111',
    'expiry_month' => '12',
    'expiry_year' => '25',
    'cvv' => '123',
];

try {
    $result = Paytr::card()->storeCard($cardData);
    // $result['token'] ile kayıtlı kart işlemleri yapılabilir
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Kart ile Ödeme (payWithCard)

payWithCard(string $token, array $paymentData): array fonksiyonu, kayıtlı kart ile ödeme başlatır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Kayıtlı Kart ile Ödeme

$token = 'KART_TOKEN';
$paymentData = [
    'amount' => 10000,
    'merchant_oid' => 'ORDER123',
];

try {
    $result = Paytr::card()->payWithCard($token, $paymentData);
    // Ödeme başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Tekrarlayan Ödeme (recurringPayment)

recurringPayment(string $token, array $paymentData): array fonksiyonu, kayıtlı kart ile tekrarlayan ödeme başlatır.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Tekrarlayan Ödeme

$token = 'KART_TOKEN';
$paymentData = [
    'amount' => 10000,
    'merchant_oid' => 'ORDER123',
];

try {
    $result = Paytr::card()->recurringPayment($token, $paymentData);
    // Ödeme başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Kartları Listele (listCards)

listCards(string $customerId): array fonksiyonu, bir kullanıcıya ait kayıtlı kartları listeler.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'cards' => [
    [
      'token' => 'KART_TOKEN',
      'cc_owner' => 'Test Kullanıcı',
      // ... diğer kart bilgileri
    ],
    // ...
  ],
  // Diğer PayTR yanıt parametreleri
]

Örnek: Kartları Listeleme

$customerId = 'USER123';

try {
    $result = Paytr::card()->listCards($customerId);
    foreach ($result['cards'] as $card) {
        echo $card['cc_owner'] . ' - ' . $card['token'] . "\n";
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Kart Sil (deleteCard)

deleteCard(string $token): array fonksiyonu, kayıtlı bir kartı siler.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Kart Silme

$token = 'KART_TOKEN';

try {
    $result = Paytr::card()->deleteCard($token);
    // Silme başarılı ise $result['status'] == 'success'
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Servisler

Kütüphane aşağıdaki ana servisleri sunar:

Örnek: iFrame ile ödeme başlatma

$payload = [
    'merchant_oid' => 'ORDER123',
    'email' => 'user@example.com',
    'amount' => 10000,
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',
    'ok_url' => 'https://site.com/success',
    'fail_url' => 'https://site.com/fail',
    'basket' => [
        ['name' => 'Ürün', 'price' => 10000, 'quantity' => 1],
    ],
];
$result = Paytr::payment()->createIframeToken($payload);

Örnek: İade işlemi

$result = Paytr::refund()->refund('ORDER123');

Eventler

// Event dinleme örneği
Event::listen(Paytr\Events\PaymentSuccessEvent::class, function($event) {
    // $event->data ile işlem detaylarına erişebilirsiniz
});

Middleware

paytr.signature middleware'i, webhook endpoint'lerinde imza doğrulaması yapar.

Route::post('/webhook', [WebhookController::class, 'handle'])
    ->middleware('paytr.signature');

Testler

Kütüphane, unit ve feature testleriyle kapsamlı şekilde test edilmiştir. Testler, eventlerin veri taşıma işlevinden, servislerin imza üretimine ve middleware doğrulamasına kadar tüm kritik noktaları kapsar.

Platform Transfer Oluştur (createTransfer)

createTransfer(array $payload): array fonksiyonu, platform üzerinden transfer talebi oluşturur.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'transfer_id' => 'TRF123',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Platform Transfer Oluşturma

$payload = [
    'amount' => 10000,
    'iban' => 'TR000000000000000000000000',
    'description' => 'Açıklama',
];

try {
    $result = Paytr::platform()->createTransfer($payload);
    // $result['transfer_id'] ile transfer işlemi takip edilebilir
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Platform Transfer Sonucu (getTransferResult)

getTransferResult(string $transferId): array fonksiyonu, platform transferinin sonucunu sorgular.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'result' => 'completed', // veya 'pending', 'failed' vb.
  // Diğer PayTR yanıt parametreleri
]

Örnek: Platform Transfer Sonucu Sorgulama

$transferId = 'TRF123';

try {
    $result = Paytr::platform()->getTransferResult($transferId);
    if ($result['result'] === 'completed') {
        // Transfer tamamlandı
    } elseif ($result['result'] === 'pending') {
        // Transfer beklemede
    } else {
        // Transfer başarısız
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Platform İade Listesi (getReturningPayments)

getReturningPayments(array $payload): array fonksiyonu, belirli bir tarih aralığında iade edilen ödemeleri listeler.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  'returning_payments' => [
    [
      'trans_id' => 'TRS123',
      'amount' => 10000,
      'iban' => 'TR000000000000000000000000',
      // ... diğer bilgiler
    ],
    // ...
  ],
  // Diğer PayTR yanıt parametreleri
]

Örnek: Platform İade Listesi Sorgulama

$payload = [
    'date_start' => '2024-01-01',
    'date_end' => '2024-01-31',
];

try {
    $result = Paytr::platform()->getReturningPayments($payload);
    foreach ($result['returning_payments'] as $payment) {
        echo $payment['trans_id'] . ': ' . $payment['amount'] . "\n";
    }
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Platform İade Gönder (sendReturningPayment)

sendReturningPayment(array $payload): array fonksiyonu, hesaptan iade ödemesi gönderir.

Parametreler

Dönüş Değeri

[
  'status' => 'success',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Platform İade Gönderme

$payload = [
    'trans_id' => 'TRS123',
    'amount' => 10000,
    'iban' => 'TR000000000000000000000000',
    'name' => 'Alıcı Adı',
];

try {
    $result = Paytr::platform()->sendReturningPayment($payload);
    // $result['status'] == 'success' ise iade gönderildi
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Platform Callback İşle (handleReturningCallback)

handleReturningCallback(array $payload): array fonksiyonu, gelen iade bildirimini işler ve doğrular.

Parametreler

Dönüş Değeri

$result = Paytr::platform()->handleReturningCallback($payload);
// $result: iade edilen işlemler dizisi

Örnek: Callback İşleme

$payload = [...];

try {
    $result = Paytr::platform()->handleReturningCallback($payload);
    // $result ile iade edilen işlemler işlenebilir
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Platform Callback Doğrulama (verifyCallback)

verifyCallback(array $payload, string $signature): bool fonksiyonu, platform transfer callback isteğinin imzasını doğrular.

Parametreler

Dönüş Değeri

$isValid = Paytr::platform()->verifyCallback($payload, $signature);
// $isValid: true veya false

Örnek: Callback Doğrulama

$payload = [...];
$signature = $_SERVER['HTTP_X_PAYTR_SIGNATURE'] ?? '';

$isValid = Paytr::platform()->verifyCallback($payload, $signature);
if ($isValid) {
    // Callback geçerli
} else {
    // Geçersiz imza
}

PaymentSuccessEvent

Başarılı bir ödeme işlemi gerçekleştiğinde tetiklenen eventtir.

Tetiklenme Durumu

Veri Yapısı

$event->data = [
  'event' => 'payment_success',
  'merchant_oid' => 'ORDER123',
  'amount' => 10000,
  // ... diğer alanlar
];

Örnek: Event Dinleme

Event::listen(Paytr\Events\PaymentSuccessEvent::class, function($event) {
    // $event->data ile işlem detaylarına erişebilirsiniz
});

PaymentFailedEvent

Başarısız bir ödeme işlemi gerçekleştiğinde tetiklenen eventtir.

Tetiklenme Durumu

Veri Yapısı

$event->data = [
  'event' => 'payment_failed',
  'merchant_oid' => 'ORDER123',
  'reason' => 'Insufficient funds',
  // ... diğer alanlar
];

Örnek: Event Dinleme

Event::listen(Paytr\Events\PaymentFailedEvent::class, function($event) {
    // $event->data ile hata detaylarına erişebilirsiniz
});

RefundSuccessEvent

Başarılı bir iade işlemi gerçekleştiğinde tetiklenen eventtir.

Tetiklenme Durumu

Veri Yapısı

$event->data = [
  'event' => 'refund_success',
  'merchant_oid' => 'ORDER123',
  'refund_amount' => 5000,
  // ... diğer alanlar
];

Örnek: Event Dinleme

Event::listen(Paytr\Events\RefundSuccessEvent::class, function($event) {
    // $event->data ile iade detaylarına erişebilirsiniz
});

paytr.signature Middleware

Webhook endpoint'lerinde gelen isteğin imzasını doğrulayan middleware'dir.

Kullanım

Route::post('/webhook', [WebhookController::class, 'handle'])
    ->middleware('paytr.signature');

Çalışma Prensibi

Örnek: Hatalı İmza

curl -X POST /webhook -H "X-PayTR-Signature: yanlis" -d '{...}'

WebhookController

PayTR tarafından gönderilen webhook bildirimlerini işler. IP ve signature doğrulaması yapar, ilgili event'i tetikler.

Örnek Route

Route::post('/webhook', [WebhookController::class, 'handle'])
    ->middleware('paytr.signature');

Çalışma Prensibi

Örnek: Webhook Payload

{
  "event": "payment_success",
  "merchant_oid": "ORDER123",
  "amount": 10000,
  // ... diğer alanlar
}

Testler (Detaylı)

Kütüphane, unit ve feature testleriyle kapsamlı şekilde test edilmiştir. Her bir testin amacı, kapsamı ve örnek assertion'lar aşağıda özetlenmiştir.

Örnek: Test Assertion

$this->assertEquals($data, $event->data);
$response->assertStatus(500);
$this->assertArrayHasKey('paytr_token', $params);