Skip to content
BranchesTags

Repository files navigation

PHP 8.2+ PHPStan Level 9 MIT License 9 Gateways CI Status

💳 Arpay

Türkiye'nin Birleşik Ödeme Kütüphanesi
9 farklı Türk ödeme altyapısını tek bir API ile yönetin.

Kurulum • Hızlı Başlangıç • Gateway'ler • Özellikler • Demo • Katkıda Bulunma

🌟 Nedir?

Arpay, Türkiye'deki popüler ödeme altyapılarını tek bir birleşik PHP arayüzü altında toplayan açık kaynak ödeme kütüphanesidir. Gateway değiştirmek artık tek satır değişiklik demek!

// PayTR ile ödeme al
$gateway = Arpay::create('paytr', $config);
$response = $gateway->pay($request);

// Iyzico'ya geçmek mi istiyorsun? Sadece gateway adını değiştir!
$gateway = Arpay::create('iyzico', $config);
$response = $gateway->pay($request); // Aynı $request, aynı API!

✨ Özellikler

Özellik Açıklama
💳 Tek Çekim Ödeme Tüm gateway'lerle anında ödeme
🔒 3D Secure Güvenli ödeme ile banka doğrulama
💰 İade İşlemleri Tam veya kısmi iade desteği
🔍 Ödeme Sorgulama İşlem durumu kontrolü
🔄 Abonelik / Tekrarlayan Ödeme Otomatik periyodik tahsilat
📊 Taksit Sorgulama BIN bazlı taksit oranları
🧪 Test Modu Sandbox ortamında güvenli geliştirme
🐳 Docker Demo Anında çalışan interaktif demo
🛡️ PHPStan Level 9 (Max) Maksimum statik analiz güvencesi

🏦 Desteklenen Gateway'ler

# Gateway Ödeme İade Sorgu 3D Secure Abonelik Taksit
1 PayTR ✅ ✅ ✅ ✅ ✅ ✅
2 Iyzico ✅ ✅ ✅ ✅ ✅ ✅
3 Vepara ✅ ✅ ✅ ✅ — ✅
4 ParamPos ✅ ✅ ✅ ✅ ✅ ✅
5 iPara ✅ ✅ ✅ ✅ — ✅
6 Ödeal ✅ ✅ ✅ ✅ — —
7 Paynet ✅ ✅ ✅ ✅ ✅ ✅
8 PayU ✅ ✅ ✅ ✅ ✅ —
9 Papara ✅ ✅ ✅ — — —

📦 Kurulum

composer require armagangokce/arpay

Gereksinimler

  • PHP 8.2 veya üzeri
  • ext-json, ext-openssl, ext-mbstring
  • Guzzle HTTP ^7.8

🚀 Hızlı Başlangıç

💳 Tek Çekim Ödeme

<?php

use Arpay\Arpay;
use Arpay\DTO\CreditCard;
use Arpay\DTO\Customer;
use Arpay\DTO\PaymentRequest;
use Arpay\DTO\CartItem;

// 1. Gateway oluştur
$gateway = Arpay::create('paytr', [
    'merchant_id'   => 'YOUR_MERCHANT_ID',
    'merchant_key'  => 'YOUR_MERCHANT_KEY',
    'merchant_salt' => 'YOUR_MERCHANT_SALT',
    'test_mode'     => true,
]);

// 2. Kart bilgileri
$card = CreditCard::create(
    cardHolderName: 'Armağan Gökce',
    cardNumber:     '5528790000000008',
    expireMonth:    '12',
    expireYear:     '2030',
    cvv:            '123',
);

// 3. Müşteri bilgileri
$customer = Customer::create(
    firstName: 'Armağan',
    lastName:  'Gökce',
    email:     'ben@armagangokce.com',
    phone:     '05551234567',
    ip:        '127.0.0.1',
);

// 4. Ödeme isteği
$request = PaymentRequest::create()
    ->amount(150.00)
    ->currency('TRY')
    ->orderId('ORDER-' . time())
    ->description('Premium Paket')
    ->installmentCount(1)
    ->card($card)
    ->customer($customer)
    ->addCartItem(CartItem::create('P001', 'Premium Paket', 'Yazılım', 150.00));

// 5. Ödeme yap!
$response = $gateway->pay($request);

if ($response->isSuccessful()) {
    echo "✅ Ödeme başarılı! İşlem No: " . $response->getTransactionId();
} else {
    echo "❌ Hata: " . $response->getErrorMessage();
}

↩️ İade İşlemi

use Arpay\DTO\RefundRequest;

$refund = RefundRequest::create()
    ->transactionId('TXN-12345')
    ->amount(50.00)
    ->reason('Müşteri talebi');

$response = $gateway->refund($refund);

if ($response->isSuccessful()) {
    echo "✅ İade başarılı! Tutar: " . $response->getRefundedAmount() . " TL";
}

🔒 3D Secure Ödeme

