2026'da iPay API ile Ödeme Entegrasyonu Nasıl Yapılır?

ÖZET

iPay API, geliştiricilerin ödeme işleme, faturalama ve finansal işlemleri programatik olarak entegre etmelerini sağlar. OAuth 2.0 ve API anahtarı kimlik doğrulamasını, ödemeler, iadeler, işlemler ve mutabakat için RESTful uç noktalarını kullanır; PCI DSS uyumluluk gereksinimleri ve endüstri standardı oran sınırlamalarıyla birlikte gelir. Bu kılavuz, kimlik doğrulama kurulumunu, ödeme işlemeyi, webhook entegrasyonunu, güvenlik uyumluluğunu ve üretim dağıtım stratejilerini kapsar.

Giriş

Dijital ödeme işlemleri dünya genelinde yıllık 8 trilyon doların üzerinde bir hacme sahiptir. E-ticaret platformları, SaaS uygulamaları veya pazar yeri çözümleri geliştirenler için ödeme API entegrasyonu isteğe bağlı değildir; müşteri ödemelerini güvenli ve uyumlu bir şekilde kabul etmek için zorunludur.

Gerçek şu ki: işletmeler başarısız ödemeler, manuel mutabakat ve ödeme dolandırıcılığı nedeniyle gelirlerinin %5-10'unu kaybediyor. Sağlam bir ödeme API entegrasyonu, ödeme işlemlerini otomatikleştirir, akıllı yeniden deneme mantığıyla başarısızlıkları azaltır, otomatik mutabakatı sağlar ve dolandırıcılık tespitini uygular.

Bu kılavuz, eksiksiz ödeme API entegrasyon sürecini adım adım anlatmaktadır. Kimlik doğrulama kurulumunu, ödeme işlemeyi, iade yönetimini, webhook işlemeyi, PCI DSS uyumluluğunu, güvenlik en iyi uygulamalarını ve üretim dağıtım stratejilerini öğreneceksiniz. Sonunda, üretime hazır bir ödeme entegrasyonuna sahip olacaksınız.

Not: Bu kılavuz, iPay ve benzeri ödeme işlemcileri için geçerli genel ödeme API entegrasyon modellerini kapsar. Belirli uç nokta URL'leri ve kimlik doğrulama detayları değişebilir; uygulama ayrıntıları için her zaman resmi iPay dokümantasyonuna başvurun.

iPay API Nedir?

iPay gibi ödeme API'leri, finansal işlemleri işlemek için RESTful arayüzler sunar. API şunları yönetir:

• Ödeme yetkilendirme ve yakalama
• İadeler ve ters ibrazlar
• İşlem geçmişi ve raporlama
• Müşteri tokenizasyonu (kasa)
• Abonelik ve yinelenen faturalandırma
• Fatura oluşturma ve yönetimi
• Mutabakat ve uzlaşma
• Dolandırıcılık tespiti ve önlenmesi

Temel Özellikler

Ödeme Akışına Genel Bakış

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Müşteri   │───▶│   Satıcı    │───▶│   Ödeme     │
│  (Tarayıcı) │    │  (Sunucu)   │    │  Ağ Geçidi  │
└─────────────┘    └─────────────┘    └─────────────┘
     │                    │                    │
     │  1. Kart Girin     │                    │
     │───────────────────▶│                    │
     │                    │                    │
     │  2. Tokenize Et    │                    │
     │───────────────────▶│  3. Niyet Oluştur  │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  4. Ödemeyi Onayla │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  5. Sonuç          │
     │                    │◀───────────────────│
     │                    │                    │
     │  6. Makbuz         │                    │
     │◀───────────────────│                    │

API Ortamı

Başlarken: Kimlik Doğrulama Kurulumu

Adım 1: iPay Hesabı Oluşturma

API'ye erişmeden önce:

1. iPay satıcı kaydını ziyaret edin
2. İşletme doğrulamasını (KYB) tamamlayın
3. Gerekli belgeleri gönderin:

• İşletme kaydı
• Banka hesabı detayları
• Resmi Kimlik

1. Onayı bekleyin (1-3 iş günü)

Adım 2: API Kimlik Bilgilerini Alın

API kimlik bilgilerini oluşturun:

1. iPay Satıcı Paneli'ne giriş yapın
2. Ayarlar > API Anahtarları bölümüne gidin
3. Yeni API anahtarı oluşturun
4. Kimlik bilgilerini güvenli bir şekilde kopyalayın

