README

Bu kütüphane, PayTR ödeme sistemini PHP uygulamalarınıza kolayca entegre etmenizi sağlar. Iframe, Direkt Ödeme, BIN Sorgulama ve Callback işlemleri gibi temel PayTR özelliklerini destekler.

Kurulum

Kütüphaneyi projenize Composer ile ekleyebilirsiniz:

composer require hasokeyk/paytr-php

Kullanım

1. PayTR Bilgilerini Yapılandırma

Öncelikle PayTR mağaza bilgileriniz olan merchant_id, merchant_key ve merchant_salt değerlerini ayarlamanız gerekmektedir. Bu bilgileri PayTR panelinizden edinebilirsiniz.

require_once __DIR__.'/vendor/autoload.php';

use Paytr\Paytr;
use Paytr\PaytrFactory;

$merchant_id   = 'XXXXXX'; // PayTR Mağaza ID'niz
$merchant_key  = 'YYYYYYYYYYYYYY'; // PayTR Mağaza Anahtarınız
$merchant_salt = 'ZZZZZZZZZZZZZZ'; // PayTR Mağaza Parolanız

$paytr = new Paytr($merchant_id, $merchant_key, $merchant_salt);

// Test modunu aktif etmek için (isteğe bağlı)
// $paytr->set_test_mode(true);

2. Iframe Ödeme

Iframe ödeme yöntemi ile müşterilerinizi PayTR ödeme sayfasına yönlendirmeden, kendi siteniz içerisinde ödeme alabilirsiniz.

// ... yukarıdaki yapılandırma kodları ...

$payment = PaytrFactory::create('iframe', $paytr);

$data = [
    'user_ip'           => $_SERVER['REMOTE_ADDR'], // Müşterinin IP adresi
    'merchant_oid'      => 'SIPARIS_'.time(), // Sipariş ID'si (her sipariş için benzersiz olmalı)
    'email'             => 'test@example.com', // Müşterinin e-posta adresi
    'payment_amount'    => 100, // Ödenecek tutar (kuruş cinsinden, örn: 1 TL için 100)
    'currency'          => 'TRY', // Para birimi
    'user_basket'       => base64_encode(json_encode([ // Sepet bilgileri
                                                   ['Ürün 1', '10.00', 1],
                                                   ['Ürün 2', '90.00', 1],
    ])),
    'user_name'         => 'Test Kullanıcı', // Müşterinin adı
    'user_address'      => 'Test Adres Mah. Test Cad. No:1 Test İlçe/Test İl', // Müşterinin adresi
    'user_phone'        => '05XXXXXXXXX', // Müşterinin telefonu
    'merchant_ok_url'   => 'http://localhost/callback.php', // Başarılı ödeme sonrası yönlendirilecek sayfa URL'si
    'merchant_fail_url' => 'http://localhost/callback.php', // Başarısız ödeme sonrası yönlendirilecek sayfa URL'si
    'debug_on'          => 1, // Hata ayıklama modu (0 veya 1)
    'lang'              => 'tr', // Dil (tr veya en)
    // Diğer opsiyonel parametreler PayTR dokümantasyonunda bulunabilir.
];

$iframe_html = $payment->run($data);

echo $iframe_html; // Bu HTML kodunu sayfanızda bir div içine yerleştirin

3. Direkt Ödeme (Kart Bilgileri ile)

Müşteriden kart bilgilerini alarak doğrudan ödeme yapmak için kullanılır. 3D Secure yönlendirmesi gerekebilir.

// ... yukarıdaki yapılandırma kodları ...

$payment = PaytrFactory::create('direct', $paytr);

