Kurulum

1. Composer ile paketi yükleyin:
   kopyala

   composer require paytr/laravel-client

2. Servis sağlayıcı otomatik eklenir. Gerekirse manuel ekleyin:
   kopyala

   // config/app.php
   'providers' => [
       Paytr\PaytrServiceProvider::class,
   ],

3. Konfigürasyon dosyasını publish edin:
   kopyala

   php artisan vendor:publish --tag=paytr-config

4. .env dosyasına PayTR bilgilerini ekleyin:
   kopyala

   # 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 (Güncel PayTR API Uç Noktaları)
   PAYTR_DIRECT_API_URL=https://www.paytr.com/odeme
   PAYTR_IFRAME_API_URL=https://www.paytr.com/odeme/api/get-token
   PAYTR_REFUND_API_URL=https://www.paytr.com/odeme/iade
   PAYTR_STATUS_API_URL=https://www.paytr.com/odeme/durum-sorgu
   
   # Webhook ayarları
   PAYTR_WEBHOOK_SECRET=your_webhook_secret
   PAYTR_ALLOWED_IPS=

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

Ödeme Yapma (pay)

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

• merchant_oid (string, zorunlu): Siparişe özel benzersiz ID.
• email (string, zorunlu): Kullanıcı e-posta adresi.
• payment_amount (float, zorunlu): Ödeme tutarı (ondalık nokta ile, örn: 100.00 = 100 TL).
• payment_type (string, zorunlu): Ödeme tipi (varsayılan: 'card').
• installment_count (int, zorunlu): Taksit sayısı (varsayılan: 0).
• currency (string, zorunlu): Para birimi (varsayılan: TL).
• non_3d (int, zorunlu): 3D Secure kullanımı (0: kullan, 1: kullanma).
• request_exp_date (string, zorunlu): İstek son kullanma tarihi (Y-m-d H:i:s formatında).
• user_name (string, zorunlu): Kullanıcı adı.
• user_address (string, zorunlu): Kullanıcı adresi.
• user_phone (string, zorunlu): Kullanıcı telefon numarası.
• merchant_ok_url (string, zorunlu): Başarılı ödeme sonrası yönlendirilecek URL.
• merchant_fail_url (string, zorunlu): Başarısız ödeme sonrası yönlendirilecek URL.
• basket (array, zorunlu): Sepet içeriği. PayTR formatında: [['Ürün Adı', '100.00', 1]]
• cc_owner (string, zorunlu): Kart sahibi adı.
• card_number (string, zorunlu): Kart numarası (16 hane).
• expiry_month (string, zorunlu): Son kullanma ayı (MM formatında, örn: "12").
• expiry_year (string, zorunlu): Son kullanma yılı (YY formatında, örn: "25").
• cvv (string, zorunlu): Kart güvenlik kodu (3-4 hane).
• lang (string, opsiyonel): Dil (varsayılan: tr).
• sync_mode (int, opsiyonel): Senkron modu (0: async, 1: sync).
• non3d_test_failed (int, opsiyonel): Test modunda başarısız işlem (0: normal, 1: başarısız test).
• card_type (string, opsiyonel): Kart tipi (bonus, axess, combo, vb.).
• timeout_limit (int, opsiyonel): Zaman aşımı süresi (saniye).

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

• Direct API için kart bilgileri zorunludur ve sunucu tarafında işlenir.
• Direct API 3D Secure doğrulaması gerektirir, kullanıcı banka sayfasına yönlendirilir.
• Sepet içeriği base64_encode(json_encode(...)) ile otomatik olarak kodlanır.
• Güvenlik için tüm isteklerde imza (signature) zorunludur, kütüphane bunu otomatik olarak üretir.
• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• Test kartları: 4355084355084358 (son kullanma: 12/25, CVV: 000)

iFrame ile Ödeme (createIframeToken)

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

