Better Payment

Türkiye'deki tüm ödeme altyapılarını entegre edebilen unified payment gateway kütüphanesi.

Özellikler

🚀 TypeScript ile Yazılmış - Tam tip güvenliği ve IntelliSense desteği
🔌 Framework Agnostic - Node.js, Next.js, Express ve diğer tüm JavaScript framework'leri ile uyumlu
🏦 Çoklu Provider Desteği - Birden fazla ödeme sağlayıcısını aynı API ile yönetin
🎯 Tutarlı API - Tüm provider'lar için aynı interface
🔄 Abonelik Desteği - İyzico ile tekrarlayan ödemeler (subscription)
📦 Hafif - Minimal bağımlılık (sadece axios)
🛡️ Güvenli - API key ve secret key şifreleme

Desteklenen Ödeme Sağlayıcıları

✅ İyzico - Tam destek (V2 Authorization, Checkout Form, Subscription, Installment Inquiry)
✅ PayTR - Tam destek
✅ Parampos - Tam destek (SOAP API, 3D Secure, Taksit, İade/İptal)

Kurulum

Gereksinimler: Node.js 20 veya üzeri

npm install better-payment
# veya
yarn add better-payment
# veya
pnpm add better-payment

Hızlı Başlangıç

🎯 Önerilen Yöntem: Config-Based

import { BetterPay, ProviderType, Currency, BasketItemType } from 'better-payment';

// 1. Config dosyası oluşturun
const paymentConfig = {
  providers: {
    iyzico: {
      enabled: true,
      config: {
        apiKey: process.env.IYZICO_API_KEY!,
        secretKey: process.env.IYZICO_SECRET_KEY!,
        baseUrl: 'https://sandbox-api.iyzipay.com',
      },
    },
    paytr: {
      enabled: false, // İsteğe bağlı - Kullanmak için true yapın
      config: {
        apiKey: process.env.PAYTR_MERCHANT_KEY!,
        secretKey: process.env.PAYTR_SECRET_KEY!,
        merchantId: process.env.PAYTR_MERCHANT_ID!,
        merchantSalt: process.env.PAYTR_MERCHANT_SALT!,
        baseUrl: 'https://www.paytr.com',
      },
    },
    parampos: {
      enabled: false, // İsteğe bağlı - Kullanmak için true yapın
      config: {
        clientCode: process.env.PARAMPOS_CLIENT_CODE!,
        clientUsername: process.env.PARAMPOS_CLIENT_USERNAME!,
        clientPassword: process.env.PARAMPOS_CLIENT_PASSWORD!,
        guid: process.env.PARAMPOS_GUID!,
        apiKey: process.env.PARAMPOS_GUID!,
        secretKey: process.env.PARAMPOS_CLIENT_PASSWORD!,
        baseUrl: 'https://testposws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx',
        testMode: true,
      },
    },
  },
  defaultProvider: ProviderType.IYZICO,
};

// 2. BetterPay'i başlatın
const betterPay = new BetterPay(paymentConfig);

// 3. Ödeme yapın - Farklı Kullanım Şekilleri:

// Yöntem 1: Provider'a doğrudan erişim (Önerilen)
const result = await betterPay.iyzico.createPayment({
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  basketId: 'B67832',
  paymentCard: {
    cardHolderName: 'John Doe',
    cardNumber: '5528790000000008',
    expireMonth: '12',
    expireYear: '2030',
    cvc: '123',
  },
  buyer: {
    id: 'BY789',
    name: 'John',
    surname: 'Doe',
    email: '[email protected]',
    identityNumber: '11111111110',
    registrationAddress: 'Address',
    city: 'Istanbul',
    country: 'Turkey',
    ip: '85.34.78.112',
  },
  shippingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  billingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  basketItems: [
    {
      id: 'BI101',
      name: 'Product 1',
      category1: 'Category',
      itemType: BasketItemType.PHYSICAL,
      price: '100.00',
    },
  ],
});

if (result.status === 'success') {
  console.log('Ödeme başarılı:', result.paymentId);
} else {
  console.error('Ödeme hatası:', result.errorMessage);
}

// Yöntem 2: Default provider kullanarak (defaultProvider ayarlanmışsa)
const result2 = await betterPay.createPayment({ ... });

