İyzipay (Iyzico) Entegrasyonu

artiframe add iyzico eklentisi, Iyzico'nun resmi PHP SDK'sını kullanarak (iyzico/iyzipay-php) karmaşık Sanal POS, 3D Secure, Cüzdan (Card Vault) ve Pazaryeri (Marketplace) süreçlerini pürüzsüz tek bir sınıfa (src/Service/Iyzico.php) indirger. Tüm metotlar, API tarafında tutarlılık sağlaması için standart bir yanıt mimarisiyle (status, message, data) tasarlanmıştır.

1. Kurulum ve Yapılandırma

Terminal üzerinden eklentiyi projenize dahil edin:

terminal
$ artiframe add iyzico

Bu komut çalıştıktan sonra, proje kökündeki .env dosyanıza aşağıdaki değişkenler eklenecektir. Bu bilgileri Iyzico Sandbox veya canlı panelinizden alıp doldurmalısınız:

terminal
IYZICO_API_KEY=sandbox-api-key
IYZICO_SECRET_KEY=sandbox-secret-key
IYZICO_BASE_URL=https://sandbox-api.iyzipay.com
İpucu: Sınıfı çağırdığınızda (new Iyzico()) kimlik doğrulama işlemi arka planda otomatik olarak .env dosyasından okunur, \Iyzipay\Options nesnesi sizin yerinize oluşturulur.
2. Standart Ödeme Alma (Non-3D)

Kredi kartı bilgilerini alıp doğrudan çekim yapan metottur. Iyzico altyapısı, sepet kırılımlarını (items) ve alıcı (buyer) bilgilerini göndermeyi zorunlu kılar.

example.php
<?php
use Src\Service\Iyzico;

$iyzico = new Iyzico();

$response = $iyzico->pay([
    'price'       => 100.0,
    'paidPrice'   => 100.0,
    'currency'    => 'TRY',
    'installment' => 1,
    'card' => [
        'holder' => 'John Doe',
        'number' => '4546710000000000',
        'month'  => '12',
        'year'   => '2025',
        'cvc'    => '123'
    ],
    'buyer' => [
        'id'      => 'USR-100',
        'name'    => 'John',
        'surname' => 'Doe',
        'email'   => '[email protected]',
        'phone'   => '+905554443322',
        'ip'      => '85.34.78.112',
        'city'    => 'Istanbul',
        'country' => 'Turkey',
        'address' => 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
        'zipCode' => '34732'
    ],
    'items' => [
        ['id' => 'ITEM-1', 'name' => 'Premium Üyelik', 'category' => 'Subscription', 'price' => 50.0],
        ['id' => 'ITEM-2', 'name' => 'E-Kitap', 'category' => 'Digital', 'price' => 50.0]
    ]
]);

if ($response['status'] === 'success') {
    echo "Ödeme başarılı! Transaction ID: " . $response['data']['paymentId'];
} else {
    echo "Hata: " . $response['message'];
}
Parametre Detayları
ParametreTürAçıklama
price ZorunlufloatSepetin asıl tutarı.
paidPrice ZorunlufloatMüşteriden tahsil edilecek son tutar (Vade farkı dahil).
installment OpsiyonelintTaksit sayısı. Tek çekim için 1 gönderin.
card.number ZorunlustringKredi kartı numarası. Boşluksuz 16 hane.
Edge Case: Sepet Toplamı Uyuşmazlığı
Iyzico, gönderilen items dizisindeki ürünlerin price değerleri toplamının, ana price parametresine kuruşu kuruşuna eşit olmasını bekler. Farklıysa API direkt hata fırlatır.
3. 3D Secure Ödeme Akışı

3D Secure işlemi 2 aşamalı asenkron bir akıştır. Önce Iyzico'ya istek atılarak bankanın SMS doğrulama formu oluşturulur, kullanıcı doğruladıktan sonra dönüş URL'sinde yakalanır.

Adım 3.1: 3D Secure Başlatma (Init)

Normal pay() parametrelerine ek olarak callbackUrl eklemeniz yeterlidir.

example.php
<?php
$response = $iyzico->threeDSecureInit([
    // ... pay() metodundaki price, card, buyer ve items parametreleri 
    'callbackUrl' => 'https://siteniz.com/payment/callback'
]);

if ($response['status'] === 'success') {
    // Iyzico'dan dönen base64 şifreli HTML formu ekrana basılır. 
    // Kullanıcı otomatik olarak bankaya (3D ekranına) yönlenir.
    echo $response['data']['threeDSHtmlContent'];
    exit;
}
Adım 3.2: 3D Dönüşü (Complete)