• merchant_oid (string, zorunlu): Siparişe özel benzersiz ID.
• email (string, zorunlu): Kullanıcı e-posta adresi.
• payment_amount (float, zorunlu): Ödeme tutarı (ondalık nokta ile, örn: 100.00 = 100 TL).
• currency (string, zorunlu): Para birimi (varsayılan: TL).
• user_name (string, zorunlu): Kullanıcı adı.
• user_address (string, zorunlu): Kullanıcı adresi.
• user_phone (string, zorunlu): Kullanıcı telefon numarası.
• merchant_ok_url (string, zorunlu): Başarılı ödeme sonrası yönlendirilecek URL.
• merchant_fail_url (string, zorunlu): Başarısız ödeme sonrası yönlendirilecek URL.
• basket (array, zorunlu): Sepet içeriği. PayTR formatında: [['Ürün Adı', '100.00', 1]]
• no_installment (int, opsiyonel): Taksit kullanımı (0: kullan, 1: kullanma).
• max_installment (int, opsiyonel): Maksimum taksit sayısı.
• timeout_limit (int, opsiyonel): Zaman aşımı süresi (saniye).

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

• iFrame API'de kart bilgileri gerekmez, kullanıcı PayTR'ın güvenli sayfasında kart bilgilerini girer.
• iFrame token'ı yalnızca sunucu tarafında alınmalıdır, güvenlik için istemciye gizli anahtarlar gönderilmemelidir.
• iFrame API, kullanıcıyı sitenizden çıkarmadan güvenli ödeme yapmanızı sağlar.
• Sepet içeriği base64_encode(json_encode(...)) ile otomatik olarak kodlanır.
• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.

Ödeme Durumu Sorgulama (getPaymentStatus)

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

Parametreler

• merchantOid (string, zorunlu): Sorgulanacak siparişin benzersiz ID'si.

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

• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• payment_status alanı 'paid', 'pending', 'failed', 'cancelled' gibi değerler alabilir.

Taksit Oranları Sorgulama (getInstallmentRates)

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

Parametreler

• bin (string, zorunlu): Kartın ilk 6 hanesi (BIN numarası).

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

• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• installment_rates dizisi, her taksit seçeneği için oranları içerir.

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

• bin (string, zorunlu): Kartın ilk 6 hanesi (BIN numarası).

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

• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• BIN sorgusu ile kartın ait olduğu banka, kart tipi, marka gibi bilgiler alınabilir.

İşlem Detayı Sorgulama (getTransactionDetail)

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

Parametreler

• merchantOid (string, zorunlu): Sorgulanacak siparişin benzersiz ID'si.

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

• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• transaction dizisi, işlemle ilgili tüm detayları içerir.

Ödeme Raporu Sorgulama (getPaymentStatement)

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

Parametreler

• date_start (string, zorunlu): Başlangıç tarihi (YYYY-MM-DD).
• date_end (string, zorunlu): Bitiş tarihi (YYYY-MM-DD).

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

• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• payments dizisi, ilgili tarih aralığındaki tüm ödemeleri içerir.

Ödeme Detayı Sorgulama (getPaymentDetail)

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

Parametreler

• paymentId (string, zorunlu): Sorgulanacak ödemenin benzersiz ID'si.

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

• Yanıtta status alanı 'success' değilse, hata olarak değerlendirilir.
• payment dizisi, ödeme ile ilgili tüm detayları içerir.

Ö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

• merchant_oid (string, zorunlu): Siparişe özel benzersiz ID.
• email (string, zorunlu): Kullanıcı e-posta adresi.
• payment_amount (int, zorunlu): Provizyon tutarı (Kuruş cinsinden).
• user_name (string, zorunlu): Kullanıcı adı.
• user_address (string, zorunlu): Kullanıcı adresi.
• user_phone (string, zorunlu): Kullanıcı telefon numarası.
• user_ip (string, zorunlu): Kullanıcı IP adresi.
• basket (array, zorunlu): Sepet içeriği.
• diğer opsiyonel parametreler: PayTR API dokümantasyonuna göre eklenebilir.

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