// Yöntem 3: use() metodu ile provider seçerek
const result3 = await betterPay.use(ProviderType.PAYTR).createPayment({ ... });

// Yöntem 4: PayTR'a doğrudan erişim
const result4 = await betterPay.paytr.createPayment({ ... });

📦 Alternatif: Direct Provider Kullanımı

import { Iyzico } from 'better-payment';

const iyzico = new Iyzico({
  apiKey: process.env.IYZICO_API_KEY!,
  secretKey: process.env.IYZICO_SECRET_KEY!,
  baseUrl: 'https://sandbox-api.iyzipay.com',
});

const result = await iyzico.createPayment({ ... });

Not: Config-based (BetterPay) yaklaşımın avantajları:

✅ Birden fazla provider'ı tek yerden yönetebilirsiniz
✅ Provider'lar arası kolayca geçiş yapabilirsiniz (betterPay.iyzico / betterPay.paytr)
✅ Ortam değişkenlerine göre provider değiştirebilirsiniz
✅ Default provider ile basit kullanım: betterPay.createPayment()
✅ Daha temiz ve maintainable kod

3D Secure Ödeme

// 3D Secure işlemini başlat
const threeDSResult = await betterPay.iyzico.initThreeDSPayment({
  // Aynı parametreler + callbackUrl
  callbackUrl: 'https://your-site.com/payment/callback',
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  // ... diğer parametreler
});

if (threeDSResult.status === 'success' && threeDSResult.threeDSHtmlContent) {
  // HTML içeriğini kullanıcıya göster
  // Bu, banka 3D Secure sayfasına yönlendirir
  return threeDSResult.threeDSHtmlContent;
}

// Callback'ten sonra ödemeyi tamamla
const finalResult = await betterPay.iyzico.completeThreeDSPayment(callbackData);

Korumalı Havale/EFT (PWI - Payment With IBAN)

İyzico'nun korumalı havale sistemi ile kullanıcılarınız havale/EFT ile ödeme yapabilir. Havale yapıldığında ödeme onaylanır ve satıcıya aktarılır:

import { BetterPay, Currency, BasketItemType } from 'better-payment';

// PWI Ödeme başlat
const pwiResult = await betterPay.iyzico.initPWIPayment({
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  basketId: 'B67832',
  callbackUrl: 'https://your-site.com/payment/callback',
  buyer: {
    id: 'BY789',
    name: 'John',
    surname: 'Doe',
    email: '[email protected]',
    identityNumber: '11111111110',
    registrationAddress: 'Address',
    city: 'Istanbul',
    country: 'Turkey',
    ip: '85.34.78.112',
    gsmNumber: '+905350000000',
  },
  shippingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  billingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  basketItems: [
    {
      id: 'BI101',
      name: 'Product 1',
      category1: 'Category',
      itemType: BasketItemType.PHYSICAL,
      price: '100.00',
    },
  ],
});

if (pwiResult.status === 'success') {
  // Option 1: HTML içeriğini göster (IBAN ve havale bilgileri)
  document.getElementById('payment-info').innerHTML = pwiResult.htmlContent;

  // Option 2: İyzico ödeme sayfasına yönlendir
  window.location.href = pwiResult.paymentPageUrl;

  // Token'ı sakla (ödeme durumu sorgulamak için)
  const token = pwiResult.token;
}

// PWI Ödeme durumunu sorgula
const paymentStatus = await betterPay.iyzico.retrievePWIPayment(token);

if (paymentStatus.status === 'success') {
  if (paymentStatus.paymentStatus === 'SUCCESS') {
    console.log('Havale başarıyla alındı:', paymentStatus.paymentId);
    console.log('Ödenen tutar:', paymentStatus.paidPrice);
  } else if (paymentStatus.paymentStatus === 'WAITING') {
    console.log('Havale bekleniyor');
    console.log('IBAN:', paymentStatus.iban);
    console.log('Banka:', paymentStatus.bankName);
  }
}

Checkout Form (Ödeme Formu)

İyzico'nun hazır ödeme formunu kullanarak, kart bilgilerini kendi sunucunuzda tutmadan ödeme alabilirsiniz:

