README

Altivo Payments API için resmi PHP istemcisi. Türk bankalarıyla POS entegrasyonunu tek satır kurulumla projenize ekler.

Gereksinimler

• PHP 8.1+
• Guzzle 7.x (guzzlehttp/guzzle)

Kurulum

composer require altivo/payments-sdk

Laravel

.env dosyanıza ekleyin:

ALTIVO_PAY_BASE_URL=https://odemelerin.siteadi.com
ALTIVO_PAY_API_KEY=ak_live_xxxxxxxxxxxx

Servis sağlayıcı otomatik keşfedilir. Facade ile kullanabilirsiniz:

use Altivo\Payments\Laravel\Facades\Altivo;

Altivo::payments()->create([...]);

Framework bağımsız

use Altivo\Payments\AltivoClient;

$altivo = new AltivoClient(
    baseUrl: 'https://odemelerin.siteadi.com',
    apiKey:  'ak_live_xxxxxxxxxxxx',
);

Hızlı Başlangıç

3D Secure Ödeme

use Altivo\Payments\Exceptions\ApiException;

try {
    $payment = $altivo->payments()->create([
        'amount'      => 249.90,
        'currency'    => 'TRY',
        'installment' => 0,
        'success_url' => 'https://siteadi.com/odeme/basarili',
        'fail_url'    => 'https://siteadi.com/odeme/basarisiz',
        'card'        => [
            'number'       => '4111111111111111',
            'expire_month' => '12',
            'expire_year'  => '26',
            'cvv'          => '123',
            'holder_name'  => 'Ali Veli',
        ],
    ]);
} catch (ApiException $e) {
    echo $e->getMessage();       // hata metni
    echo $e->getStatusCode();    // HTTP durum kodu
}

if ($payment->requires3D()) {
    // $payment->formData → bankaya POST edilecek form alanları
    // Kullanıcıyı bankaya yönlendirin (otomatik form submit)
}