# .env dosyası (ASLA git'e eklemeyin)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

Güvenlik notu: Test ortamı ve üretim ortamı için ayrı anahtarlar kullanın.

Adım 3: Kimlik Doğrulama Yöntemlerini Anlayın

iPay birden fazla kimlik doğrulama yöntemini destekler:

Adım 4: Kimlik Doğrulanmış API Çağrıları Yapın

Yeniden kullanılabilir API istemcisi oluşturun:

const IPAY_BASE_URL = process.env.IPAY_SANDBOX
  ? 'https://sandbox.ipay.com/api'
  : 'https://api.ipay.com/api';

const ipayRequest = async (endpoint, options = {}) => {
  const apiKey = process.env.IPAY_API_KEY;
  const apiSecret = process.env.IPAY_API_SECRET;

  // Temel kimlik doğrulama (Base64 kodlamalı)
  const authHeader = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

  const response = await fetch(`${IPAY_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${authHeader}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': options.idempotencyKey || generateIdempotencyKey(),
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`iPay API Hatası: ${error.message}`);
  }

  return response.json();
};

function generateIdempotencyKey() {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

// Kullanım
const account = await ipayRequest('/account');
console.log(`Satıcı: ${account.business_name}`);

Ödeme İşleme

Ödeme Niyeti Oluşturma

Ödemeyi başlatın:

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // En küçük para birimi biriminde (kuruş)
    currency: paymentData.currency || 'USD',
    customer: paymentData.customerId,
    payment_method: paymentData.paymentMethodId,
    confirm: true,
    description: paymentData.description,
    metadata: {
      orderId: paymentData.orderId,
      customerId: paymentData.customerId
    },
    capture_method: paymentData.captureMethod || 'automatic', // 'otomatik' veya 'manuel'
    statement_descriptor: paymentData.statementDescriptor || 'MYCOMPANY'
  };

  const response = await ipayRequest('/payments', {
    method: 'POST',
    body: JSON.stringify(payment),
    idempotencyKey: paymentData.idempotencyKey
  });

  return response;
};

// Kullanım
const payment = await createPayment({
  amount: 2999, // $29.99
  currency: 'USD',
  customerId: 'cus_12345',
  paymentMethodId: 'pm_67890',
  description: 'Sipariş #ORD-001',
  orderId: 'ORD-001',
  statementDescriptor: 'MYCOMPANY INC'
});

console.log(`Ödeme durumu: ${payment.status}`);
console.log(`Ödeme ID: ${payment.id}`);

Ödeme Durumu Akışı

requires_payment_method → requires_confirmation → requires_action
                         → processing → requires_capture → succeeded
                                                        → failed
                                                        → canceled

Ödeme Yöntemleri

Kart Bilgilerini Tokenize Etme

Kartı gelecekteki kullanımlar için güvenli bir şekilde saklayın:

const tokenizeCard = async (cardData) => {
  // Ham kart verilerini ASLA sunucunuza göndermeyin
  // Bunun yerine istemci tarafı tokenizasyon kullanın

  // İstemci tarafı (tarayıcı/mobil)
  const response = await fetch(`${IPAY_BASE_URL}/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CLIENT_PUBLISHABLE_KEY}`
    },
    body: JSON.stringify({
      card: {
        number: cardData.number,
        exp_month: cardData.expMonth,
        exp_year: cardData.expYear,
        cvc: cardData.cvc
      }
    })
  });

  const token = await response.json();
  return token; // token.id'yi sunucunuza gönderin
};

// Sunucu tarafı: Token'ı ödeme yöntemi oluşturmak için kullanın
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};

3D Secure Kimlik Doğrulaması

SCA uyumluluğunu uygulayın:

const createPaymentWith3DS = async (paymentData) => {
  const payment = await createPayment({
    ...paymentData,
    confirmation_token: true // 3DS için istemci sırrını döndür
  });

  if (payment.status === 'requires_action') {
    // İstemci 3DS meydan okumasını tamamlamalıdır
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// İstemci tarafı: 3DS meydan okumasını ele alın
// Kimlik doğrulama meydan okumasını sunmak için iPay.js veya mobil SDK kullanın

İade Yönetimi

Tam İade İşleme

Ödemenin tamamını iade edin:

const refundPayment = async (paymentId, reason = null) => {
  const refund = {
    payment: paymentId,
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${Date.now()}`
  });

  return response;
};