import { BetterPay, Currency, BasketItemType } from 'better-payment';

// Checkout Form başlat
const checkoutResult = await betterPay.iyzico.initCheckoutForm({
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  basketId: 'B67832',
  callbackUrl: 'https://your-site.com/payment/callback',
  enabledInstallments: [1, 2, 3, 6, 9], // İsteğe bağlı - İzin verilen taksit sayıları
  buyer: {
    id: 'BY789',
    name: 'John',
    surname: 'Doe',
    email: '[email protected]',
    identityNumber: '11111111110',
    registrationAddress: 'Address',
    city: 'Istanbul',
    country: 'Turkey',
    ip: '85.34.78.112',
  },
  shippingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  billingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  basketItems: [
    {
      id: 'BI101',
      name: 'Product 1',
      category1: 'Category',
      itemType: BasketItemType.PHYSICAL,
      price: '100.00',
    },
  ],
});

if (checkoutResult.status === 'success') {
  // Kullanıcıyı İyzico ödeme sayfasına yönlendir
  // Option 1: paymentPageUrl ile redirect
  window.location.href = checkoutResult.paymentPageUrl;

  // Option 2: checkoutFormContent (iframe HTML) göster
  // document.getElementById('payment-form').innerHTML = checkoutResult.checkoutFormContent;
}

// Callback'te token ile ödeme sonucunu sorgula
const paymentResult = await betterPay.iyzico.retrieveCheckoutForm(token);

if (paymentResult.status === 'success') {
  console.log('Ödeme başarılı:', paymentResult.paymentId);
  console.log('Ödenen tutar:', paymentResult.paidPrice);
  console.log('Taksit sayısı:', paymentResult.installment);
}

Abonelik Yönetimi (İyzico Subscription)

İyzico'nun abonelik sistemi ile tekrarlayan ödemeler alabilirsiniz:

import { BetterPay, PaymentInterval, SubscriptionStatus } from 'better-payment';

// 1. Abonelik ürünü oluştur
const product = await betterPay.iyzico.createSubscriptionProduct({
  name: 'Premium Üyelik',
  description: 'Aylık premium üyelik paketi',
  conversationId: 'product-001',
});

// 2. Fiyatlandırma planı oluştur
const plan = await betterPay.iyzico.createPricingPlan({
  productReferenceCode: product.data.referenceCode,
  name: 'Aylık Plan',
  price: 99.9,
  currency: 'TRY',
  paymentInterval: PaymentInterval.MONTHLY,
  paymentIntervalCount: 1,
  trialPeriodDays: 7, // 7 günlük deneme süresi (opsiyonel)
  recurrenceCount: 12, // 12 ay sonra otomatik iptal (opsiyonel)
  conversationId: 'plan-001',
});

// 3. Aboneliği başlat
const subscription = await betterPay.iyzico.initializeSubscription({
  pricingPlanReferenceCode: plan.data.referenceCode,
  subscriptionInitialStatus: SubscriptionStatus.ACTIVE,
  customer: {
    name: 'John',
    surname: 'Doe',
    email: '[email protected]',
    gsmNumber: '+905350000000',
    identityNumber: '11111111111',
    billingAddress: {
      contactName: 'John Doe',
      city: 'Istanbul',
      country: 'Turkey',
      address: 'Nidakule Göztepe, Merdivenköy Mah.',
      zipCode: '34732',
    },
  },
  paymentCard: {
    cardHolderName: 'John Doe',
    cardNumber: '5528790000000008',
    expireMonth: '12',
    expireYear: '2030',
    cvc: '123',
  },
  conversationId: 'subscription-001',
});

if (subscription.status === 'success') {
  console.log('Abonelik başlatıldı:', subscription.data.referenceCode);
  console.log('Durum:', subscription.data.subscriptionStatus);
}

// 4. Abonelik detaylarını sorgula
const details = await betterPay.iyzico.retrieveSubscription({
  subscriptionReferenceCode: subscription.data.referenceCode,
});

// 5. Aboneliği yükselt (farklı plana geç)
const upgrade = await betterPay.iyzico.upgradeSubscription({
  subscriptionReferenceCode: subscription.data.referenceCode,
  newPricingPlanReferenceCode: 'yeni-plan-ref-code',
  useTrial: false,
  resetRecurrenceCount: false,
});

