JavaScript ilə Bank API İnteqrasiyası: Real Nümunə ilə A-dan Z-yə

JavaScript ilə Bank API İnteqrasiyası: Real Nümunə ilə A-dan Z-yə

Salam, developer dostum! Əgər Bakıda fintech sahəsində işləyirsən və ya iş axtarırsan, bu məqalə sənin üçündür. Azərbaycanda rəqəmsal ödənişlər sürətlə böyüyür — Mərkəzi Bankın 2025 statistikasına görə, ölkədə onlayn ödəniş əməliyyatlarının həcmi ildə 34% artıb. Bu o deməkdir ki, bank API inteqrasiyası bacaran developer-lərə tələbat hər zamankından yüksəkdir.

Bu gün sənə real bir ssenari üzərindən — e-commerce saytında ödəniş qəbulu — bank API inteqrasiyasını addım-addım göstərəcəyəm.

---

Niyə Bu Mövzu Vacibdir?

Bakıda Kapital Bank, ABB, Rabitəbank kimi banklar öz API gateway-lərini inkişaf etdirir. Paymes, E-PUL, GoldenPay kimi ödəniş provayderləri isə artıq developer-dostu API-lər təqdim edir. Əgər sən Node.js bilirsənsə, bu sahədə 1500-3500 AZN maaş aralığında iş tapa bilərsən. Senior səviyyədə isə bu rəqəm 4000-6000 AZN-ə qədər qalxa bilir.

Fintech şirkətləri — məsələn, hesab.az, birbank ekosistemi və ya yeni startaplar — bu bacarığa sahib insanları aktiv axtarır.

---

Əsas Konseptlər: Başlamaqdan Əvvəl Bilməli Olduqların

Bank API inteqrasiyasına girişmədən əvvəl bu terminləri bil:

• Payment Gateway — ödənişi qəbul edən vasitəçi sistem
• Merchant ID — sənin biznesin üçün unikal identifikator
• Callback URL — bank əməliyyat nəticəsini sənə göndərdiyi endpoint
• Idempotency Key — eyni sorğunun təkrar göndərilməsinin qarşısını alan açar
• HMAC Signature — sorğunun həqiqiliyini təsdiqləyən imza

---

Real Nümunə: Ödəniş Sessiyası Yaratmaq

Gəl fərz edək ki, bir e-commerce sayt üçün ödəniş inteqrasiyası edirsən. Müştəri "Ödə" düyməsinə basanda backend-də ödəniş sessiyası yaranmalıdır. Aşağıdakı nümunədə generic bir bank API strukturu istifadə edəcəyik — bu struktur Azərbaycandakı əksər provayderlərin API-lərinə çox yaxındır.

1. Layihə Quraşdırması

bashKopyala
mkdir payment-integration && cd payment-integration
npm init -y
npm install express axios crypto dotenv

2. Environment Dəyişənləri (.env)

envKopyala
MERCHANT_ID=MERCHANT_12345
API_SECRET=s3cr3t_k3y_h3r3
PAYMENT_API_URL=https://api.bankgateway.az/v1
CALLBACK_URL=https://yourapp.az/api/payment/callback

3. Ödəniş Sessiyası Yaratma (paymentService.js)

javascriptKopyala
const axios = require('axios');
const crypto = require('crypto');
require('dotenv').config();

class PaymentService {
  constructor() {
    this.apiUrl = process.env.PAYMENT_API_URL;
    this.merchantId = process.env.MERCHANT_ID;
    this.secret = process.env.API_SECRET;
  }

  // HMAC imza yaratmaq — bank sorğunun səndən gəldiyini bilsin
  generateSignature(payload) {
    const data = Object.keys(payload)
      .sort()
      .map(key => `${key}=${payload[key]}`)
      .join('&');
    return crypto
      .createHmac('sha256', this.secret)
      .update(data)
      .digest('hex');
  }

  // Ödəniş sessiyası yaratmaq
  async createPaymentSession(orderId, amount, currency = 'AZN') {
    const payload = {
      merchant_id: this.merchantId,
      order_id: orderId,
      amount: amount.toFixed(2),
      currency,
      callback_url: process.env.CALLBACK_URL,
      timestamp: Date.now(),
      idempotency_key: `${orderId}_${Date.now()}`
    };

    payload.signature = this.generateSignature(payload);

    try {
      const response = await axios.post(
        `${this.apiUrl}/sessions`,
        payload,
        {
          headers: {
            'Content-Type': 'application/json',
            'X-Merchant-Id': this.merchantId
          },
          timeout: 10000 // 10 saniyə timeout — vacibdir!
        }
      );

      return {
        success: true,
        sessionId: response.data.session_id,
        paymentUrl: response.data.payment_url
      };
    } catch (error) {
      console.error('Ödəniş sessiyası xətası:', error.response?.data || error.message);
      return {
        success: false,
        error: error.response?.data?.message || 'Bank ilə əlaqə mümkün olmadı'
      };
    }
  }

