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ı)
    // product_id dahil gönderdiğiniz tüm alanlar webhook ve GET /payments/{id} yanıtında aynen geri döner
    'invoice_data' => [
        [
            'product_id'  => 'SKU-1042',          // kendi sisteminizdeki ürün ID'si
            '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',
        ],
        [
            'product_id'  => 'SKU-0088',
            '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 olayları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);

Webhook Payload

{
  "event":              "payment.completed",
  "payment_id":         "019ef95f-5c54-726d-84c0-a3f0e1ea2cb8",
  "order_id":           "BZG-01KVWNYQ2JTHFN5YMN4VZJKWFG",
  "external_order_id":  "343024031",
  "status":             "PAYMENT_COMPLETED",
  "amount":             "349.90",
  "currency":           "TRY",
  "auth_code":          "540312",
  "ref_ret_num":        "617514555962",
  "masked_number":      "5339",
  "invoice_data": [
    { "product_id": "SKU-1042", "name": "Kablosuz Kulaklık", "quantity": 1, "price": 297.03 },
    { "product_id": "SKU-0088", "name": "USB-C Kablo",       "quantity": 2, "price": 22.50 }
  ],
  "timestamp":          "2026-06-24T14:23:57+00:00"
}

Olaylar (Events)

Event	Açıklama
`payment.completed`	Ödeme başarıyla tamamlandı
`payment.failed`	Ödeme başarısız oldu
`payment.refunded`	Ödeme iade edildi (settlement sonrası)
`payment.cancelled`	Ödeme iptal edildi (aynı gün, settlement öncesi)

$event     = $payload['event'];
$paymentId = $payload['payment_id'];
$orderId   = $payload['order_id'];

match ($event) {
    'payment.completed'  => handleCompleted($payload),
    'payment.failed'     => handleFailed($payload),
    'payment.refunded'   => handleRefunded($payload),
    'payment.cancelled'  => handleCancelled($payload),
    default              => null,
};

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` / `PAYMENT_COMPLETED` / `PAYMENT_FAILED` / `REFUNDED` / `CANCELLED`
`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
`invoiceData`	`array`	Ödeme oluşturulurken gönderilen ürün listesi (boş ise `[]`)
`initiatedAt`	`?string`	Başlangıç tarihi (ISO 8601)
`completedAt`	`?string`	Tamamlanma tarihi (ISO 8601)

Yardımcı metodlar: isPending(), isCompleted(), isFailed(), isRefunded(), isCancelled(), 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

altivo / payments-sdk

Package info

Security

Statistics