Halkbank (EST)

Halkbank'ın sanal POS'u EST (Asseco NestPay) altyapısında çalışır. Better Payment bu altyapıya est sağlayıcısı ve bank: 'halkbank' ile bağlanır; bank Halkbank'ı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: {
    halkbank: est({
      bank: 'halkbank',
      clientId: process.env.HALKBANK_CLIENT_ID!,
      username: process.env.HALKBANK_API_USER!,
      password: process.env.HALKBANK_API_PASSWORD!,
      storeKey: process.env.HALKBANK_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.halkbank.com.tr)
    }),
  },
});

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

HALKBANK_CLIENT_ID=your-store-number
HALKBANK_API_USER=your-api-user
HALKBANK_API_PASSWORD=your-api-password
HALKBANK_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: {
    halkbank: est({ bank: 'halkbank', clientId, username, password, storeKey }),
  },
});

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

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

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

3D SecureCopy Anchor Link

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

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

const result = await payment.halkbank.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ç Halkbank 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: Halkbank yalnızca kartı doğrular. mdStatus kabul edilen bir değerse kart XML API Auth ile (md kullanılarak) tahsil edilir ve sonucu Halkbank'ın cevabı belirler;
• 3d_pay / 3d_pay_hosting: kartı Halkbank tahsil eder. Onaylı bir callback sipariş durumu sorgusuyla kontrol edilir; Halkbank'ın doğrulamadığı bir ödeme INVALID_HASH olarak reddedilir.

paymentId ve conversationId yalnızca Halkbank'ı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ı Halkbank verir.

İade, iptal ve durum sorgusuCopy Anchor Link

await payment.halkbank.refund({ paymentId: 'ORDER123', price: '50.00', currency: 'TRY', ip: '1.2.3.4' }); // Credit
await payment.halkbank.cancel({ paymentId: 'ORDER123', ip: '1.2.3.4' });                                  // Void
const status = await payment.halkbank.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.halkbank özelliği yoktur. Sağlayıcıya providers içindeki anahtarıyla ulaşın:

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

Diğer EST bankalarıCopy Anchor Link

Aynı sağlayıcı İş Bankası (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.