• merchant_oid (string, zorunlu): Siparişe özel benzersiz ID.
• email (string, zorunlu): Kullanıcı e-posta adresi.
• payment_amount (int, zorunlu): Ödeme tutarı (Kuruş cinsinden).
• user_name (string, zorunlu): Kullanıcı adı.
• user_address (string, zorunlu): Kullanıcı adresi.
• user_phone (string, zorunlu): Kullanıcı telefon numarası.
• user_ip (string, zorunlu): Kullanıcı IP adresi.
• basket (array, zorunlu): Sepet içeriği.
• diğer opsiyonel parametreler: PayTR API dokümantasyonuna göre eklenebilir.

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)

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

Parametreler

• merchant_oid (string, zorunlu): Siparişe özel benzersiz ID.
• email (string, zorunlu): Kullanıcı e-posta adresi.
• payment_amount (int, zorunlu): Ödeme tutarı (Kuruş cinsinden).
• user_name (string, zorunlu): Kullanıcı adı.
• user_address (string, zorunlu): Kullanıcı adresi.
• user_phone (string, zorunlu): Kullanıcı telefon numarası.
• user_ip (string, zorunlu): Kullanıcı IP adresi.
• basket (array, zorunlu): Sepet içeriği.
• diğer opsiyonel parametreler: PayTR API dokümantasyonuna göre eklenebilir.

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ı

Parametreler

• basket (array, zorunlu): Sepet içeriği. PayTR formatında: [['Ürün Adı', '100.00', 1]]

Dönüş Değeri

Base64 ile kodlanmış sepet verisi döner.

Örnek: Sepet Kodlama

// 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

• Sepet verisi base64_encode(json_encode(...)) ile otomatik kodlanır.
• PayTR API, kodlanmış sepet verisini bekler.
• Sepet içeriği, ödeme tutarı ile uyumlu olmalıdır.
• Fiyatlar ondalık nokta (.) ile gösterilmelidir.
• Paket otomatik olarak farklı formatları PayTR formatına dönüştürür.

İade (refund)

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

Parametreler

• merchantOid (string, zorunlu): İadesi yapılacak siparişin benzersiz ID'si.

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)

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

Parametreler

• merchantOid (string, zorunlu): İadesi yapılacak siparişin benzersiz ID'si.
• amount (int, zorunlu): İade edilecek tutar (Kuruş cinsinden).

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

• merchantOid (string, zorunlu): Sorgulanacak iade işleminin sipariş ID'si.

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

• merchantOid (string, zorunlu): İptal edilecek siparişin benzersiz ID'si.

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

• merchantOid (string, zorunlu): İptal edilecek siparişin benzersiz ID'si.
• amount (int, zorunlu): İptal edilecek tutar (Kuruş cinsinden).

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

• customer_id (string, zorunlu): Kullanıcıya özel ID.
• cc_owner (string, zorunlu): Kart sahibi adı.
• card_number (string, zorunlu): Kart numarası.
• expiry_month (string, zorunlu): Son kullanma ayı (MM).
• expiry_year (string, zorunlu): Son kullanma yılı (YY).
• cvv (string, zorunlu): Kart güvenlik kodu.

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

• token (string, zorunlu): Kayıtlı kart tokeni.
• amount (int, zorunlu): Ödeme tutarı (Kuruş cinsinden).
• merchant_oid (string, zorunlu): Sipariş ID'si.
• currency (string, opsiyonel): Para birimi.
• installment_count (int, opsiyonel): Taksit sayısı.

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

• token (string, zorunlu): Kayıtlı kart tokeni.
• amount (int, zorunlu): Ödeme tutarı (Kuruş cinsinden).
• merchant_oid (string, zorunlu): Sipariş ID'si.
• currency (string, opsiyonel): Para birimi.
• installment_count (int, opsiyonel): Taksit sayısı.

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

• customerId (string, zorunlu): Kullanıcıya özel ID.

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

• token (string, zorunlu): Silinecek kartın tokeni.

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();
}

Link ile Ödeme Oluştur (createLink)