use Arpay\DTO\SecurePaymentRequest;

$request = SecurePaymentRequest::create()
    ->amount(250.00)
    ->currency('TRY')
    ->orderId('ORDER-3D-001')
    ->card($card)
    ->customer($customer)
    ->callbackUrl('https://example.com/callback')
    ->successUrl('https://example.com/success')
    ->failUrl('https://example.com/fail');

$response = $gateway->initSecurePayment($request);

if ($response->isRedirectRequired()) {
    // Müşteriyi banka sayfasına yönlendir
    echo $response->getRedirectForm();
}

🔍 Ödeme Sorgulama

use Arpay\DTO\QueryRequest;

$query = QueryRequest::create()
    ->transactionId('TXN-12345')
    ->orderId('ORDER-001');

$response = $gateway->query($query);

if ($response->isSuccessful()) {
    echo "Durum: " . $response->getPaymentStatus()->value;
    echo "Tutar: " . $response->getAmount() . " TL";
}

📊 Taksit Sorgulama

$installments = $gateway->queryInstallments('552879', 1000.00);

foreach ($installments as $info) {
    echo "{$info->installmentCount} taksit: {$info->installmentAmount} TL/ay "
       . "(Toplam: {$info->totalAmount} TL, Faiz: %{$info->interestRate})\n";
}

�️ Hata Yönetimi

use Arpay\Exceptions\ArpayException;
use Arpay\Exceptions\GatewayNotFoundException;
use Arpay\Exceptions\InvalidParameterException;
use Arpay\Exceptions\AuthenticationException;
use Arpay\Exceptions\NetworkException;
use Arpay\Exceptions\PaymentFailedException;
use Arpay\Exceptions\UnsupportedOperationException;

try {
    $gateway = Arpay::create('paytr', $config);
    $response = $gateway->pay($request);

    if (!$response->isSuccessful()) {
        echo "Reddedildi: " . $response->getErrorMessage();
    }
} catch (GatewayNotFoundException $e) {
    // Geçersiz gateway adı
} catch (InvalidParameterException $e) {
    // Eksik yapılandırma
} catch (AuthenticationException $e) {
    // Yanlış API anahtarları
} catch (NetworkException $e) {
    // Bağlantı hatası / timeout
} catch (PaymentFailedException $e) {
    // Kritik ödeme hatası — $e->getErrorCode(), $e->getRawResponse()
} catch (UnsupportedOperationException $e) {
    // Gateway bu işlemi desteklemiyor
} catch (ArpayException $e) {
    // Tüm Arpay hataları (genel catch)
}

💡 Detaylı hata yönetimi örnekleri için Hızlı Başlangıç Rehberi'ne bakın.

�🔄 Abonelik Oluşturma

use Arpay\DTO\SubscriptionRequest;

$subscription = SubscriptionRequest::create()
    ->planName('Premium Aylık')
    ->amount(99.99)
    ->currency('TRY')
    ->period('monthly')
    ->periodInterval(1)
    ->card($card)
    ->customer($customer);

$response = $gateway->createSubscription($subscription);

if ($response->isSuccessful()) {
    echo "✅ Abonelik oluşturuldu: " . $response->getSubscriptionId();
}

⚙️ Gateway Yapılandırmaları

PayTR 
$gateway = Arpay::create('paytr', [
    'merchant_id'   => 'YOUR_MERCHANT_ID',
    'merchant_key'  => 'YOUR_MERCHANT_KEY',
    'merchant_salt' => 'YOUR_MERCHANT_SALT',
    'test_mode'     => true,
]);
Iyzico 
$gateway = Arpay::create('iyzico', [
    'api_key'    => 'YOUR_API_KEY',
    'secret_key' => 'YOUR_SECRET_KEY',
    'test_mode'  => true,
]);
Vepara 
$gateway = Arpay::create('vepara', [
    'api_key'     => 'YOUR_API_KEY',
    'secret_key'  => 'YOUR_SECRET_KEY',
    'merchant_id' => 'YOUR_MERCHANT_ID',
    'test_mode'   => true,
]);
ParamPos 
$gateway = Arpay::create('parampos', [
    'client_code'     => 'YOUR_CLIENT_CODE',
    'client_username' => 'YOUR_USERNAME',
    'client_password' => 'YOUR_PASSWORD',
    'guid'            => 'YOUR_GUID',
    'test_mode'       => true,
]);
iPara 
$gateway = Arpay::create('ipara', [
    'public_key'  => 'YOUR_PUBLIC_KEY',
    'private_key' => 'YOUR_PRIVATE_KEY',
    'test_mode'   => true,
]);
Ödeal 
$gateway = Arpay::create('odeal', [
    'api_key'    => 'YOUR_API_KEY',
    'secret_key' => 'YOUR_SECRET_KEY',
    'test_mode'  => true,
]);
Paynet 
$gateway = Arpay::create('paynet', [
    'secret_key'  => 'YOUR_SECRET_KEY',
    'merchant_id' => 'YOUR_MERCHANT_ID',
    'test_mode'   => true,
]);
PayU 
$gateway = Arpay::create('payu', [
    'merchant'   => 'YOUR_MERCHANT',
    'secret_key' => 'YOUR_SECRET_KEY',
    'test_mode'  => true,
]);
Papara 
$gateway = Arpay::create('papara', [
    'api_key'     => 'YOUR_API_KEY',
    'merchant_id' => 'YOUR_MERCHANT_ID',
    'test_mode'   => true,
]);

🐳 Demo

Arpay, tüm 9 gateway'i interaktif olarak test edebileceğiniz bir Docker demo ile birlikte gelir.

# Docker ile başlat
docker compose up --build

# veya PHP built-in server ile
php -S localhost:8043 -t demo

🌐 Tarayıcıda aç: http://localhost:8043

⚠️ Demo ortamı MockHttpClient kullanır — gerçek API çağrısı yapılmaz.

🏗️ Mimari

src/
├── Arpay.php                  # Ana facade — Arpay::create()
├── ArpayFactory.php           # Gateway factory
├── Contracts/                 # Interface'ler
│   ├── PayableInterface.php
│   ├── RefundableInterface.php
│   ├── QueryableInterface.php
│   ├── SecurePayableInterface.php
│   ├── SubscribableInterface.php
│   └── InstallmentQueryableInterface.php
├── DTO/                       # Veri transfer nesneleri
│   ├── PaymentRequest.php
│   ├── PaymentResponse.php
│   ├── RefundRequest.php
│   ├── RefundResponse.php
│   ├── QueryRequest.php
│   ├── QueryResponse.php
│   ├── SecurePaymentRequest.php
│   ├── SecureInitResponse.php
│   ├── SubscriptionRequest.php
│   ├── SubscriptionResponse.php
│   ├── CreditCard.php
│   ├── Customer.php
│   ├── CartItem.php
│   ├── Address.php
│   └── InstallmentInfo.php
├── Enums/                     # Sabitler
├── Exceptions/                # Özel hata sınıfları
├── Gateways/                  # 9 gateway implementasyonu
│   ├── AbstractGateway.php
│   ├── PayTR/
│   ├── Iyzico/
│   ├── Vepara/
│   ├── ParamPos/
│   ├── Ipara/
│   ├── Odeal/
│   ├── PayNet/
│   ├── PayU/
│   └── Papara/
├── Http/                      # HTTP katmanı
│   ├── HttpClientInterface.php
│   ├── GuzzleHttpClient.php
│   └── HttpResponse.php
└── Support/                   # Yardımcı sınıflar
    ├── Config.php
    ├── HashGenerator.php
    └── MoneyFormatter.php

🧪 Test

# Tüm testleri çalıştır
composer test

# PHPStan analizi
composer analyse

# Kod stili kontrolü
composer cs-check

# Kod stili düzeltme
composer cs-fix

# Hepsini bir seferde
composer check

🤝 Katkıda Bulunma

Katkılarınızı memnuniyetle karşılıyoruz! Lütfen CONTRIBUTING.md dosyasını inceleyin.

  1. 🍴 Fork edin
  2. 🌿 Feature branch oluşturun (git checkout -b feature/amazing-feature)
  3. ✅ Testleri geçirin (composer check)
  4. 📝 Commit edin (git commit -m 'feat: amazing feature')
  5. 🚀 Push edin (git push origin feature/amazing-feature)
  6. 📬 Pull Request açın

📋 Diğer Belgeler

Belge Açıklama
docs/QUICK_START.md 5 dakikada başlangıç rehberi
docs/API_REFERENCE.md Tüm sınıf ve metot dokümantasyonu
CONTRIBUTING.md Katkıda bulunma rehberi
CODE_OF_CONDUCT.md Topluluk davranış kuralları
SECURITY.md Güvenlik politikası
CHANGELOG.md Değişiklik günlüğü
LICENSE MIT Lisansı

👨‍💻 Geliştirici

Armağan Gökce
Armağan Gökce
Full-Stack Developer • 15+ Yıl Deneyim

🌐 💻 💼 📸 📧

PHP • Laravel • Node.js • Vue.js • React • Docker • AWS

50+ proje • Isparta, Türkiye 🇹🇷

📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır — detaylar için LICENSE dosyasına bakın.

⭐ Bu projeyi beğendiyseniz yıldız bırakmayı unutmayın!
Made with ❤️ in Türkiye 🇹🇷 by Armağan Gökce

About

Türkiye'nin Birleşik Ödeme Kütüphanesi 9 Türk ödeme altyapısını tek bir PHP API ile yönetin

www.armagangokce.com

Topics

composer-packagefintechgatewayiyzicoodemepaymentpaytrphpsanal-posturkey

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages