Ziraat Bankası (EST)

Ziraat 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: 'ziraat' ile bağlanır; bank Ziraat 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: {
    ziraat: est({
      bank: 'ziraat',
      clientId: process.env.ZIRAAT_CLIENT_ID!,
      username: process.env.ZIRAAT_API_USER!,
      password: process.env.ZIRAAT_API_PASSWORD!,
      storeKey: process.env.ZIRAAT_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 / sanalpos2.ziraatbank.com.tr)
    }),
  },
});

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

ZIRAAT_CLIENT_ID=your-store-number
ZIRAAT_API_USER=your-api-user
ZIRAAT_API_PASSWORD=your-api-password
ZIRAAT_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: {
    ziraat: est({ bank: 'ziraat', clientId, username, password, storeKey }),
  },
});

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

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

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

3D SecureCopy Anchor Link

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

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

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

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

İade, iptal ve durum sorgusuCopy Anchor Link

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

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

Diğer EST bankalarıCopy Anchor Link

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