// 6. Kart güncelleme formu oluştur
const cardUpdate = await betterPay.iyzico.updateSubscriptionCard({
  subscriptionReferenceCode: subscription.data.referenceCode,
  callbackUrl: 'https://your-site.com/subscription/card-update/callback',
  conversationId: 'card-update-001',
});

if (cardUpdate.status === 'success') {
  // Kullanıcıyı kart güncelleme sayfasına yönlendir
  window.location.href = cardUpdate.paymentPageUrl;
}

// 7. Aboneliği iptal et
const cancel = await betterPay.iyzico.cancelSubscription({
  subscriptionReferenceCode: subscription.data.referenceCode,
});

Ödeme Aralıkları (PaymentInterval):

PaymentInterval.DAILY - Günlük
PaymentInterval.WEEKLY - Haftalık
PaymentInterval.MONTHLY - Aylık
PaymentInterval.YEARLY - Yıllık

Abonelik Durumları (SubscriptionStatus):

SubscriptionStatus.ACTIVE - Aktif
SubscriptionStatus.PENDING - Beklemede
SubscriptionStatus.CANCELED - İptal Edildi
SubscriptionStatus.EXPIRED - Süresi Doldu
SubscriptionStatus.UNPAID - Ödenmedi

Taksit Sorgulama

Kullanıcının kartına ait BIN numarasına göre kullanılabilir taksit seçeneklerini sorgulayabilirsiniz:

import { BetterPay } from 'better-payment';

// Kart BIN numarası ile taksit seçeneklerini sorgula
const installmentResult = await betterPay.iyzico.installmentInfo({
  binNumber: '552879', // Kart numarasının ilk 6-8 hanesi
  price: '100.00',
  conversationId: 'optional-conversation-id',
});

if (installmentResult.status === 'success' && installmentResult.installmentDetails) {
  installmentResult.installmentDetails.forEach((detail) => {
    console.log(`Banka: ${detail.bankName}`);
    console.log(`Kart Ailesi: ${detail.cardFamilyName}`);
    console.log(`Kart Tipi: ${detail.cardType}`);
    console.log(`Kart Kuruluşu: ${detail.cardAssociation}`);

    // Taksit seçenekleri
    detail.installmentPrices.forEach((installment) => {
      if (installment.installmentNumber === 1) {
        console.log(`Tek Çekim: ${installment.totalPrice} TL`);
      } else {
        console.log(
          `${installment.installmentNumber} Taksit: ${installment.totalPrice} TL ` +
          `(Aylık: ${installment.installmentPrice} TL)`
        );
      }
    });
  });
}

Taksit Bilgileri:

binNumber - Kart BIN numarası
bankName - Banka adı
cardFamilyName - Kart ailesi (Bonus, Maximum, Axess, World, vb.)
cardType - Kart tipi (CREDIT_CARD, DEBIT_CARD)
cardAssociation - Kart kuruluşu (VISA, MASTER_CARD, TROY, AMEX)
commercial - Ticari kart mı (0: hayır, 1: evet)
force3ds - 3DS zorunlu mu (0: hayır, 1: evet)
installmentPrices - Taksit seçenekleri listesi

Kullanım Senaryoları:

E-Ticaret checkout sayfasında kullanıcıya taksit seçeneklerini gösterme
Farklı kartlar için taksit oranlarını karşılaştırma
Kart girişi sırasında gerçek zamanlı taksit bilgisi gösterme

Diğer İşlemler

// Ödeme sorgulama
const payment = await betterPay.iyzico.getPayment('payment-id');

// İade
const refund = await betterPay.iyzico.refund({
  paymentId: 'payment-id',
  price: '50.00',
  currency: Currency.TRY,
  ip: '85.34.78.112',
});

// İptal
const cancel = await betterPay.iyzico.cancel({
  paymentId: 'payment-id',
  ip: '85.34.78.112',
});

// Default provider kullanarak (defaultProvider ayarlanmışsa)
const payment2 = await betterPay.getPayment('payment-id');
const refund2 = await betterPay.refund({ ... });
const cancel2 = await betterPay.cancel({ ... });