// Kullanım
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`İade durumu: ${refund.status}`);
console.log(`İade ID: ${refund.id}`);

Kısmi İade İşleme

Ödemenin bir kısmını iade edin:

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // En küçük para birimi biriminde
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${amount}_${Date.now()}`
  });

  return response;
};

// Kullanım - 29.99$ tutarındaki ödemenin 15.00$'ını iade edin
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`İade edilen: $${refund.amount / 100}`);

İade Nedenleri

Müşteri Yönetimi

Müşteri Oluşturma

Tekrarlayan ödemeler için müşteriyi saklayın:

const createCustomer = async (customerData) => {
  const customer = {
    email: customerData.email,
    name: customerData.name,
    phone: customerData.phone,
    metadata: {
      internalId: customerData.internalId,
      tier: customerData.tier
    }
  };

  const response = await ipayRequest('/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Kullanım
const customer = await createCustomer({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1-555-0123',
  internalId: 'USR-12345',
  tier: 'premium'
});

console.log(`Oluşturulan müşteri: ${customer.id}`);

Ödeme Yöntemini Müşteriye Bağlama

Kartı gelecekteki kullanımlar için kaydedin:

const attachPaymentMethod = async (paymentMethodId, customerId) => {
  const response = await ipayRequest(`/payment_methods/${paymentMethodId}/attach`, {
    method: 'POST',
    body: JSON.stringify({
      customer: customerId
    })
  });

  return response;
};

// Kullanım
await attachPaymentMethod('pm_67890', 'cus_12345');

Müşteri Ödeme Yöntemlerini Listeleme

Kaydedilen kartları alın:

const getCustomerPaymentMethods = async (customerId) => {
  const response = await ipayRequest(`/customers/${customerId}/payment_methods`);
  return response;
};

// Kullanım
const methods = await getCustomerPaymentMethods('cus_12345');
methods.data.forEach(method => {
  console.log(`${method.card.brand} ${method.card.last4} ile bitiyor`);
  console.log(`Son kullanma tarihi: ${method.card.exp_month}/${method.card.exp_year}`);
});

Webhook'lar

Webhook'ları Yapılandırma

Webhook uç noktalarını kurun:

1. iPay Paneli'ne giriş yapın
2. Geliştiriciler > Webhook'lar bölümüne gidin
3. Uç Nokta Ekle'ye tıklayın
4. HTTPS URL'nizi girin
5. Abone olunacak olayları seçin

Webhook Olayları

Webhook'ları Yönetme

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/ipay', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['ipay-signature'];
  const payload = req.body;

  // Webhook imzasını doğrulayın
  const isValid = verifyWebhookSignature(payload, signature, process.env.IPAY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Geçersiz webhook imzası');
    return res.status(401).send('Yetkisiz');
  }

  const event = JSON.parse(payload.toString());

  // Uygun işleyiciye yönlendirin
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.refunded':
      await handlePaymentRefunded(event.data);
      break;
    case 'payment.disputed':
      await handlePaymentDisputed(event.data);
      break;
    default:
      console.log('İşlenmeyen olay türü:', event.type);
  }

  // Alındığını onaylayın
  res.status(200).send('Tamam');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

async function handlePaymentSucceeded(data) {
  console.log(`Ödeme başarılı: ${data.id}`);

  // Sipariş durumunu güncelleyin
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Onay e-postası gönderin
  await sendOrderConfirmation(data.metadata.orderId);
}

async function handlePaymentFailed(data) {
  console.log(`Ödeme başarısız: ${data.id} - ${data.failure_code}`);

  // Müşteriyi bilgilendirin
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Yeniden deneme mantığı veya siparişi başarısız olarak işaretle
  await db.orders.update(data.metadata.orderId, {
    status: 'payment_failed',
    failureReason: data.failure_message
  });
}

Güvenlik ve Uyumluluk

PCI DSS Gereksinimleri

Ödeme entegrasyonları PCI DSS'ye uymalıdır:

Güvenlik En İyi Uygulamaları

// 1. Tokenizasyon kullanın - ASLA ham kart verilerini işlemeyin
const token = await tokenizeCard(cardData); // İstemci tarafı

// 2. Tüm ödeme işlemleri için idempotentlik uygulayın
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Tutarları sunucu tarafında doğrulayın
if (req.body.amount !== calculatedAmount) {
  throw new Error('Tutar uyumsuzluğu - olası kurcalama');
}

// 4. Tüm ödeme işlemlerini günlüğe kaydedin (hassas veriler olmadan)
logger.info('Ödeme denendi', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // ASLA günlüğe kaydetmeyin: kart numaraları, CVV, tam ödeme yöntemi detayları
});

// 5. Sırlar için ortam değişkenleri kullanın
const apiKey = process.env.IPAY_API_KEY; // Sabit kodlanmamış

// 6. Ödeme uç noktalarında oran sınırlaması uygulayın
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // Dakikada 10 ödeme denemesi
});

Üretim Dağıtım Kontrol Listesi

Canlı ödemeleri işlemeden önce:

• [ ] PCI DSS Öz Değerlendirme Anketini Tamamlayın
• [ ] Tüm uç noktalar için HTTPS kullanın
• [ ] API anahtarlarını güvenli sır yönetiminde saklayın
• [ ] Webhook imza doğrulamasını uygulayın
• [ ] Tüm ödeme işlemleri için idempotentlik ekleyin
• [ ] Kapsamlı günlükleme kurun (hassas veri yok)
• [ ] Dolandırıcılık tespit kurallarını yapılandırın
• [ ] İade ve ters ibraz akışlarını test edin
• [ ] Ödeme hataları için çalışma kitabı oluşturun
• [ ] İzleme ve uyarı sistemini kurun
• [ ] Yedek ödeme işlemcisi uygulayın

Gerçek Dünya Kullanım Senaryoları

E-ticaret Ödeme İşlemi

Bir çevrimiçi perakendeci ödemeleri entegre eder:

• Zorluk: Manuel ödeme işleme, yüksek terk edilme oranları
• Çözüm: Tokenize edilmiş kartlarla tek sayfalık ödeme
• Sonuç: %35 dönüşüm artışı, anında ödemeler

SaaS Abonelik Faturalandırması

Bir yazılım şirketi faturalandırmayı otomatikleştiriyor:

• Zorluk: Manuel fatura oluşturma ve tahsilat
• Çözüm: Otomatik yeniden deneme ile yinelenen ödemeler
• Sonuç: %95 zamanında ödeme, %80 yönetim süresi tasarrufu

Pazar Yeri Emanet (Escrow)

Bir platform çok taraflı ödemeleri yönetir:

• Zorluk: Satıcılar arasında karmaşık bölünmüş ödemeler
• Çözüm: Transfer zamanlaması ile ödeme niyetleri
• Sonuç: Otomatik satıcı ödemeleri, dolandırıcılıkta azalma

Sonuç

Ödeme API entegrasyonu, güvenlik, uyumluluk ve hata yönetimine dikkatli bir yaklaşım gerektirir. Temel çıkarımlar:

• Ham kart verilerini asla işlemeyin – tokenizasyon kullanın
• Tüm ödeme işlemleri için idempotentlik uygulayın
• Dolandırıcılığı önlemek için webhook imzalarını doğrulayın
• PCI DSS gereksinimlerine uyun
• Üretim öncesi test ortamında kapsamlı test yapın
• Apidog, API testini ve ekip işbirliğini kolaylaştırır

Sıkça Sorulan Sorular

iPay API ile nasıl kimlik doğrulaması yaparım?

API anahtarı ve gizli anahtar ile Temel kimlik doğrulamasını veya çok kiracılı uygulamalar için OAuth 2.0'ı kullanın.

Müşteri kart bilgilerini saklayabilir miyim?

Evet, ancak PCI DSS uyumlu olmanız gerekir. Kartları iPay'in kasasında güvenli bir şekilde saklamak için tokenizasyon kullanın.

Başarısız ödemeleri nasıl yönetirim?

Üstel geri çekilmeyle yeniden deneme mantığı uygulayın, müşterileri bilgilendirin ve alternatif ödeme yöntemleri sunun.

İdempotentlik nedir ve neden önemlidir?

İdempotentlik, aynı anahtara sahip yinelenen isteklerin aynı sonucu üretmesini sağlayarak yinelenen tahsilatları önler.

Kartları tahsil etmeden ödemeleri nasıl test ederim?

iPay dokümantasyonunda sağlanan test kart numaralarıyla sanal ortam modunu kullanın.

Webhook imzaları nelerdir?

Webhook'ların kötü niyetli bir aktörden değil, iPay'den geldiğini doğrulayan kriptografik imzalardır.