  // Callback-i verify etmək — ən vacib hissə!
  verifyCallback(callbackData) {
    const receivedSignature = callbackData.signature;
    const dataToVerify = { ...callbackData };
    delete dataToVerify.signature;

    const expectedSignature = this.generateSignature(dataToVerify);
    return crypto.timingSafeEqual(
      Buffer.from(receivedSignature, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    );
  }
}

module.exports = new PaymentService();

4. Express Router (paymentRouter.js)

javascriptKopyala
const express = require('express');
const router = express.Router();
const paymentService = require('./paymentService');

// Müştəri ödəniş etmək istəyəndə
router.post('/create', async (req, res) => {
  const { orderId, amount } = req.body;

  if (!orderId || !amount || amount <= 0) {
    return res.status(400).json({ error: 'Yanlış parametrlər' });
  }

  const result = await paymentService.createPaymentSession(orderId, amount);

  if (result.success) {
    // Müştərini bankın ödəniş səhifəsinə yönləndir
    return res.json({
      paymentUrl: result.paymentUrl,
      sessionId: result.sessionId
    });
  }

  return res.status(502).json({ error: result.error });
});

// Bank əməliyyat nəticəsini göndərəndə
router.post('/callback', (req, res) => {
  const isValid = paymentService.verifyCallback(req.body);

  if (!isValid) {
    console.warn('TƏHLÜKƏ: Yanlış imza ilə callback gəldi!');
    return res.status(403).json({ error: 'Invalid signature' });
  }

  const { order_id, status, transaction_id } = req.body;

  if (status === 'SUCCESS') {
    // Sifarişi "ödənildi" kimi işarələ
    console.log(`Sifariş ${order_id} ödənildi. TX: ${transaction_id}`);
    // TODO: Database-də order statusunu yenilə
  } else {
    console.log(`Sifariş ${order_id} uğursuz: ${status}`);
  }

  // Bank 200 cavab gözləyir — əks halda retry edəcək
  res.status(200).json({ received: true });
});

module.exports = router;

---

Azərbaycanlı Developer Kimi Bilməli Olduğun 5 Tələ

1. Timeout qoyma — Yerli bank API-ləri bəzən 5-8 saniyə cavab verir. Timeout qoymasan, istifadəçi gözləyəcək və sən də thread itirəcəksən. Həmişə 10-15 saniyə timeout qoy.

2. Callback-i verify etmə — Bu ən böyük təhlükəsizlik boşluğudur. Əgər signature yoxlamasan, hər kəs sənin callback URL-inə saxta "ödəniş uğurlu" sorğusu göndərə bilər.

3. Idempotency key istifadə etmə — İstifadəçi "Ödə" düyməsinə iki dəfə basarsa, iki dəfə pul çıxmasın. Unikal key ilə bunu qarşısını al.

4. AZN format problemi — Bəzi API-lər məbləği qəpiklə (150 = 1.50 AZN), bəziləri manatla (1.50) gözləyir. Dokumentasiyanı diqqətlə oxu.

5. Test mühiti yoxdur deyə production-da test etmə — Əksər Azərbaycan bankları sandbox mühit verir, amma bəzən gec verir. Səbr et, sandbox olmadan heç vaxt production-a çıxma.

---

Ödəniş Axışı: Böyük Mənzərə

Bütün prosesi belə xülasə edə bilərik:

1. Müştəri → "Ödə" düyməsinə basır
2. Sənin Backend → Bank API-yə session yaradır
3. Bank → Ödəniş URL-i qaytarır
4. Müştəri → Bank səhifəsində kart məlumatlarını daxil edir
5. Bank → Sənin callback URL-inə nəticəni POST edir
6. Sənin Backend → İmzanı yoxlayır, sifarişi yeniləyir
7. Müştəri → "Ödəniş uğurlu" səhifəsini görür

---

Növbəti Addımlar

Bu baza inteqrasiyanı mənimsədikdən sonra bunlara bax:

• Webhook retry mexanizmi — Bank callback göndərə bilməsə nə baş verir?
• Recurring payments — Abunəlik modelləri üçün
• 3D Secure — Əlavə təhlükəsizlik təsdiqləməsi
• Refund API — Geri ödəmə funksionallığı
• Redis ilə session caching — Yüksək yüklənmə üçün

Fintech Azərbaycanda ən sürətlə böyüyən sahələrdən biridir. Bu il ABB və Kapital Bank-ın açıq bankinq API-ləri üzərində yeni imkanlar yaranacaq. Hazır olan developer-lər bu dalğadan maksimum faydalanacaq.

---

Sualın var? Kommentlərdə yaz, real layihələrdən danışaq. Kodu GitHub-da paylaşmaq istəsən, baku-stack-payment-demo repo-su ilə tağ et!