Bu makalede PayTR Direkt API kullanarak ödeme formundan doğrudan ödeme almayı adım adım anlatacağız. Sunucu tarafında doğrulama, token üretimi, form verilerinin doğru gönderilmesi ve ödeme başarı durumlarını ele alacağız.

Bağlantılı Rehberler:

Direkt API Entegrasyonu Çalışma Mantığı

Müşteri ürün/hizmet almak ister.
Ödeme formuna bilgilerini girer.
Token üretilir ve bilgiler PayTR'a doğrudan POST edilir.
PayTR, verileri kontrol eder ve müşteriyi başarılı/başarısız sayfaya yönlendirir.

1) Token Nasıl Üretilir?

Gerekli Alanlar:

merchant_id
user_ip
merchant_oid
email
payment_amount
payment_type ('card')
installment_count
currency (Varsayılan TL)
test_mode
non_3d

PHP Token Hesaplama Örneği:

$hash_str = $merchant_id . $user_ip . $merchant_oid . $email . $payment_amount . $payment_type . $installment_count . $currency . $test_mode . $non_3d;
$paytr_token = base64_encode(hash_hmac('sha256', $hash_str.$merchant_salt, $merchant_key, true));

Not: Base64 ile HMAC SHA256 hash şifreleme zorunludur.

2) POST İsteğinde Gönderilmesi Gerekenler

Alan Adı	Açıklama
merchant_id	Mağaza ID
paytr_token	Üretmiş olduğunuz token
user_ip	Müşteri IP adresi
merchant_oid	Sipariş numarası
email	Müşteri email adresi
payment_type	'card'
payment_amount	Ödeme tutarı
installment_count	Taksit sayısı
cc_owner	Kart sahibi
card_number	Kart numarası
expiry_month	Ay
expiry_year	Yıl
cvv	CVV
merchant_ok_url	Başarılı yönlendirme URL
merchant_fail_url	Başarısız yönlendirme URL
user_name	Müşteri adı
user_address	Adres
user_phone	Telefon numarası
user_basket	JSON sepet verisi

3) Ödeme Formu Hazırlama (PHP HTML Örneği)

<form action="https://www.paytr.com/odeme" method="post">
    <input type="text" name="cc_owner" value="TEST KARTI">
    <input type="text" name="card_number" value="9792030394440796">
    <input type="text" name="expiry_month" value="12">
    <input type="text" name="expiry_year" value="99">
    <input type="text" name="cvv" value="000">
    <!-- Diğer zorunlu gizli inputlar -->
    <input type="hidden" name="merchant_id" value="..."><!-- vb. -->
    <input type="submit" value="Ödeme Yap">
</form>

4) Sync Mode (Eğer Kullanılacaksa)

sync_mode=1 gönderilirse, ödeme sonucu JSON formatında anlık döner.
"status": "success" veya "failed" veya "wait_callback" değerleri alabilirsiniz.
Daha hızlı entegre olan, modern ödeme deneyimi sunar.

Sync Mode JSON Yanıt Örneği:

{
  "status": "success",
  "msg": "Ödeme Başarılı",
  "utoken": "...", // Kart saklama yapıldıysa
  "ctoken": "..."
}

5) Bildirim URL ve Ödeme Sonuçları

Müşteri merchant_ok_url'e giderse bile, sipariş onaylanmış olmaz!
Asıl doğrulama Bildirim URL üzerinden server-side POST verisiyle gelir.
POST ile gelen değerlerde status=success ise siparişi onaylayabilirsiniz.

6) Dikkat Edilmesi Gerekenler

Kart bilgileri sadece PayTR'a POST edilmelidir. Kendi sunucunuza kesinlikle kaydetmeyin.
IP adresini almakta sorun yaşarsanız "REMOTE_ADDR" değerini kontrol edin.
Test ortamında dahi "SSL/TLS" aktif olmalı.
Hata ayıklamak için debug_on=1 gönderin.

Sık Yapılan Hatalar ve Çözümler

Sorun	Sebep	Çözüm
"bad hash" hatası	Yanlış hash hesaplama	HMAC SHA256 ve base64 encoding kontrol edin
Ödeme formu hata veriyor	Eksik alan	Tüm zorunlu alanları gönderdiğinize emin olun
Müşteri merchant_ok_url'e giderken sipariş onaylanmıyor	Bildirim URL'den onay bekleniyor	Bildirim URL'yi doğru kodlayın

Sonuç: Direkt API ile Kontrol Sizde!

PayTR Direkt API entegrasyonu, ödeme sürecini tamamen kendi sayfanızda kontrol edebilmenizi sağlar. Özellikle taksitli işlemler ve non-3D Secure işlem opsiyonları ile daha esnek bir entegrasyon deneyimi sunar.

Bağlantılı Makaleler: