PHP ile Sanal POS Entegrasyonu

Neden PHP ile Sanal POS Entegrasyonu?

Web dünyasının en yaygın dillerinden biriyle ödeme entegrasyonu.

PHP, internet sitelerinin önemli bir bölümünü çalıştıran ve web geliştirme alanında en yaygın kullanılan programlama dillerinden biridir. WordPress, Laravel, Symfony, Magento ve WooCommerce gibi pek çok platform PHP üzerine inşa edilmiştir. Bu yaygınlık, PHP geliştiricilerinin ödeme entegrasyonu konusunda oturmuş bir ekosisteme ve geniş bir örnek birikimine sahip olduğu anlamına gelir.

Laravel ve Symfony gibi modern PHP çatılarıyla çalışan entegrasyon, Composer paket yöneticisi üzerinden bağımlılık olarak kurulabilir. MVC mimarisine ve PSR standartlarına uygun bir yapı, mevcut projelere eklenmeyi kolaylaştırır. Saf PHP projelerinde ise cURL ya da herhangi bir HTTP istemcisi ile doğrudan REST çağrıları yaparak aynı akışı kurabilirsiniz. Çatı bağımlılığı bulunmadığı için CodeIgniter, Yii, Slim veya kendi çatınızla geliştirdiğiniz özel projelerde de aynı yol izlenir.

Desteklenen PHP sürümleri ve bağımlılıklar, hesabınızın açıldığı ödeme kuruluşunun çözümüne göre belirlenir; kesin liste hesap açılışında iletilen dokümantasyonda belirtilir. Genel yetenekler için API ve SDK entegrasyonu sayfasına bakabilirsiniz.

Composer ve SDK Kurulumu

Paketi projeye ekleyin, anahtarları ortam değişkeninde tutun.

SDK kullanmak zorunlu değildir; ancak istek imzalama, oturum ve token yönetimi, yanıt ayrıştırma gibi tekrar eden işleri üstlendiği için çoğu projede yazılacak kod miktarını azaltır. Paket, Composer ile bağımlılık olarak eklenir. Aşağıdaki paket adı yer tutucudur: gerçek paket adı, varsa eklenti veya modül dosyası ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir.

# Paket adı hesabınız açıldığında iletilen dokümantasyonda yazılıdır.
# Tahmin ettiğiniz bir adla kurulum yapmayın (sahte paket riski).
composer require <saglayici>/<paket-adi>

API anahtarları kod dosyalarına ya da sürüm deposuna yazılmaz; sunucu ortam değişkenlerinde tutulur. Test ve canlı anahtarlar ayrı tutulmalı, canlı anahtarla test yapılmamalıdır. Kurulum sonrası sınıf adları, metot adları ve alan yapısı için PHP SDK sayfasını inceleyebilirsiniz.

PHP Kod Örneği

REST API ile ödeme başlatma örneği.

Aşağıdaki örnek, ödeme kuruluşunun REST uç noktasına PHP cURL ile ödeme başlatma isteği göndermeyi göstermektedir. Bu temel yapıyı kullanarak kendi ödeme akışınızı oluşturabilirsiniz. API anahtarınız istek başlığına eklenerek kimlik doğrulaması yapılır ve ödeme bilgileri JSON biçiminde gönderilir. Yanıt olarak işlem sonucu ve gerekiyorsa 3D Secure yönlendirme adresi döner.

Örnekteki adres ve alan adları yer tutucudur; karşılıkları hesabınız açıldığında iletilen dokümantasyonda yer alır. Daha gelişmiş kullanım ve hazır metotlar için PHP SDK dokümantasyonunu inceleyebilirsiniz.

// REST API ile ödeme başlatma örneği
// adres ve alan adları dokümantasyonunuzda

$apiKey = getenv('SANALPOS_API_KEY'); // anahtarı koda yazmayın; ortam değişkeninde tutun
$apiUrl = 'https://API_ADRESI/v1/payments';

$payload = [
    'amount'      => 150.00, // tutar biçimi (TL / kuruş) dokümantasyonunuzda
    'currency'    => 'TRY',
    'locale'      => 'tr',
    'installment' => 1,
    'callbackUrl' => 'https://siteniz.com/odeme/callback',
];

$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey,
    ],
]);

$response = curl_exec($ch);
$httpKodu = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($response === false || $httpKodu < 200 || $httpKodu >= 300) {
    error_log('odeme-baslat: HTTP ' . $httpKodu); // kart verisi ve anahtar günlüğe yazılmaz
    http_response_code(502);
    exit('Ödeme başlatılamadı');
}

$result = json_decode($response, true);

// 3D Secure yönlendirmesi gerekiyorsa
if (($result['status'] ?? null) === 'redirect') {
    header('Location: ' . $result['redirectUrl']);
    exit;
}

Ödeme Akışı ve Ayarlar

Yönlendirme, dönüş adresi ve sonucun kesinleştirilmesi.

Tutar, para birimi ve sipariş numarası her zaman sunucuda belirlenir; tarayıcıdan gelen değere güvenilmez. Ödeme isteği oluşturulduktan sonra kart sahibi bankanın doğrulama adımına yönlendirilir. Bu adımın nasıl işlediğini 3D Secure güvenli ödeme sayfasında bulabilirsiniz. Doğrulama tamamlandığında kullanıcı, projenizde tanımladığınız dönüş adresine geri döner.

Kullanıcının döndüğü sayfa sonucu göstermek için yeterlidir, ancak ödemeyi kesinleştirmek için yeterli değildir. Sonuç yalnızca sunucunuza gelen bildirimle kesinleşir: bildirim uç noktasında önce imza doğrulanır, sonra sipariş durumu güncellenir ve 200 yanıtı döndürülür. Aynı olay iki kez gelebileceğinden kaydın idempotent biçimde işlenmesi gerekir. Alan yapısı ve yeniden deneme davranışı için webhook ve callback sayfasına bakın.

Hata durumlarında kullanıcıya sade bir mesaj gösterilir, teknik ayrıntı yalnız günlüğe yazılır; günlüklerde kart numarası, CVV ve API anahtarı bulunmamalıdır. Akışı canlıya almadan önce test anahtarlarıyla deneyebilirsiniz; ayrıntı için sandbox ortamı ve test ortamı (sandbox) sayfalarını kullanın. Anahtarların tanımlanması için önce başvuru formunu doldurmanız gerekir.

Teknik gereksinimler

Sürüm bilgileri genel çerçevedir; kesin gereksinimler ve desteklenen sürümler, hesabınız açıldığında iletilen dokümantasyonda belirtilir.