Parampos Kullanımı

Parampos, Türkiye'de 22 banka ve 9 kart markası ile çalışan SOAP tabanlı bir ödeme altyapısıdır.

Parampos Konfigürasyonu

import { BetterPay, ProviderType } from 'better-payment';

const betterPay = new BetterPay({
  providers: {
    parampos: {
      enabled: true,
      config: {
        clientCode: process.env.PARAMPOS_CLIENT_CODE!,
        clientUsername: process.env.PARAMPOS_CLIENT_USERNAME!,
        clientPassword: process.env.PARAMPOS_CLIENT_PASSWORD!,
        guid: process.env.PARAMPOS_GUID!,
        apiKey: process.env.PARAMPOS_GUID!,
        secretKey: process.env.PARAMPOS_CLIENT_PASSWORD!,
        baseUrl: 'https://testposws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx',
        testMode: true,
      },
    },
  },
  defaultProvider: ProviderType.PARAMPOS,
});

Önemli Not: Parampos kullanmadan önce sunucunuzun statik IP adresini [email protected] adresine göndererek beyaz listeye eklettirmeniz gerekmektedir.

Parampos ile Direkt Ödeme

const result = await betterPay.parampos.createPayment({
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  basketId: 'BASKET123',
  paymentCard: {
    cardHolderName: 'John Doe',
    cardNumber: '5528790000000008',
    expireMonth: '12',
    expireYear: '2030',
    cvc: '123',
  },
  buyer: {
    id: 'BUYER123',
    name: 'John',
    surname: 'Doe',
    email: '[email protected]',
    identityNumber: '12345678901',
    registrationAddress: 'Address',
    city: 'Istanbul',
    country: 'Turkey',
    ip: '85.34.78.112',
    gsmNumber: '+905301234567',
  },
  shippingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  billingAddress: {
    contactName: 'John Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Address',
  },
  basketItems: [
    {
      id: 'ITEM1',
      name: 'Product',
      category1: 'Electronics',
      itemType: BasketItemType.PHYSICAL,
      price: '100.00',
    },
  ],
});

if (result.status === 'success') {
  console.log('Ödeme başarılı:', result.paymentId);
}

Parampos ile 3D Secure Ödeme

// 1. 3D Secure işlemini başlat
const threeDSResult = await betterPay.parampos.initThreeDSPayment({
  // Yukarıdaki parametreler + aşağıdakiler
  callbackUrl: 'https://your-domain.com/payment/callback',
  installment: 1, // Taksit sayısı (1 = tek çekim)
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  // ... diğer parametreler
});

if (threeDSResult.status === 'pending' && threeDSResult.threeDSHtmlContent) {
  // Base64 HTML içeriğini decode et ve kullanıcıya göster
  const htmlContent = Buffer.from(
    threeDSResult.threeDSHtmlContent,
    'base64'
  ).toString('utf-8');

  // HTML içeriğini sayfada göster (banka 3DS sayfasına yönlendirir)
  document.getElementById('payment-form').innerHTML = htmlContent;
}

// 2. Banka callback'inden sonra ödemeyi tamamla
// Callback handler'ınızda:
const completeResult = await betterPay.parampos.completeThreeDSPayment({
  islemGUID: callbackData.islemGUID,
  md: callbackData.md,
  mdStatus: callbackData.mdStatus,
  orderId: callbackData.orderId,
  GUID: callbackData.GUID,
  hash: callbackData.hash,
});

if (completeResult.status === 'success') {
  console.log('3D Secure ödeme başarılı:', completeResult.paymentId);
}

Parampos ile Taksitli Ödeme

const installmentResult = await betterPay.parampos.initThreeDSPayment({
  price: '1000.00',
  paidPrice: '1060.00', // Taksit komisyonu dahil toplam tutar
  currency: Currency.TRY,
  basketId: 'BASKET123',
  callbackUrl: 'https://your-domain.com/callback',
  installment: 6, // 6 taksit
  // ... diğer parametreler
});

// Taksit komisyon hesaplama (otomatik)
// 2 taksit: %2, 3 taksit: %3, ... 12 taksit: %12

Parampos İşlemleri

