EST (İş Bankası, Ziraat, Halkbank, TEB, Şekerbank)

İş Bankası, Ziraat Bankası, Halkbank, TEB ve Şekerbank aynı EST (Asseco) sanal POS altyapısını kullanır. Tek bir sağlayıcı hepsini kapsar: bank 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', // 'isbank' | 'ziraat' | 'halkbank' | 'teb' | 'sekerbank'
      clientId: process.env.EST_CLIENT_ID!,
      username: process.env.EST_API_USER!,
      password: process.env.EST_API_PASSWORD!,
      storeKey: process.env.EST_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 / the bank's host)
    }),
  },
});

clientId 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 bankanın üye işyeri panelinden alınır. storeType, bankanın mağazanız için tanımladığı 3D modeliyle aynı olmalıdır.

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

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 bank's 3D gate

3d_pay_hosting ve 3d_host modellerinde kart bilgisi bankanın kendi sayfasında alınır, bu yüzden istekte paymentCard gerekmez. Banka 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ç bankayla doğrulanır:

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

paymentId ve conversationId yalnızca bankanı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ı banka 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. EST sağlayıcısına providers içindeki anahtarıyla ulaşın:

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