Regular (3D'siz) Ödeme

$payment = $altivo->payments()->create([
    'amount'      => 99.00,
    'currency'    => 'TRY',
    'success_url' => 'https://siteadi.com/basarili',
    'fail_url'    => 'https://siteadi.com/basarisiz',
    'card'        => [...],
]);

if ($payment->isCompleted()) {
    // ödeme onaylandı
}

Ödeme Durumu Sorgula

// Detay getir (kendi veritabanınızdaki kayıtla karşılaştırmak için)
$payment = $altivo->payments()->get('payment-uuid');

// Bankadan anlık durum sorgula
$status = $altivo->payments()->status('payment-uuid');

echo $status->status;        // PAYMENT_COMPLETED
echo $status->bankResponse;  // bankanın ham yanıtı

Hosted Checkout (Stripe tarzı ödeme sayfası)

Müşteriyi hazır, Stripe benzeri bir ödeme sayfasına yönlendirin. Kart formu, ürün listesi, KDV ve kargo satırları otomatik gösterilir. 3D Secure akışı tamamen sunucu tarafında halledilir.

$session = $altivo->checkout()->createSession([
    'amount'          => 349.90,
    'currency'        => 'TRY',
    'description'     => 'Sipariş #1042',
    'success_url'     => 'https://siteadi.com/odeme/basarili',
    'fail_url'        => 'https://siteadi.com/odeme/basarisiz',

    // İsteğe bağlı kırılım
    'tax_amount'      => 52.87,
    'shipping_amount' => 0,      // 0 → "Ücretsiz" olarak gösterilir

    // Ürün satırları (isteğe bağlı)
    'invoice_data' => [
        [
            'name'        => 'Kablosuz Kulaklık',
            'quantity'    => 1,
            'price'       => 297.03,
            'image_url'   => 'https://cdn.siteadi.com/urunler/kulalik.jpg',
            'description' => 'Bluetooth 5.3, 30 saat pil',
        ],
        [
            'name'     => 'USB-C Kablo',
            'quantity' => 2,
            'price'    => 22.50,
        ],
    ],
]);

// Müşteriyi yönlendirin — gerisini Altivo halleder
header('Location: ' . $session->checkoutUrl);

Oturum 24 saat geçerlidir ve yalnızca bir kez kullanılabilir.

echo $session->sessionId;   // UUID
echo $session->checkoutUrl; // https://odemelerin.siteadi.com/checkout/{token}
echo $session->expiresAt;   // 2026-06-24T10:30:00+00:00

Laravel / Facade:

use Altivo\Payments\Laravel\Facades\Altivo;

$session = Altivo::checkout()->createSession([...]);
return redirect($session->checkoutUrl);

iFrame ile Gömülü Ödeme

Müşterinin sitenizi terk etmeden ödeme yapmasını sağlar.

// 1. Backend'de token oluşturun
$iframe = $altivo->iframe()->createToken([
    'amount'      => 149.00,
    'currency'    => 'TRY',
    'success_url' => 'https://siteadi.com/basarili',
    'fail_url'    => 'https://siteadi.com/basarisiz',
]);

echo $iframe->iframeUrl;  // embed edilecek URL (30 dk geçerli)
echo $iframe->expiresAt;  // ISO 8601 tarih

<!-- 2. Frontend'de embed edin -->
<iframe src="<?= $iframe->iframeUrl ?>" width="480" height="600" frameborder="0"></iframe>

<!-- 3. Sonucu postMessage ile dinleyin -->
<script>
window.addEventListener('message', function (e) {
    if (e.data?.type !== 'altivo:payment') return;

    if (e.data.success) {
        console.log('Başarılı, payment_id:', e.data.payment_id);
    } else {
        console.log('Başarısız:', e.data.message);
    }
});
</script>

Webhook Doğrulama

Altivo, ödeme tamamlandığında belirlediğiniz URL'e POST atar. İsteği doğrulamak için X-Altivo-Signature başlığını kontrol edin:

$secret   = 'webhook-secret-key';
$body     = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
$received = $_SERVER['HTTP_X_ALTIVO_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$payload   = json_decode($body, true);
$event     = $payload['event'];      // 'payment.completed' | 'payment.failed'
$paymentId = $payload['payment_id'];

Webhook başarısız olursa Altivo 3 kez daha dener: 1 dk → 5 dk → 30 dk.

Yanıt Nesneleri

PaymentResponse

Özellik	Tür	Açıklama
paymentId	string	Ödeme UUID
orderId	string	Altivo tarafından üretilen sipariş no
status	string	PENDING / PENDING_3D / PAYMENT_COMPLETED / PAYMENT_FAILED
type	string	3d veya regular
formData	?array	3D akışı için banka form verisi
amount	?float	Ödeme tutarı
currency	?string	Para birimi
cardLastFour	?string	Kartın son 4 hanesi
initiatedAt	?string	Başlangıç tarihi (ISO 8601)
completedAt	?string	Tamamlanma tarihi (ISO 8601)

Yardımcı metodlar: isPending(), isCompleted(), isFailed(), requires3D(), toArray()

StatusResponse

Özellik	Tür	Açıklama
paymentId	string	Ödeme UUID
orderId	string	Sipariş no
status	string	Güncel durum
bankResponse	array	Bankanın ham yanıtı

IframeTokenResponse

Özellik	Tür	Açıklama
token	string	64 karakterlik oturum token'ı
iframeUrl	string	Embed edilecek tam URL
expiresAt	string	Son kullanma tarihi (ISO 8601)

CheckoutSessionResponse

Özellik	Tür	Açıklama
sessionId	string	Oturum UUID
checkoutUrl	string	Müşterinin yönlendirileceği ödeme sayfası URL'i
expiresAt	string	Son kullanma tarihi — 24 saat (ISO 8601)

Hata Yönetimi

use Altivo\Payments\Exceptions\ApiException;
use Altivo\Payments\Exceptions\AltivoException;

try {
    $payment = $altivo->payments()->create([...]);
} catch (ApiException $e) {
    // API'den dönen HTTP hatası (4xx / 5xx)
    $e->getStatusCode();    // örn: 422
    $e->getResponseBody();  // ['error' => 'Aktif gateway bulunamadı']
    $e->getMessage();       // kısa hata metni
} catch (AltivoException $e) {
    // Yapılandırma hatası (boş base_url veya api_key)
} catch (\Throwable $e) {
    // Ağ hatası, timeout vb.
}

Seçenekler

$altivo = new AltivoClient(
    baseUrl: 'https://odemelerin.siteadi.com',
    apiKey:  'ak_live_xxxxxxxxxxxx',
    options: [
        'timeout'    => 15,    // saniye, varsayılan: 30
        'verify_ssl' => false, // geliştirme ortamı için, prod'da true bırakın
    ],
);

Lisans

MIT