Hızlı Başlangıç

1. Ödeme nesnesini oluşturun

import { betterPayment, iyzico } from 'better-payment';

export const payment = betterPayment({
  mode: 'sandbox', // sandbox URLs and provider test modes; default is 'production'
  providers: {
    iyzico: iyzico({
      apiKey: process.env.IYZICO_API_KEY!,
      secretKey: process.env.IYZICO_SECRET_KEY!,
    }),
  },
});

2. Ödeme isteğini oluşturun

İsteği sunucuda, kendi sipariş verilerinizden oluşturun. Tutarları asla tarayıcıdan almayın.

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

const request = {
  price: '100.00',
  paidPrice: '100.00',
  currency: Currency.TRY,
  installment: 1,
  basketId: 'B67832',
  conversationId: 'ORDER123', // your order id (letters and digits only for PayTR)
  paymentCard: {
    cardHolderName: 'John Doe',
    cardNumber: '5528790000000008',
    expireMonth: '12',
    expireYear: '2030',
    cvc: '123',
  },
  buyer: {
    id: 'BY789',
    name: 'John',
    surname: 'Doe',
    gsmNumber: '+905350000000',
    email: 'johndoe@example.com',
    identityNumber: '74300864791',
    registrationAddress: 'Nidakule Göztepe, Merdivenköy Mah.',
    city: 'Istanbul',
    country: 'Turkey',
    ip: '85.34.78.112',
  },
  shippingAddress: {
    contactName: 'Jane Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Nidakule Göztepe, Merdivenköy Mah.',
  },
  billingAddress: {
    contactName: 'Jane Doe',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Nidakule Göztepe, Merdivenköy Mah.',
  },
  basketItems: [
    {
      id: 'BI101',
      name: 'Binocular',
      category1: 'Collectibles',
      itemType: BasketItemType.PHYSICAL,
      price: '100.00',
    },
  ],
};

3. 3D Secure'u başlatın

const init = await payment.initThreeDSPayment({
  ...request,
  callbackUrl: 'https://yoursite.com/api/pay/iyzico/payment/complete-3ds',
});

if (init.status === 'pending') {
  // Render init.threeDSHtmlContent in the browser
  // (or redirect to init.redirectUrl when the provider returns one)
}

4. 3D Secure'u tamamlayın

Banka sonucu callbackUrl adresine POST eder. Bu POST gövdesini olduğu gibi geçirin:

const result = await payment.completeThreeDSPayment(callbackBody);

if (result.status === 'success') {
  // mark the order as paid
}

Kütüphane callback'i sizin kimlik bilgilerinizle kontrol eder ve sağlayıcı gerektiriyorsa ödemeyi tamamlar. Sahte ya da başarısız bir callback her zaman failure döner. HTTP handler bunu sizin için yapar.

5. Sonuçları işleyin

status	anlamı
`success`	Sağlayıcı tarafından onaylandı
`failure`	Reddedildi; `errorCode` / `errorMessage` alanlarına bakın
`pending`	Müşteri bekleniyor ya da sonuç bilinmiyor (`errorCode: 'NETWORK_ERROR'`)
`cancelled`	İptal edildi veya tamamen iade edildi (durum sorguları)

NETWORK_ERROR durumunda ödeme yine de gerçekleşmiş olabilir. Yeniden denemeden önce getPayment(paymentId) ile kontrol edin. Ödeme, iade ve iptal istekleri asla otomatik olarak tekrarlanmaz.

Birden fazla sağlayıcı kullanmak

const payment = betterPayment({
  providers: {
    iyzico: iyzico({ /* ... */ }),
    paytr: paytr({ /* ... */ }),
  },
  defaultProvider: 'iyzico',
});

await payment.createPayment(request);                 // default provider
await payment.paytr.initThreeDSPayment(paytrRequest); // specific provider
await payment.use('paytr').getPayment('ORDER123');

Siparişleri olaylarla güncelleyin

Her sonucu tek tek kontrol etmek yerine ödeme olaylarını dinleyin. Olaylar her sağlayıcı ve akış için, sonuç sağlayıcı tarafından doğrulandıktan sonra yayınlanır:

payment.on('payment.succeeded', async (event) => {
  await orders.markPaid(event.conversationId, event.paymentId);
});

payment.on('payment.failed', async (event) => {
  await orders.markFailed(event.conversationId, event.code);
});