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

ÖZET

iPay API, ödeme işlemleri, faturalama ve finansal işlemleri programatik olarak entegre etmenizi sağlar. OAuth 2.0 ve API anahtarı kimlik doğrulaması, ödemeler, iadeler, işlemler ve mutabakat için RESTful uç noktalar sunar; ayrıca PCI DSS uyumluluğu ve endüstri standardı oran sınırlamaları ile gelir. Bu rehberde kimlik doğrulama kurulumu, ödeme işleme, webhook entegrasyonu, güvenlik uyumluluğu ve üretim dağıtım stratejileri adım adım ele alınmaktadır.

Apidog’u bugün deneyin

Giriş

Dijital ödeme işlemleri dünya çapında yıllık 8 trilyon dolardan fazla hacme ulaşıyor. E-ticaret, SaaS uygulamaları veya pazar yerleri geliştiriyorsanız, ödeme API entegrasyonu zorunludur; müşteri ödemelerini güvenli ve uyumlu şekilde kabul etmek için gereklidir.

Gerçek şu: İşletmeler başarısız ödemeler, manuel mutabakat ve ödeme dolandırıcılığı nedeniyle gelirlerinin %5-10'unu kaybediyor. Güçlü bir ödeme API entegrasyonu, işlemleri otomatikleştirir, başarısızlıkları azaltır, otomatik mutabakat sağlar ve dolandırıcılık tespitini uygular.

Bu rehber, eksiksiz ödeme API entegrasyonunu uygulamaya yönelik adım adım teknik talimatlar sunar. Kimlik doğrulama, ödeme işleme, iade yönetimi, webhook işlemesi, PCI DSS uyumluluğu, güvenlik en iyi uygulamaları ve üretime dağıtım stratejilerini öğrenecek ve sonunda üretime hazır bir entegrasyon oluşturacaksınız.

💡 Apidog, ödeme API testlerini basitleştirir. Ödeme uç noktalarını sanal ortamda test edin, webhook imzalarını doğrulayın, işlem yanıtlarını inceleyin ve entegrasyon sorunlarını tek bir çalışma alanında ayıklayın. API spesifikasyonlarını içe aktarın, yanıtları taklit edin ve test senaryolarını ekibinizle paylaşın.

Not: Bu rehber, iPay ve benzeri ödeme işlemcileri için genel entegrasyon modellerini kapsar. Uygulama detayları için her zaman resmi dokümantasyonu kontrol edin.

iPay API Nedir?

iPay gibi ödeme API’leri, finansal işlemleri yönetmek için RESTful arayüzler sunar. API ile şunları yönetebilirsiniz:

• Ö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

Özellik	Açıklama
RESTful API	JSON tabanlı uç noktalar
OAuth 2.0 + API Anahtarları	Güvenli kimlik doğrulama
Webhook'lar	Gerçek zamanlı ödeme bildirimleri
Tokenizasyon	Güvenli kart depolama
3D Secure	SCA uyumluluğu
PCI DSS	Seviye 1 uyumluluğu
Çoklu Para Birimi	100+'dan fazla para birimi
Dolandırıcılık Araçları	Risk puanlama, hız kontrolleri

Ö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ı

Ortam	URL	Kullanım Durumu
Test Ortamı	https://sandbox.ipay.com/api	Geliştirme, test
Üretim	https://api.ipay.com/api	Canlı işlemler

Başlarken: Kimlik Doğrulama Kurulumu

Adım 1: iPay Hesabı Oluşturma

API erişimi için:

1. iPay satıcı kaydını ziyaret edin
2. İşletme doğrulamasını (KYB) tamamlayın
3. Belgeleri gönderin:
   • İşletme kaydı
   • Banka hesabı
   • Resmi kimlik
4. Onaylanmayı bekleyin (1-3 iş günü)

Adım 2: API Kimlik Bilgilerini Alın

Kimlik bilgisi oluşturmak için:

1. iPay Satıcı Paneli'ne girin
2. Ayarlar > API Anahtarları’na gidin
3. Yeni API anahtarı oluşturun
4. Anahtarları güvenli ş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: Test ve üretim ortamı için farklı anahtarlar kullanın.

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

Yöntem	En İyi Kullanım	Güvenlik Seviyesi
Temel Kimlik Doğrulama	Sunucudan sunucuya	Yüksek
OAuth 2.0	Çoklu kiracılı uygulama	Daha Yüksek
JWT	Mikroservisler	Yüksek

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

Yeniden kullanılabilir bir istemci 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

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

Yöntem	Tip	Kullanım Durumu
kart	Kredi/Banka Kartı	Standart ödemeler
bank_havalesi	ACH, SEPA	Düşük ücretli transfer
dijital_cüzdan	Apple Pay, Google Pay	Mobil ödeme
şimdi_al_sonra_öde	Klarna, Afterpay	Taksitli ödemeler