createLink(array $payload): array fonksiyonu, kullanıcıya özel ödeme linki oluşturur.

Parametreler

• email (string, zorunlu): Kullanıcı e-posta adresi.
• amount (int, zorunlu): Ödeme tutarı (Kuruş cinsinden).
• user_name (string, zorunlu): Kullanıcı adı.
• user_address (string, zorunlu): Kullanıcı adresi.
• user_phone (string, zorunlu): Kullanıcı telefon numarası.
• basket (array, zorunlu): Sepet içeriği.
• currency (string, opsiyonel): Para birimi.
• lang (string, opsiyonel): Dil.

Dönüş Değeri

[
  'status' => 'success',
  'link' => 'https://paytr.com/odeme/....',
  // Diğer PayTR yanıt parametreleri
]

Örnek: Link ile Ödeme Oluşturma

$payload = [
    'email' => 'user@example.com',
    'amount' => 10000,
    'user_name' => 'Test Kullanıcı',
    'user_address' => 'Adres',
    'user_phone' => '5551234567',
    'basket' => [
        ['name' => 'Ürün', 'price' => 10000, 'quantity' => 1],
    ],
];

try {
    $result = Paytr::link()->createLink($payload);
    // $result['link'] ile kullanıcıya ödeme linki gönderilebilir
} catch (Paytr\Exceptions\PaytrException $e) {
    echo $e->getMessage();
}

Link Sil (deleteLink)

deleteLink(string $linkId): array fonksiyonu, oluşturulan ödeme linkini siler.

Parametreler

• linkId (string, zorunlu): Silinecek linkin ID'si.

Dönüş Değeri

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

Örnek: Link Silme

$linkId = 'LINK_ID';

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

Link Callback Doğrulama (verifyCallback)

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

Parametreler

• payload (array, zorunlu): Callback ile gelen veri.
• signature (string, zorunlu): Callback isteği ile gelen imza.

Dönüş Değeri

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

Örnek: Callback Doğrulama

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

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

Link Bildirim Gönder (sendLinkNotification)

sendLinkNotification(string $linkId, string $type = 'sms'): array fonksiyonu, oluşturulan ödeme linki için SMS veya e-posta bildirimi gönderir.

Parametreler

• linkId (string, zorunlu): Bildirim gönderilecek linkin ID'si.
• type (string, opsiyonel): Bildirim tipi ('sms' veya 'email').

Dönüş Değeri

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

Örnek: Link Bildirim Gönderme

$linkId = 'LINK_ID';

try {
    $result = Paytr::link()->sendLinkNotification($linkId, 'sms');
    // Bildirim 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:

• Ödeme Servisi (PaymentService): Direct API, iFrame API, ödeme durumu, taksit oranı, BIN sorgulama, işlem detayı.
• İade Servisi (RefundService): Tam/kısmi iade ve iade durumu sorgulama.
• İptal Servisi (CancelService): Tam/kısmi iptal işlemleri.
• Kart Servisi (CardService): Kart saklama, kayıtlı kartla ödeme, kart listeleme/silme.
• Link Servisi (LinkService): Link ile ödeme oluşturma, silme, bildirim gönderme.
• Platform Servisi (PlatformService): Platform transferi, iade, callback doğrulama.

Ö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

• PaymentSuccessEvent: Başarılı ödeme sonrası tetiklenir.
• PaymentFailedEvent: Başarısız ödeme sonrası tetiklenir.
• RefundSuccessEvent: Başarılı iade sonrası tetiklenir.

// 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.

• PaytrEventsTest: Eventlerin veri taşıma işlevi test edilir.
• WebhookSecretTest: Webhook secret eksikse istek reddedilir.
• VerifyPaytrSignatureTest: Middleware imza doğrulaması test edilir.
• WebhookAllowedIpTest: IP kısıtlaması test edilir.
• ServicePayloadTest & PayloadStructureTest: Servislerin imza ve payload yapısı test edilir.
• PaymentTest: Temel ödeme, iade, kart ve iptal işlemleri test edilir.

Platform Transfer Oluştur (createTransfer)

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

Parametreler

• amount (int, zorunlu): Transfer edilecek tutar (Kuruş cinsinden).
• iban (string, zorunlu): Alıcı IBAN numarası.
• description (string, opsiyonel): Açıklama.

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

• transferId (string, zorunlu): Sorgulanacak transferin ID'si.

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

• date_start (string, zorunlu): Başlangıç tarihi (YYYY-MM-DD).
• date_end (string, zorunlu): Bitiş tarihi (YYYY-MM-DD).

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

• trans_id (string, zorunlu): İade edilecek işlemin ID'si.
• amount (int, zorunlu): İade edilecek tutar (Kuruş cinsinden).
• iban (string, zorunlu): Alıcı IBAN numarası.
• name (string, zorunlu): Alıcı adı.

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

• payload (array, zorunlu): Callback ile gelen veri.

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

• payload (array, zorunlu): Callback ile gelen veri.
• signature (string, zorunlu): Callback isteği ile gelen imza.

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

• Ödeme başarılı olduğunda otomatik olarak tetiklenir (webhook veya servis üzerinden).

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

• Ödeme başarısız olduğunda otomatik olarak tetiklenir (webhook veya servis üzerinden).

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

• İade başarılı olduğunda otomatik olarak tetiklenir (webhook veya servis üzerinden).

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
});

