E-Ticarette iyzico Entegrasyonu Nasıl Çalışır?

Bu rehber iyzico Checkout Form sonucunu PHP sunucusunda sorgulama adımını gösterir. Tarayıcının başarı URL'sine gelmesi siparişi ödendi yapmamalı. Form başlatma sırasında üretilen token'ı kendi ödeme denemenize kaydetmiş olmanız gerekir.

1. Sandbox ortamını ayırın

Resmî PHP SDK'sını Composer projenize ekleyin. Paketin PHP gereksinimlerini kontrol edin ve composer.lock dosyasını sürüm kontrolünde tutun.

composer require iyzico/iyzipay-php

API anahtarlarını sunucu ortamında IYZICO_API_KEY ve IYZICO_SECRET_KEY olarak tanımlayın. Sandbox anahtarıyla sandbox API, canlı anahtarla canlı API kullanılmalı; ikisini aynı ayar grubunda karıştırmayın. Aşağıdaki örnek yalnız sandbox sonucunu okumak içindir.

2. Callback token'ıyla sonucu sorgulayın

Checkout Form callback adresinize POST edilen token'ı alın. Bu parça PHP 8.x ve Composer autoload bulunan endpoint içinde çalışır. Token'ı ayrıca kendi kaydettiğiniz ödeme denemesiyle eşleştirmeden sipariş durumunu değiştirmeyin.

<?php
require __DIR__ . '/vendor/autoload.php';
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    http_response_code(405); exit;
}
$token = $_POST['token'] ?? null;
if (!is_string($token) || $token === '' || strlen($token) > 2048) {
    http_response_code(400); exit;
}
$apiKey = getenv('IYZICO_API_KEY');
$secret = getenv('IYZICO_SECRET_KEY');
if (!$apiKey || !$secret) { http_response_code(503); exit; }
$options = new \Iyzipay\Options();
$options->setApiKey($apiKey);
$options->setSecretKey($secret);
$options->setBaseUrl('https://sandbox-api.iyzipay.com');
$request = new \Iyzipay\Request\RetrieveCheckoutFormRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setToken($token);
try {
    $result = \Iyzipay\Model\CheckoutForm::retrieve($request, $options);
    $successful = $result->getStatus() === 'success'
        && $result->getPaymentStatus() === 'SUCCESS';
    // Bu örnek bilgi döndürür; siparişi ÖDENDİ olarak güncellemez.
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(['provider_success' => $successful]);
} catch (\Throwable $e) {
    http_response_code(503);
    echo 'Sonuç şu anda doğrulanamadı.';
}

Autoload yolunu kendi proje kökünüze göre değiştirin. API sonucu, callback gövdesindeki bir başarı iddiasından daha güçlü kanıttır; yine de token/sipariş ilişkisi, basketId, beklenen tutarlar, para birimi ve sağlayıcının desteklediği imza doğrulaması tamamlanmadan stok/kargo işlemi başlatmayın. Ham yanıtı müşteri ekranına veya herkese açık loga basmayın.

3. Tekrarlı bildirimi güvenli işleyin

Ödeme denemesi için token/provider payment id üzerinde benzersizlik kısıtı kurun. Veritabanı transaction'ında siparişi kilitleyip sadece uygun bekleyen durumdan ödendiye geçirin. Aynı doğrulanmış sonuç ikinci kez geldiğinde ikinci stok düşümü veya fatura oluşmamalı. Kargo/e-posta gibi dış işlemleri transaction sonrası tekil outbox işiyle tetikleyin.

4. Hatalı ve belirsiz durumları ayırın

Banka reddi, kullanıcı iptali ve API timeout farklıdır. Timeout'ta doğrudan yeni tahsilat başlatmayın; mevcut denemeyi sağlayıcıdan tekrar sorgulayıp uzlaştırın. Yanlış üye işyeri/anahtar hatasında müşteriyi tekrar tekrar kart girmeye yönlendirmek yerine yöneticiye hata koduyla bildirim üretin.

Kabul testi

Sandbox'ta başarılı, reddedilen, 3D iptal ve tekrar callback denemelerini yapın. Aynı token'ın başka siparişe bağlanması reddedilmeli. Ödeme başarılı olup tarayıcı kapanırsa sunucu uzlaşması siparişi tamamlayabilmeli. Canlıya geçerken endpoint ve anahtarları birlikte değiştirip küçük kontrollü testinizi sağlayıcının prosedürüyle yapın.