// İade
const refund = await betterPay.parampos.refund({
  paymentId: 'payment-guid',
  price: '50.00', // Kısmi iade
  currency: Currency.TRY,
  ip: '85.34.78.112',
});

// İptal (Void)
const cancel = await betterPay.parampos.cancel({
  paymentId: 'payment-guid',
  ip: '85.34.78.112',
});

// Ödeme Sorgulama
const payment = await betterPay.parampos.getPayment('payment-guid');

// BIN Sorgulama (Kart Bilgisi)
const binInfo = await betterPay.parampos.binCheck('552879');
if (binInfo.cardType) {
  console.log('Kart Tipi:', binInfo.cardType); // CREDIT, DEBIT
  console.log('Banka:', binInfo.bankName);
  console.log('Kart Ailesi:', binInfo.cardFamily); // VISA, MASTERCARD
  console.log('Ticari Kart:', binInfo.commercial);
}

Parampos API Özellikleri

Hash Algoritmaları:

Ödeme İstekleri: SHA256 → Base64
3DS Callback Doğrulama: SHA1 → Base64

Desteklenen İşlemler:

✅ Direkt ödeme (3D Secure olmadan)
✅ 3D Secure ödeme (başlatma ve tamamlama)
✅ Taksitli ödemeler (otomatik komisyon hesaplama)
✅ İade işlemi (tam/kısmi)
✅ İptal işlemi (void)
✅ Ödeme sorgulama
✅ BIN sorgulama (kart bilgisi)

Para Birimleri:

TRY (Türk Lirası)
USD (Amerikan Doları)
EUR (Euro)
GBP (İngiliz Sterlini)

Test Ortamı:

Test URL: https://testposws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx
IP Kaydı: [email protected]

Production Ortamı:

Production URL: ParamPOS panelinden alınır
IP Kaydı: ParamPOS > Entegrasyon Bilgilerim panelinden yapılır

TypeScript Desteği

Better Pay, tam TypeScript desteği sunar:

import type { PaymentRequest, PaymentResponse } from 'better-payment';

const request: PaymentRequest = {
  // TypeScript otomatik olarak tüm gerekli alanları gösterir
  price: '100.00',
  // ...
};

const result: PaymentResponse = await provider.createPayment(request);

if (result.status === 'success') {
  // TypeScript bilir ki result.paymentId var
  console.log(result.paymentId);
}

Framework Örnekleri

Next.js (App Router)

// app/api/payment/route.ts
import { BetterPay, ProviderType } from 'better-payment';
import { NextRequest, NextResponse } from 'next/server';

const betterPay = new BetterPay({
  providers: {
    iyzico: {
      enabled: true,
      config: {
        apiKey: process.env.IYZICO_API_KEY!,
        secretKey: process.env.IYZICO_SECRET_KEY!,
        baseUrl: process.env.IYZICO_BASE_URL!,
      },
    },
  },
  defaultProvider: ProviderType.IYZICO,
});

export async function POST(request: NextRequest) {
  const body = await request.json();

  // Yöntem 1: Provider'a doğrudan erişim
  const result = await betterPay.iyzico.createPayment(body);

  // Yöntem 2: Default provider kullanarak
  // const result = await betterPay.createPayment(body);

  return NextResponse.json(result);
}

Express.js

import express from 'express';
import { BetterPay, ProviderType } from 'better-payment';

const app = express();

const betterPay = new BetterPay({
  providers: {
    iyzico: {
      enabled: true,
      config: {
        apiKey: process.env.IYZICO_API_KEY!,
        secretKey: process.env.IYZICO_SECRET_KEY!,
        baseUrl: process.env.IYZICO_BASE_URL!,
      },
    },
  },
  defaultProvider: ProviderType.IYZICO,
});

app.post('/payment', async (req, res) => {
  // Provider'a doğrudan erişim
  const result = await betterPay.iyzico.createPayment(req.body);
  res.json(result);
});

API Dokümantasyonu

Detaylı API dokümantasyonu için: [Dokümantasyon Sitesi]

Temel Metodlar

Tüm provider'lar aşağıdaki metodları uygular:

createPayment(request) - Direkt ödeme oluştur
initThreeDSPayment(request) - 3D Secure ödeme başlat
completeThreeDSPayment(callbackData) - 3D Secure ödeme tamamla
refund(request) - İade işlemi
cancel(request) - İptal işlemi
getPayment(paymentId) - Ödeme sorgulama
binCheck(binNumber) - BIN sorgulama (provider desteğine bağlı)

İyzico Özel Metodlar

İyzico provider'ı aşağıdaki ek metodları sunar:

PWI (Payment With IBAN - Korumalı Havale/EFT):

initPWIPayment(request) - Korumalı havale/EFT ödeme başlat
retrievePWIPayment(token, conversationId?) - PWI ödeme durumunu sorgula

Checkout Form:

initCheckoutForm(request) - Checkout form başlat (kart bilgileri toplamadan ödeme)
retrieveCheckoutForm(token) - Checkout form sonucunu sorgula

Abonelik (Subscription):

createSubscriptionProduct(request) - Abonelik ürünü oluştur
createPricingPlan(request) - Fiyatlandırma planı oluştur
initializeSubscription(request) - Abonelik başlat
retrieveSubscription(request) - Abonelik detaylarını sorgula
upgradeSubscription(request) - Aboneliği farklı plana yükselt
updateSubscriptionCard(request) - Abonelik kartını güncelle
cancelSubscription(request) - Aboneliği iptal et

BIN Sorgulama:

binCheck(binNumber) - Kart BIN numarası sorgulama

Taksit Sorgulama:

installmentInfo(request) - Kart BIN numarası ve tutara göre taksit seçeneklerini sorgula

Tipler ve Enum'lar

enum PaymentStatus {
  SUCCESS = 'success',
  FAILURE = 'failure',
  PENDING = 'pending',
  CANCELLED = 'cancelled',
}

enum Currency {
  TRY = 'TRY',
  USD = 'USD',
  EUR = 'EUR',
  GBP = 'GBP',
}

enum BasketItemType {
  PHYSICAL = 'PHYSICAL',
  VIRTUAL = 'VIRTUAL',
}

enum PaymentInterval {
  DAILY = 'DAILY',
  WEEKLY = 'WEEKLY',
  MONTHLY = 'MONTHLY',
  YEARLY = 'YEARLY',
}

enum SubscriptionStatus {
  ACTIVE = 'ACTIVE',
  PENDING = 'PENDING',
  CANCELED = 'CANCELED',
  EXPIRED = 'EXPIRED',
  UNPAID = 'UNPAID',
}

Test

# Testleri çalıştır
pnpm test

# Test UI ile çalıştır
pnpm test:ui

# Build
pnpm build

Katkıda Bulunma

Better Pay açık kaynak bir projedir. Katkılarınızı bekliyoruz!

Repository'yi fork edin
Feature branch'i oluşturun (git checkout -b feature/amazing-feature)
Değişikliklerinizi commit edin (git commit -m 'feat: Add amazing feature')
Branch'i push edin (git push origin feature/amazing-feature)
Pull Request açın

Sürüm Yönetimi ve Release Süreci

Bu proje Release Please kullanarak otomatik sürüm yönetimi yapar. Her commit Conventional Commits standardına uygun olmalıdır.

Commit Mesajı Formatı

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Commit Tipleri:

feat: - Yeni özellik (minor sürüm artışı: 1.1.0 → 1.2.0)
fix: - Bug düzeltmesi (patch sürüm artışı: 1.1.0 → 1.1.1)
docs: - Dokümantasyon değişikliği
style: - Kod formatı değişikliği
refactor: - Kod iyileştirmesi
test: - Test ekleme/güncelleme
chore: - Genel bakım işlemleri
BREAKING CHANGE: - Geriye dönük uyumsuz değişiklik (major sürüm artışı: 1.1.0 → 2.0.0)

Örnekler:

git commit -m "feat: Add webhook support for payment notifications"
git commit -m "fix: Resolve 3DS callback parsing issue"
git commit -m "feat(iyzico): Add installment calculation method"
git commit -m "feat!: Change payment API interface" # Breaking change

Prerelease (Beta/Alpha) Sürüm Yayınlama

Beta veya alpha gibi prerelease sürümleri yayınlamak için:

1. Prerelease Branch Oluşturun