Callback Doğrulama (validateCallback)

PayTR, 2. Adım (Bildirim URL) işleminde ödeme sonucunu sitenize bir POST isteği ile iletir. Güvenlik gereği bu isteğin gerçekten PayTR'dan geldiğini doğrulamanız zorunludur.

Kullanım

use Paytr\Facades\Paytr;
use Illuminate\Http\Request;

public function handleCallback(Request $request)
{
    // Gelen isteği doğrula
    $isValid = Paytr::payment()->validateCallback($request->all());

    if (!$isValid) {
        return response('Bad Hash', 400); // Hatalı imza ise reddet
    }

    // İmza doğruysa, ödeme durumunu kontrol et
    if ($request->post('status') == 'success') {
        // Ödeme başarılı, siparişi onayla
    } else {
        // Ödeme başarısız, siparişi iptal et
    }

    return response('OK'); // PayTR'a işlemin alındığını bildir (ZORUNLU)
}

Çalışma Prensibi

• Gelen POST isteğindeki merchant_oid, status, ve total_amount değerleri, merchant_salt ile birleştirilerek PayTR'ın beklediği şifreleme algoritmasıyla hash'lenir.
• Oluşturulan hash, PayTR tarafından gönderilen hash değeri ile karşılaştırılır.

Webhook / Bildirim URL Yönetimi

Ödemenin tamamlandığını yalnızca PayTR'ın 2. adım bildirimi ile anlamalısınız. Kullanıcının iFrame'den dönüş URL'sine yönlenmesi ödemenin kesin başarılı olduğu anlamına gelmez.

Önemli Kurallar

• PayTR bildirimlerine her zaman OK metnini (string) döndürmelisiniz. Aksi halde PayTR, sitenize yanıt alamadığını düşünüp aynı bildirimi tekrar tekrar gönderir.
• Siparişi veritabanında güncellemeden önce mutlaka validateCallback ile güvenlik kontrolünü yapın.
• Yalnızca PayTR'ın IP adreslerinden gelen isteklere izin vererek güvenliğinizi artırabilirsiniz.

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.

• PaytrEventsTest: Eventlerin veri taşıma işlevi test edilir.
• WebhookSecretTest: Webhook secret eksikse istek reddedilir.
• VerifyPaytrSignatureTest: Middleware imza doğrulaması test edilir.
• WebhookAllowedIpTest: IP kısıtlaması test edilir.
• ServicePayloadTest & PayloadStructureTest: Servislerin imza ve payload yapısı test edilir.
• PaymentTest: Temel ödeme, iade, kart ve iptal işlemleri test edilir.

Örnek: Test Assertion

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