İş Bankası (EST)

İş Bankası'nın sanal POS'u EST (Asseco NestPay) altyapısında çalışır. Better Payment bu altyapıya est sağlayıcısı ve bank: 'isbank' ile bağlanır; bank İş Bankası'nın canlı ortam adresini seçer. 3D Secure istekleri ve callback'leri hash sürüm 3 ile imzalanır: base64(SHA-512(alan adına göre sıralanmış değerler ve sonunda mağaza anahtarı, "|" ile birleştirilmiş)).

YapılandırmaCopy Anchor Link

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

const payment = betterPayment({
  providers: {
    isbank: est({
      bank: 'isbank',
      clientId: process.env.ISBANK_CLIENT_ID!,
      username: process.env.ISBANK_API_USER!,
      password: process.env.ISBANK_API_PASSWORD!,
      storeKey: process.env.ISBANK_STORE_KEY!,
      // storeType?: '3d' | '3d_pay' | '3d_pay_hosting' | '3d_host' (default '3d')
      // department?: number (BOLUM, when the bank assigned one)
      // acceptedMdStatuses?: string[] (default ['1'], see below)
      // baseUrl: defaults from mode (shared EST test host / sanalpos.isbank.com.tr)
    }),
  },
});

clientId İş Bankası mağaza numaranızdır. username ve password API kullanıcısına (XML API), storeKey ise 3D Secure mağaza anahtarına aittir; hepsi İş Bankası'nın üye işyeri panelinden alınır. storeType, İş Bankası'nın mağazanız için tanımladığı 3D modeliyle aynı olmalıdır.

ISBANK_CLIENT_ID=your-store-number
ISBANK_API_USER=your-api-user
ISBANK_API_PASSWORD=your-api-password
ISBANK_STORE_KEY=your-3d-store-key

paymentId sipariş numaranızdır: verdiğiniz conversationId ya da üretilen bir numara.

AdreslerCopy Anchor Link

const payment = betterPayment({
  mode: 'sandbox', // shared EST test host
  providers: {
    isbank: est({ bank: 'isbank', clientId, username, password, storeKey }),
  },
});

Tüm EST bankaları aynı test adresini kullanır; sandbox istekleri, İş Bankası tarafından verilen test mağazası bilgileriyle Asseco'nun test ortamına gider. baseUrl değerini yalnızca İş Bankası size farklı bir adres verdiyse girin.

Doğrudan ödeme (3D'siz)Copy Anchor Link

const result = await payment.isbank.createPayment({ ...paymentRequest, conversationId: 'ORDER123' });
// XML API Auth; success when ProcReturnCode is 00 and Response is Approved

3D SecureCopy Anchor Link

const init = await payment.isbank.initThreeDSPayment({
  ...paymentRequest,
  conversationId: 'ORDER123',
  callbackUrl: 'https://yoursite.com/api/pay/isbank/payment/complete-3ds',
});
// init.threeDSHtmlContent auto-submits a signed form to the İş Bankası 3D gate

3d_pay_hosting ve 3d_host modellerinde kart bilgisi İş Bankası'nın kendi sayfasında alınır, bu yüzden istekte paymentCard gerekmez. İş Bankası sonucu callbackUrl adresine POST eder:

const result = await payment.isbank.completeThreeDSPayment(callbackBody);

Hash, dönen tüm alanların değerlerini kapsar ama alan adlarını kapsamaz; bu yüzden geçerli bir hash tek başına hangi değerin sipariş numarası olduğunu kanıtlamaz. Sonuç İş Bankası ile doğrulanır:

• hash'i geçersiz ya da başka bir clientid için gelen callback INVALID_HASH olarak reddedilir;
• 3d / 3d_host: İş Bankası yalnızca kartı doğrular. mdStatus kabul edilen bir değerse kart XML API Auth ile (md kullanılarak) tahsil edilir ve sonucu İş Bankası'nın cevabı belirler;
• 3d_pay / 3d_pay_hosting: kartı İş Bankası tahsil eder. Onaylı bir callback sipariş durumu sorgusuyla kontrol edilir; İş Bankası'nın doğrulamadığı bir ödeme INVALID_HASH olarak reddedilir.

paymentId ve conversationId yalnızca İş Bankası'nın doğruladığı bir ödemede doldurulur; bu yüzden başarısız bir sonuç hiçbir zaman callback'ten alınan bir sipariş numarası taşımaz.

mdStatusCopy Anchor Link

mdStatus 1, kartın tam olarak doğrulandığı anlamına gelir. 2, 3 ve 4 yarım güvenlidir: kart ya da bankası 3D Secure'a kayıtlı değildir veya yalnızca bir deneme yapılmıştır. 3d ve 3d_host modellerinde varsayılan olarak yalnızca 1 tahsil edilir; diğer değerler MD_STATUS_<değer> ile başarısız olur. Yarım güvenli ödemeleri de tahsil etmek için bunları acceptedMdStatuses içinde listeleyin (örneğin ['1', '2', '3', '4']). Bu durumda ters ibraz (chargeback) sorumluluğu sizde kalabilir. 3d_pay ve 3d_pay_hosting modellerinde kararı İş Bankası verir.

İade, iptal ve durum sorgusuCopy Anchor Link

await payment.isbank.refund({ paymentId: 'ORDER123', price: '50.00', currency: 'TRY', ip: '1.2.3.4' }); // Credit
await payment.isbank.cancel({ paymentId: 'ORDER123', ip: '1.2.3.4' });                                  // Void
const status = await payment.isbank.getPayment('ORDER123');                                             // ORDERSTATUS
// status: 'success' (captured sale), 'cancelled' (voided or refunded),
// 'failure' (declined or unknown order), 'pending' (anything else)

Tarayıcı client'ıCopy Anchor Link

better-payment/client içinde client.isbank özelliği yoktur. Sağlayıcıya providers içindeki anahtarıyla ulaşın:

const result = await client.use('isbank').initThreeDSPayment(request);

Diğer EST bankalarıCopy Anchor Link

Aynı sağlayıcı Halkbank (EST), Şekerbank (EST), TEB (EST) ve Ziraat Bankası (EST) için de çalışır. Birden fazlasını aynı uygulamada kullanmak için EST (NestPay) sayfasına bakın.