Kullanıcı bankadan SMS doğrulamasını yaptıktan sonra Iyzico, verdiğiniz callbackUrl adresine bir POST isteği atar.

example.php
<?php
// Route: /payment/callback (POST)
$paymentId = $_POST['paymentId'] ?? null;
$conversationId = $_POST['conversationId'] ?? null;

$response = $iyzico->threeDSecureComplete([
    'paymentId' => $paymentId
]);

if ($response['status'] === 'success') {
    $paymentDetails = $response['data'];
    echo "Ödeme onaylandı! Tutar: " . $paymentDetails['paidPrice'];
} else {
    echo "3D Doğrulama başarısız: " . $response['message'];
}
4. Kart Saklama (Card Vault)

Kullanıcılarınızın "Kartımı Kaydet" seçeneğini kullanabilmesi içindir. Kart verileri sizin veritabanınızda değil, Iyzico'nun PCI-DSS uyumlu sunucularında saklanır.

Yeni Kart Kaydetmek
example.php
<?php
$response = $iyzico->saveCard([
    'holder' => 'Jane Doe',
    'number' => '4546710000000000',
    'month'  => '12',
    'year'   => '2025',
    'alias'  => 'İş Bankası Kartım'
], '[email protected]'); // E-posta adresi External Identifier olarak kullanılır.

if ($response['status'] === 'success') {
    // Bu değerleri veritabanınızdaki 'user_cards' tablosunda saklayın
    $cardUserKey = $response['data']['cardUserKey']; // Kullanıcının Cüzdan ID'si
    $cardToken   = $response['data']['cardToken'];   // Bu Spesifik Kartın ID'si
}
Kayıtlı bir kartla ödeme almak için, normal pay() metodundaki card dizisine kart numarası vs. vermek yerine, doğrudan kaydettiğiniz cardUserKey ve cardToken parametrelerini göndermeniz yeterlidir. Iyzico arka planda tanıyacaktır.
Kullanıcının Kartlarını Listeleme
example.php
<?php
// DB'den aldığınız cardUserKey'i gönderin
$response = $iyzico->listCards($cardUserKey);

if ($response['status'] === 'success') {
    foreach ($response['data']['cards'] as $card) {
        echo $card['cardAlias'] . ' : ' . $card['binNumber'] . '***' . $card['lastFourDigits'];
    }
}
5. İptal ve İade (Cancel & Refund) İşlemleri
Tüm Siparişi İptal Etmek (Cancel)

Aynı gün içinde gün sonu alınmadan (gece 23:59'dan önce) yapılan işlemlerdir. Komisyon kesilmeden tam iade yapılır.

example.php
<?php
$response = $iyzico->cancel('12345678'); // Ana PaymentId

if ($response['status'] === 'success') {
    echo "Ödeme tamamen iptal edildi.";
}
Kısmi / Ürün Bazlı İade (Refund)

Gün sonu alındıktan sonra veya sepetin sadece belli bir ürününü iade etmek için kullanılır. Ana ödeme ID'sini değil, ürün bazlı paymentTransactionId gerektirir.

example.php
<?php
// 100 TL'lik sepetin içindeki 50 TL'lik tek bir ürünü iade et
$response = $iyzico->refund('TXN-99887766', 50.0);

if ($response['status'] === 'success') {
    echo "İade (Refund) işlemi başarılı.";
}
6. Pazaryeri (Marketplace) Alt Üye İşyeri

Satıcılarınıza (Sub-Merchant) ödeme dağıtmak için onları sisteme kaydetmeniz gerekir.

example.php
<?php
$response = $iyzico->createSubMerchant([
    'name'             => 'Ahmet Yılmaz',
    'type'             => 'PERSONAL_COMPANY', // Şahıs şirketi
    'legalCompanyName' => 'Ahmet Yılmaz E-Ticaret',
    'taxOffice'        => 'Kadıköy',
    'taxNumber'        => '11122233344', // Şahıs ise TCKN, şirket ise VKN
    'email'            => '[email protected]',
    'phone'            => '+905551234567',
    'address'          => 'Moda Cad. No:1 Kadıköy / Istanbul',
    'iban'             => 'TR120000000000000000000000',
    'subMerchantExternalId' => 'SATICI-001' // Kendi DB'nizdeki Satıcı ID'si
]);

if ($response['status'] === 'success') {
    // Bu key'i veritabanında satıcıya (vendor) kaydedin.
    // Sepet kırılımında (items) 'subMerchantKey' ve 'subMerchantPrice' olarak kullanacaksınız.
    $subMerchantKey = $response['data']['subMerchantKey'];
}