$data = [
    'user_ip'           => $_SERVER['REMOTE_ADDR'],
    'merchant_oid'      => 'SIPARIS_'.time(),
    'email'             => 'test@example.com',
    'payment_amount'    => 100,
    'currency'          => 'TRY',
    'user_basket'       => base64_encode(json_encode([
                                                   ['Ürün 1', '10.00', 1],
    ])),
    'user_name'         => 'Test Kullanıcı',
    'user_address'      => 'Test Adres',
    'user_phone'        => '05XXXXXXXXX',
    'merchant_ok_url'   => 'http://localhost/callback.php',
    'merchant_fail_url' => 'http://localhost/callback.php',
    'debug_on'          => 1,
    'lang'              => 'tr',

    // Kart bilgileri (test modu aktif değilse gerçek kart bilgileri girilmelidir)
    'cc_owner'          => 'KART SAHIBI ADI',
    'card_number'       => 'XXXXXXXXXXXXXXXX', // Kart Numarası
    'expiry_month'      => 'AA', // Son Kullanma Ayı (örn: 01)
    'expiry_year'       => 'YY', // Son Kullanma Yılı (örn: 29)
    'cvv'               => 'XXX', // CVV Kodu
];

$result = $payment->run($data);

// 3D Secure kontrolü
$html_3d = $payment->handle_3d_secure($result);

if ($html_3d) {
    echo $html_3d; // 3D Secure sayfasına yönlendirme için HTML
} elseif ($result['status'] == 'success') {
    echo 'Ödeme başarılı! Sipariş ID: ' . $result['merchant_oid'];
    // Siparişinizi onaylayın
} else {
    echo 'Ödeme başarısız: ' . $result['reason'];
    // Siparişinizi iptal edin
}

4. PayTR Callback (Geri Bildirim) İşlemleri

PayTR, ödeme tamamlandığında (başarılı veya başarısız) merchant_ok_url veya merchant_fail_url olarak belirttiğiniz adrese bir POST isteği gönderir. Bu isteği işlemek için aşağıdaki gibi bir callback.php dosyası oluşturabilirsiniz:

// ... yukarıdaki yapılandırma kodları ...

// Direkt API callback'i için
$direct_payment = PaytrFactory::create('direct', $paytr);
$callback_data = $direct_payment->handle_callback($_POST);

// Eğer Direkt API callback değilse, diğer yöntemleri deneyin
if (!$callback_data) {
    $link_payment = PaytrFactory::create('link', $paytr);
    $callback_data = $link_payment->handle_callback($_POST);
}

if (!$callback_data) {
    $iframe_payment = PaytrFactory::create('iframe', $paytr);
    $callback_data = $iframe_payment->handle_callback($_POST);
}

if (!$callback_data) {
    $bank_transfer_iframe_payment = $paytr->bank_transfer_iframe();
    $callback_data = $bank_transfer_iframe_payment->handle_callback($_POST);
}

if (!$callback_data) {
    die('OK'); // Geçersiz callback veya hash doğrulaması başarısız
}

if ($callback_data['status'] == 'success') {
    // Ödeme başarılı
    // merchant_oid: $callback_data['merchant_oid']
    // Ödeme tutarı: $callback_data['payment_amount']
    // Siparişinizi onaylayın, veritabanınızı güncelleyin vb.
    echo 'Ödeme başarılı. Sipariş ID: ' . $callback_data['merchant_oid'];
} else {
    // Ödeme başarısız
    // merchant_oid: $callback_data['merchant_oid']
    // Hata nedeni: $callback_data['failed_reason_msg']
    // Siparişinizi iptal edin veya başarısız olarak işaretleyin.
    echo 'Ödeme başarısız. Sipariş ID: ' . $callback_data['merchant_oid'] . ' Neden: ' . $callback_data['failed_reason_msg'];
}

// PayTR'a callback'in alındığını bildirmek için "OK" çıktısı gönderin
echo 'OK';

5. BIN Sorgulama

Kartın BIN numarasına göre banka ve kart bilgilerini sorgulamak için kullanılır.

// ... yukarıdaki yapılandırma kodları ...

$bin_number = '545616'; // Sorgulanacak BIN numarası

$result = $paytr->bin_lookup($bin_number);

if ($result['status'] == 'success') {
    echo 'BIN sorgulama başarılı: <pre>' . print_r($result, true) . '</pre>';
} else {
    echo 'BIN sorgulama başarısız: ' . $result['reason'];
}

Dokümantasyon

Bu kütüphanenin kullanımı için en iyi kaynak, bu README dosyasındaki örnekler ve examples klasöründeki detaylı örnek dosyalardır. PayTR API'si hakkında daha fazla bilgi için PayTR Geliştirici Dokümantasyonu adresini ziyaret edebilirsiniz.