Kart Bilgilerini Tokenize Etme

Kartı güvenli biçimde saklamak için:

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 olarak kaydedin
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ğu için:

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ı iPay.js veya mobil SDK ile gösterin

İade Yönetimi

Tam İade İşleme

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

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$ ödemenin 15.00$'ını iade edin
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`İade edilen: $${refund.amount / 100}`);

İade Nedenleri

Neden Kodu	Açıklama
yinelenen	Yinelenen tahsilat
sahtekarlık	Sahtekarlık işlemi
müşteri_tarafından_talep_edildi	Müşteri talebi
sipariş_iptal_edildi	Sipariş iptali
ürün_teslim_edilmedi	Ürün teslim edilmedi
ürün_açıklandığı_gibi_değil	Ürün açıklamadan farklı

Müşteri Yönetimi

Müşteri Oluşturma

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: '[e-mail]',
  name: 'John Doe',
  phone: '[phone]',
  internalId: 'USR-12345',
  tier: 'premium'
});

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

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

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

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

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. Olayları seçin

Webhook Olayları

Olay	Tetikleyici
payment.succeeded	Ödeme tamamlandı
payment.failed	Ödeme reddedildi
payment.refunded	İade işlendi
payment.disputed	Ters ibraz yapıldı
customer.created	Yeni müşteri
customer.subscription.updated	Abonelik değiştirildi

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());

  // Olayı işleyin
  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);
  }

  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üncelle
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

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

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

  // Müşteriye bildirim gönder
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // 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

Gereksinim	Uygulama
Güvenli Ağ	HTTPS, güvenlik duvarları, yapılandırmalar
Kart Sahibi Verilerinin Korunması	CVV’yi asla saklamayın, PAN’ı şifreleyin
Güvenlik Açığı Yönetimi	Güncellemeler, anti-virüs
Erişim Kontrolü	En az ayrıcalık, MFA, benzersiz kimlik
İzleme	Günlükleme, izinsiz giriş tespiti
Güvenlik Politikası	Belgelenmiş politikalar, eğitim

Güvenlik En İyi Uygulamaları

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

// 2. İdempotentlik 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 veri olmadan)
logger.info('Ödeme denendi', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // ASLA: kart numarası, CVV, tam ödeme yöntemi detayları loglamayın
});

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

// 6. Oran sınırlaması uygulayın
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // Dakikada 10 deneme
});

Üretim Dağıtım Kontrol Listesi

Canlı ödemeye geçmeden önce:

• [ ] PCI DSS Öz Değerlendirme Anketini tamamla
• [ ] Tüm uç noktalar için HTTPS kullan
• [ ] API anahtarlarını güvenli sır yönetimine al
• [ ] Webhook imza doğrulaması uygula
• [ ] Ödeme işlemlerine idempotentlik ekle
• [ ] Kapsamlı logging yap (hassas veri olmadan)
• [ ] Dolandırıcılık tespit kurallarını ayarla
• [ ] İade ve ters ibraz akışlarını test et
• [ ] Ödeme hataları için bir çalışma kitabı oluştur
• [ ] İzleme ve uyarı ayarla
• [ ] Yedek ödeme işlemcisi ekle

Gerçek Dünya Kullanım Senaryoları

E-ticaret Ödeme İşlemi

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

SaaS Abonelik Faturalandırması

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

Pazar Yeri Emanet (Escrow)

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

Sonuç

Ödeme API entegrasyonu, güvenlik, uyumluluk ve hata yönetiminde dikkat gerektirir. Uygulama için öne çıkanlar:

• Ham kart verisi kullanmayın – tokenizasyon şarttır
• Tüm ödemelerde idempotentlik kullanın
• Dolandırıcılığı önlemek için webhook imzası doğrulayın
• PCI DSS gerekliliklerini karşılayın
• Ü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ınız ve gizli anahtarınız ile Temel kimlik doğrulaması veya çok kiracılı uygulamalar için OAuth 2.0 kullanın.

Müşteri kart bilgilerini saklayabilir miyim?

Evet, fakat PCI DSS uyumlu olmalısınız. Kartları iPay'in kasasında güvenli saklamak için tokenizasyon kullanın.

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

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

İdempotentlik nedir ve neden önemlidir?

İdempotentlik, aynı anahtara sahip tekrarlanan isteklerin aynı sonucu vermesini sağlar; böylece çift tahsilat riskini ortadan kaldırır.

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

iPay'in sağladığı test kartları ile sandbox ortamında test yapabilirsiniz.

Webhook imzaları nelerdir?

Webhook’ların kötü niyetli aktörlerden değil, gerçekten iPay’den geldiğini kriptografik olarak doğrulayan imzalardır.