PayTR Node.js SDK

PayTR ödeme geçidi için modüler Node.js/TypeScript SDK. React, Nuxt, Next.js ve Vue backend'lerinde kullanılabilir.

🚀 Kurulum

npm install paytr-node
# veya
yarn add paytr-node
# veya
pnpm add paytr-node

⚙️ Yapılandırma

import { PayTR } from 'paytr-node';

const paytr = new PayTR({
  merchantId: 'MAGAZA_NO',
  merchantKey: 'API_KEY',
  merchantSalt: 'API_SALT',
  testMode: false, // Test modu (isteğe bağlı)
  language: 'tr',  // Dil: 'tr' veya 'en' (isteğe bağlı)
  debugMode: false // Debug modu (isteğe bağlı)
});

📖 Kullanım

Direkt Ödeme (3D Secure)

// Ödeme formu verilerini hazırla
const payment = paytr.preparePayment({
  merchantOid: `ORDER-${Date.now()}`,
  email: '[email protected]',
  paymentAmount: 100.99,
  currency: 'TL',
  basketItems: [
    { name: 'Ürün 1', price: 50.00, quantity: 1 },
    { name: 'Ürün 2', price: 25.50, quantity: 2 }
  ],
  user: {
    name: 'Müşteri Adı',
    address: 'Müşteri Adresi',
    phone: '05551234567'
  },
  merchantOkUrl: 'https://site.com/odeme/basarili',
  merchantFailUrl: 'https://site.com/odeme/hata',
  userIp: '192.168.1.1', // İsteğe bağlı
  installmentCount: 0,    // Taksit sayısı (0 = peşin)
  non3d: false           // 3D'siz işlem
});

// payment.formAction -> Form action URL'i
// payment.formData   -> Hidden input verileri
// payment.token      -> PayTR token

Ödeme Callback Doğrulama

// Express.js / Next.js API Route
app.post('/api/paytr/callback', (req, res) => {
  const isValid = paytr.verifyCallback(req.body);
  
  if (!isValid) {
    return res.status(400).send('Invalid hash');
  }
  
  const { merchant_oid, status, total_amount, utoken } = req.body;
  
  if (status === 'success') {
    // Siparişi onayla ve veritabanını güncelle
    // utoken varsa kullanıcının kart token'ını kaydet
  } else {
    // Siparişi iptal et
  }
  
  res.send('OK'); // PayTR'a bildirimi aldığımızı bildir
});

BIN Sorgulama

const result = await paytr.queryBIN('979203');

if (result.status === 'success') {
  console.log('Banka:', result.issuer_name);
  console.log('Kart Tipi:', result.card_type);
  console.log('Kart Ailesi:', result.card_family);
}

İade İşlemi

const result = await paytr.refund('ORDER-123', 50.00, 'REF-001');

if (result.status === 'success') {
  console.log('İade başarılı');
} else {
  console.error('Hata:', result.err_msg);
}

İşlem Dökümü

const startDate = new Date('2024-01-01');
const endDate = new Date('2024-01-03'); // Max 3 gün aralık

const result = await paytr.getTransactions(startDate, endDate);

if (result.status === 'success' && result.transactions) {
  result.transactions.forEach(tx => {
    console.log(`${tx.merchant_oid}: ${tx.status} - ${tx.amount} ${tx.currency}`);
  });
}

Kayıtlı Kartlar

// Kart listesi
const cards = await paytr.listCards('user-token-xxx');

if (cards.status === 'success' && cards.cards) {
  cards.cards.forEach(card => {
    console.log(`${card.bank_name} - ****${card.c_last_four}`);
    console.log('CVV Gerekli:', card.require_cvv === '1');
  });
}

// Kart silme
const deleteResult = await paytr.deleteCard('user-token-xxx', 'card-token-xxx');

Kayıtlı Kart ile Ödeme

const payment = paytr.prepareStoredCardPayment({
  merchantOid: `ORDER-${Date.now()}`,
  email: '[email protected]',
  paymentAmount: 100.99,
  currency: 'TL',
  basketItems: [{ name: 'Ürün', price: 100.99, quantity: 1 }],
  user: { name: 'Ad Soyad', address: 'Adres', phone: '05551234567' },
  merchantOkUrl: 'https://site.com/basarili',
  merchantFailUrl: 'https://site.com/hata',
  utoken: 'user-token-xxx',
  ctoken: 'card-token-xxx',
  requireCvv: true // Eğer kart CVV gerektiriyorsa
});

Kart Saklayarak Ödeme

