PHP projelerinde ödeme akışını kurarken SDK, istek imzalama, oturum ve token yönetimi, yanıt ayrıştırma gibi tekrar eden işleri üstlenir. Aşağıdaki bölümler kurulumdan canlıya geçişe kadar izlenen sırayı özetler.
Paket adı ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir. Uç nokta ve alan yapısı için API dokümantasyonu sayfasına bakın.
Hangi PHP sürümleriyle çalışır?
Sürüm desteği ve bağımlılıklar seçilen ödeme kuruluşunun çözümüne göre değişir; kesin liste hesabınız açıldığında iletilen dokümantasyonda yer alır.
Kodumu canlıya almadan deneyebilir miyim?
Evet. Test anahtarlarıyla akışı uçtan uca çalıştırabilirsiniz; ayrıntılar için test ortamı (sandbox) ve test kartları sayfalarına bakın.
Ödeme sonucunu nasıl kesinleştiririm?
Tarayıcıdan dönen yanıtla değil, sunucunuza gelen bildirimle. Alanlar ve imza doğrulaması için webhook ve callback sayfasını kullanın.
SDK, Composer ile projeye bağımlılık olarak eklenir. Aşağıdaki paket adı yer tutucudur; gerçek paket adı ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir. Desteklenen PHP sürümleri ve bağımlılıklar da seçilen ödeme kuruluşunun çözümüne göre değişir.
bash
# 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>
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.
php
<?php
require __DIR__ . '/vendor/autoload.php';
// Sınıf ve metot adları örnektir; karşılıkları dokümantasyonunuzdadır
$istemci = new Saglayici\SanalPos\Client([
'api_key' => getenv('SANALPOS_API_KEY'),
'api_secret' => getenv('SANALPOS_API_SECRET'),
'ortam' => getenv('SANALPOS_ORTAM'), // test | canli
]);
Temel Ödeme Akışı
Tipik akış üç adımdır: ödeme isteğinin sunucudan oluşturulması, kart sahibinin 3D Secure doğrulamasına yönlendirilmesi ve dönüşte sonucun sunucu tarafında doğrulanması. Tutar, para birimi ve sipariş numarası her zaman sunucuda belirlenir; tarayıcıdan gelen değere güvenilmez.
php
<?php
$sonuc = $istemci->odeme()->baslat([
'siparis_no' => 'SIP-10245',
'tutar' => 149.90,
'para_birimi' => 'TRY',
'donus_url' => 'https://ornek-site.com/odeme/donus',
]);
// 3D Secure doğrulaması için kart sahibi yönlendirilir
header('Location: ' . $sonuc->yonlendirmeUrl);
Aynı sipariş için istek tekrarlanabildiğinden sipariş numarası benzersiz üretilmeli, kayıt çift oluşmayacak biçimde işlenmelidir. Alan adları ile desteklenen işlemler (iade, iptal, taksit) seçilen çözüme göre değişir.
Webhook ve Hata Yönetimi
Ödemenin başarılı sayılması, tarayıcının döndüğü sayfaya değil sunucunuza gelen bildirime bağlıdır. Bildirim uç noktasında önce imza doğrulanır, sonra sipariş durumu güncellenir ve 200 yanıtı döndürülür; aksi hâlde bildirim yeniden gönderilebilir.
php
<?php
$govde = file_get_contents('php://input');
$imza = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
if (!$istemci->webhook()->imzaDogrula($govde, $imza)) {
http_response_code(400);
exit;
}
$olay = json_decode($govde, true);
// Aynı olay iki kez gelebilir: durumu idempotent güncelleyin
siparisDurumunuGuncelle($olay['siparis_no'], $olay['durum']);
http_response_code(200);
Hata durumlarında SDK'nın fırlattığı istisnalar yakalanır, 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. Dönen kodların karşılığı için POS hata kodları sayfasına bakın; bildirim alanları ve yeniden deneme davranışı webhook ve callback sayfasında açıklanır.
Test ve Canlıya Geçiş
Entegrasyon önce test anahtarlarıyla doğrulanır: başarılı ödeme, yetersiz bakiye, CVV hatası ve 3D Secure adımı denenir. Ayrıntılar test ortamı (sandbox) ve test kartları sayfalarındadır.
Akış doğrulandıktan sonra yalnız ortam ve anahtar değerleri canlıya çevrilir; kod yapısı aynı kalır. Adım adım kurulum için entegrasyon kılavuzu, uç nokta ve alan referansı için API dokümantasyonu, hazır örnekler için örnek kodlar sayfalarını kullanın. Diğer diller için Node.js ve Python SDK sayfalarına, genel yetenekler için API ve SDK entegrasyonu sayfasına bakabilirsiniz.
