İçeriğe geç
Better Payment
Sağlayıcılar

PayTR

PayTR entegrasyon referansı — iFrame ödemeler, bildirimler, iadeler, durum sorgusu, BIN ve taksit.

PayTR form-urlencoded istekler kullanır. Her token base64(HMAC-SHA256(data + merchant_salt, merchant_key)) olarak imzalanır.

Yapılandırma

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

const payment = betterPayment({
  providers: {
    paytr: paytr({
      merchantId: process.env.PAYTR_MERCHANT_ID!,
      merchantKey: process.env.PAYTR_MERCHANT_KEY!,
      merchantSalt: process.env.PAYTR_MERCHANT_SALT!,
      // testMode: defaults to mode === 'sandbox' (sends test_mode=1)
      // timeoutLimit: 30 (minutes)
      // threeDSMode: 'iframe' | 'direct' (default 'iframe', see Direct API 3D Secure)
    }),
  },
});

Sipariş numaraları

PayTR'nin merchant_oid alanı yalnızca harf ve rakam içerebilir. Sipariş numaranızı conversationId olarak verin. Vermezseniz BP1727180000000A1B2C3D4 gibi bir numara üretilir ve paymentId / conversationId olarak döner. Bunu saklayın; refund, cancel ve getPayment bunu kullanır.

iFrame ödeme (3D Secure)

const init = await payment.paytr.initThreeDSPayment({
  ...paymentRequest,            // buyer.gsmNumber and billingAddress.address are sent to PayTR
  conversationId: 'ORDER123',
  callbackUrl: 'https://yoursite.com/orders/ORDER123', // where the customer returns
  installment: undefined,       // undefined: any; 1: single payment only; n: up to n
});

// init.threeDSHtmlContent — a page with the PayTR iframe
// init.redirectUrl        — https://www.paytr.com/odeme/guvenli/<token>

payment_amount, paidPrice'tır (kuruş cinsinden). Sepet kalemleri TL fiyatlarıyla gönderilir.

Direct API ile 3D Secure (kendi kart formunuz)

0.12.0 sürümünde eklendi

threeDSMode: 'direct' ile initThreeDSPayment() PayTR'ın iFrame sayfasını göstermek yerine kartı istekten alır; böylece kendi ödeme sayfası tasarımınızı korursunuz. Direct API token'ıyla (non_3d=0) imzalanmış bir form döner ve bu formu müşterinin tarayıcısı PayTR'a gönderir; PayTR kart verisi için bunu şart koşar. PayTR 3D Secure'u çalıştırır, callbackUrl (veya failUrl) adresine yönlendirir ve sonucu iFrame'deki gibi bildirim adresine gönderir.

const payment = betterPayment({
  providers: {
    paytr: paytr({ merchantId, merchantKey, merchantSalt, threeDSMode: 'direct' }),
  },
});

const init = await payment.paytr.initThreeDSPayment({
  ...paymentRequest,            // paymentCard comes from your own checkout form
  conversationId: 'ORDER123',
  callbackUrl: 'https://yoursite.com/orders/ORDER123',
  // failUrl?: string (defaults to callbackUrl)
  // saveCard?: true (PayTR stores the card; the utoken comes in the notification)
});
// init.threeDSHtmlContent auto-submits the signed card form to https://www.paytr.com/odeme

PayTR hesabınızda Direct API açık olmalıdır. Kayıtlı kartlar threeDSMode ne olursa olsun her zaman bu yolu kullanır.

Bildirim (Bildirim URL)

callbackUrl ödeme sonucunu taşımaz. PayTR sonucu, PayTR mağaza panelinde tanımlı bildirim URL'sine sunucudan sunucuya gönderir.

  1. Bildirim URL'sini https://yoursite.com/api/pay/paytr/callback olarak ayarlayın.
  2. HTTP handler ile bildirim doğrulanır, onCallback'e iletilir ve düz metin OK ile yanıtlanır:
handler: {
  onCallback: async (result) => {
    // result.paymentId === merchant_oid
    // result.status is 'success' or 'failure'
    await db.orders.updatePayment(result.paymentId, result.status);
  },
}

Handler olmadan:

const result = await payment.paytr.completeThreeDSPayment(req.body);
if (result.errorCode === 'INVALID_HASH') return res.status(400).send('bad hash');
await db.orders.updatePayment(result.paymentId, result.status); // make this idempotent
res.type('text/plain').send('OK');

Doğrudan ödeme (3D'siz)

const result = await payment.paytr.createPayment(paymentRequest);

Bu, non_3d=1 ve sync_mode=1 ile Direct API'yi kullanır. PayTR hesabınızın 3D'siz ödemeler için onaylanmış olması gerekir.

Kayıtlı kartlar (utoken / ctoken)

const init = await payment.paytr.createPaymentWithToken({
  utoken, ctoken, cvv, price: '100.00',
  callbackUrl: 'https://yoursite.com/orders/ORDER123',
  conversationId: 'ORDER123',
  buyer: { email, name, surname, ip, gsmNumber },
  basketItems: [{ name: 'Item', price: '100.00', quantity: 1 }],
});
// init.threeDSHtmlContent auto-submits a Direct API form from the browser

İade, iptal ve durum sorgusu

await payment.paytr.refund({ paymentId: 'ORDER123', price: '50.00', currency: 'TRY', ip: '1.2.3.4' });

// PayTR has no void; cancel() is a full refund. Without price, the paid amount is looked up.
await payment.paytr.cancel({ paymentId: 'ORDER123', ip: '1.2.3.4' });

const status = await payment.paytr.getPayment('ORDER123'); // /odeme/durum-sorgu
// 'success', or 'cancelled' when fully refunded

BIN ve taksit

const bin = await payment.paytr.binCheck('552879');
// bin.bankName, bin.cardFamily (brand), bin.cardAssociation (schema), bin.cardType

const info = await payment.paytr.installmentInfo({ binNumber: '552879', price: '100.00' });
// Totals use the commission rates defined on your PayTR account (/odeme/taksit-oranlari)