const payment = paytr.prepareSaveCardPayment({
  merchantOid: `ORDER-${Date.now()}`,
  email: '[email protected]',
  paymentAmount: 100.99,
  currency: 'TL',
  basketItems: [{ name: 'Ürün', price: 100.99, quantity: 1 }],
  user: { name: 'Ad Soyad', address: 'Adres', phone: '05551234567' },
  merchantOkUrl: 'https://site.com/basarili',
  merchantFailUrl: 'https://site.com/hata',
  storeCard: true,
  utoken: 'existing-user-token' // Mevcut kullanıcı varsa
});

Tekrarlı Ödeme (Recurring)

const payment = paytr.prepareRecurringPayment({
  merchantOid: `RECURRING-${Date.now()}`,
  email: '[email protected]',
  paymentAmount: 49.99,
  currency: 'TL',
  basketItems: [{ name: 'Aylık Abonelik', price: 49.99, quantity: 1 }],
  user: { name: 'Ad Soyad', address: 'Adres', phone: '05551234567' },
  merchantOkUrl: 'https://site.com/basarili',
  merchantFailUrl: 'https://site.com/hata',
  utoken: 'user-token-xxx',
  ctoken: 'card-token-xxx'
});

Sipariş Durumu Sorgulama

const result = await paytr.getOrderStatus('ORDER-123');

if (result.status === 'success') {
  console.log('Ödeme Durumu:', result.payment_status);
  // 'waiting' | 'success' | 'failed'
}

Taksit Oranları

const result = await paytr.getInstallmentRates();

if (result.status === 'success') {
  console.log('Taksit Oranları:', result.raw);
}

🔧 Next.js / Nuxt Entegrasyonu

Next.js API Route

// app/api/payment/route.ts
import { PayTR } from 'paytr-node';

const paytr = new PayTR({
  merchantId: process.env.PAYTR_MERCHANT_ID!,
  merchantKey: process.env.PAYTR_MERCHANT_KEY!,
  merchantSalt: process.env.PAYTR_MERCHANT_SALT!
});

export async function POST(request: Request) {
  const body = await request.json();
  
  const payment = paytr.preparePayment({
    merchantOid: `ORDER-${Date.now()}`,
    email: body.email,
    paymentAmount: body.amount,
    currency: 'TL',
    basketItems: body.items,
    user: body.user,
    merchantOkUrl: `${process.env.NEXT_PUBLIC_URL}/payment/success`,
    merchantFailUrl: `${process.env.NEXT_PUBLIC_URL}/payment/failed`,
    userIp: request.headers.get('x-forwarded-for') || ''
  });

  return Response.json(payment);
}

Nuxt Server Route

// server/api/payment.post.ts
import { PayTR } from 'paytr-node';

const paytr = new PayTR({
  merchantId: process.env.PAYTR_MERCHANT_ID!,
  merchantKey: process.env.PAYTR_MERCHANT_KEY!,
  merchantSalt: process.env.PAYTR_MERCHANT_SALT!
});

export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  
  const payment = paytr.preparePayment({
    merchantOid: `ORDER-${Date.now()}`,
    email: body.email,
    paymentAmount: body.amount,
    currency: 'TL',
    basketItems: body.items,
    user: body.user,
    merchantOkUrl: `${process.env.NUXT_PUBLIC_URL}/odeme/basarili`,
    merchantFailUrl: `${process.env.NUXT_PUBLIC_URL}/odeme/hata`,
    userIp: getHeader(event, 'x-forwarded-for') || ''
  });

  return payment;
});

📋 API Referansı

| Metod | Açıklama | |-------|----------| | preparePayment(options) | Direkt ödeme formu hazırlar | | prepareSaveCardPayment(options) | Kart saklayarak ödeme formu hazırlar | | prepareStoredCardPayment(options) | Kayıtlı kart ile ödeme formu hazırlar | | prepareRecurringPayment(options) | Tekrarlı ödeme formu hazırlar | | verifyCallback(callback) | Ödeme bildirimini doğrular | | queryBIN(binNumber) | BIN sorgulama yapar | | refund(merchantOid, amount, referenceNo?) | İade işlemi yapar | | getTransactions(startDate, endDate) | İşlem dökümü getirir | | listCards(utoken) | Kayıtlı kartları listeler | | deleteCard(utoken, ctoken) | Kayıtlı kartı siler | | getOrderStatus(merchantOid) | Sipariş durumu sorgular | | getInstallmentRates() | Taksit oranlarını getirir |

📝 Test Kartı

Kart Numarası: 9792030394440796
Son Kullanma: 12/24
CVV: 000

📄 Lisans

MIT