# Beta sürüm için
git checkout -b release-please--branches--main--prerelease-type--beta

# Alpha sürüm için
git checkout -b release-please--branches--main--prerelease-type--alpha

# RC (Release Candidate) için
git checkout -b release-please--branches--main--prerelease-type--rc

2. Değişikliklerinizi Yapın ve Commit Edin

git commit -m "feat: Add new experimental payment method"
git push origin release-please--branches--main--prerelease-type--beta

3. Release Please Otomatik PR Oluşturur

Release Please, branch'i algılayıp otomatik olarak bir prerelease PR oluşturur:

Beta branch için: 1.2.0 → 1.2.0-beta.1
Her yeni commit: 1.2.0-beta.1 → 1.2.0-beta.2

4. PR'ı Merge Ederek Prerelease Yayınlayın

PR'ı merge ettiğinizde:

Git tag oluşturulur (örn: v1.2.0-beta.1)
NPM'e beta tag ile yayınlanır
Kullanıcılar şu şekilde kurabilir:

npm install better-payment@beta
# veya spesifik versiyon
npm install [email protected]

5. Stable Sürüme Geçiş

Beta testleri tamamlandıktan sonra:

# Beta branch'i main'e merge edin
git checkout main
git merge release-please--branches--main--prerelease-type--beta
git push origin main

# Beta branch'i silin
git push origin --delete release-please--branches--main--prerelease-type--beta

Release Please bir sonraki main PR'ında beta label'ını kaldırıp stable sürüm (örn: 1.2.0) oluşturur.

NPM Tag'leri

latest - Stable sürümler (varsayılan: npm install better-payment)
beta - Beta sürümler (npm install better-payment@beta)
alpha - Alpha sürümler (npm install better-payment@alpha)
rc - Release candidate sürümler (npm install better-payment@rc)

Release Workflow

Normal geliştirme akışı:

main branch → feat/fix commits → Release Please PR → merge → stable release (1.2.0)

Prerelease akışı:

beta branch → feat commits → Release Please PR → merge → beta release (1.2.0-beta.1)
              → more commits → auto update PR → merge → beta release (1.2.0-beta.2)
              → merge to main → Release Please PR → merge → stable release (1.2.0)

Yeni Provider Ekleme

Yeni bir provider eklemek için:

src/providers/[provider-name]/ klasörü oluşturun
PaymentProvider abstract sınıfını extend edin
Tüm metodları implement edin
Testler yazın
Dokümantasyon ekleyin

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.github		.github
examples		examples
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
.versionrc.js		.versionrc.js
BETA_RELEASE.md		BETA_RELEASE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE_WORKFLOW.md		RELEASE_WORKFLOW.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Uh oh!

License

furkanczay/better-payment

Folders and files

Latest commit

History

Repository files navigation

Better Payment

Özellikler

Desteklenen Ödeme Sağlayıcıları

Kurulum

Hızlı Başlangıç

🎯 Önerilen Yöntem: Config-Based

📦 Alternatif: Direct Provider Kullanımı

3D Secure Ödeme

Korumalı Havale/EFT (PWI - Payment With IBAN)

Checkout Form (Ödeme Formu)

Abonelik Yönetimi (İyzico Subscription)

Taksit Sorgulama

Diğer İşlemler

Parampos Kullanımı

Parampos Konfigürasyonu

Parampos ile Direkt Ödeme

Parampos ile 3D Secure Ödeme

Parampos ile Taksitli Ödeme

Parampos İşlemleri

Parampos API Özellikleri

TypeScript Desteği

Framework Örnekleri

Next.js (App Router)

Express.js

API Dokümantasyonu

Temel Metodlar

İyzico Özel Metodlar

Tipler ve Enum'lar

Test

Katkıda Bulunma

Sürüm Yönetimi ve Release Süreci

Commit Mesajı Formatı

Prerelease (Beta/Alpha) Sürüm Yayınlama

NPM Tag'leri

Release Workflow

Yeni Provider Ekleme

Lisans

Destek

Roadmap

Ödeme Altyapıları

Banka Sanal POS'ları

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 15

Sponsor this project

Uh oh!

Packages 0

Contributors 3

Uh oh!

Languages

Packages