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! 👋

Bakıda fintech sektoru son 2-3 ildə ciddi böyüyüb. Kapital Bank, ABB, Birbank kimi banklar öz API-lərini açıb, e-commerce saytlar artıb, və ödəniş inteqrasiyası bacaran developer-ə tələbat kəskin yüksəlib. LinkedIn-də "Payment Integration Developer" vakansiyalarına baxsan, maaş diapazonu 1800-3500 AZN arasında dəyişir — və bu, Bakı bazarı üçün ciddi rəqəmdir.

Bu məqalədə sənə real bir ssenari üzərindən bank API inteqrasiyasını göstərəcəm. Nəzəriyyə yox, konkret kod, konkret axış.

---

🎯 Ssenari: Online Mağaza üçün Ödəniş Qəbulu

Təsəvvür et ki, Bakıda kiçik bir e-commerce startup-da işləyirsən. Müştəri saytdan məhsul alır, kartla ödəyir, sən də bankdan təsdiq alırsan. Klassik axış belədir:

1. Müştəri "Ödə" düyməsinə basır
2. Backend bankın API-sinə sorğu göndərir
3. Bank ödəniş səhifəsinə redirect edir
4. Müştəri kart məlumatlarını daxil edir
5. Bank nəticəni callback URL-ə göndərir
6. Backend nəticəni yoxlayır və sifarişi təsdiqləyir

Azərbaycanda ən geniş yayılmış ödəniş gateway-lərdən biri E-Commerce Gateway modelidir (Kapital Bank, ABB və digərləri oxşar struktur istifadə edir). Biz bu məqalədə ümumi bir gateway nümunəsi üzərindən gedəcəyik — prinsipi başa düşsən, istənilən banka tətbiq edə bilərsən.

---

🛠️ Layihə Strukturu

Node.js + Express istifadə edəcəyik. Minimal, təmiz, başa düşülən.

project/
├── server.js
├── routes/
│   └── payment.js
├── services/
│   └── bankService.js
├── .env
└── package.json

---

📦 Əvvəlcə Quraşdırma

bashKopyala
mkdir payment-demo && cd payment-demo
npm init -y
npm install express axios dotenv crypto-js uuid

.env faylın belə olacaq:

envKopyala
BANK_API_URL=https://api.bankgateway.az/v1
MERCHANT_ID=your_merchant_id
SECRET_KEY=your_secret_key
CALLBACK_URL=https://yourdomain.az/api/payment/callback
SUCCESS_URL=https://yourdomain.az/payment/success
FAIL_URL=https://yourdomain.az/payment/fail
PORT=3000

---

🔑 Bank Service — Əsas Məntiq

Bu modul bankla bütün kommunikasiyanı idarə edir:

javascriptKopyala
// services/bankService.js
const axios = require('axios');
const CryptoJS = require('crypto-js');
const { v4: uuidv4 } = require('uuid');

class BankService {
  constructor() {
    this.apiUrl = process.env.BANK_API_URL;
    this.merchantId = process.env.MERCHANT_ID;
    this.secretKey = process.env.SECRET_KEY;
  }

  generateSignature(orderId, amount, currency) {
    const data = `${this.merchantId}:${orderId}:${amount}:${currency}`;
    return CryptoJS.HmacSHA256(data, this.secretKey).toString();
  }

  async createOrder(amount, description) {
    const orderId = uuidv4();
    const currency = 'AZN';
    const signature = this.generateSignature(orderId, amount, currency);

    try {
      const response = await axios.post(`${this.apiUrl}/orders`, {
        merchant_id: this.merchantId,
        order_id: orderId,
        amount: amount,
        currency: currency,
        description: description,
        signature: signature,
        callback_url: process.env.CALLBACK_URL,
        success_url: process.env.SUCCESS_URL,
        fail_url: process.env.FAIL_URL
      }, {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.secretKey}`
        },
        timeout: 10000
      });

      return {
        success: true,
        orderId: orderId,
        paymentUrl: response.data.payment_url,
        transactionId: response.data.transaction_id
      };
    } catch (error) {
      console.error('Bank API xətası:', error.response?.data || error.message);
      return {
        success: false,
        error: error.response?.data?.message || 'Bank ilə əlaqə mümkün olmadı'
      };
    }
  }

  verifyCallback(payload) {
    const { order_id, amount, currency, status, bank_signature } = payload;
    const expectedSig = this.generateSignature(order_id, amount, currency);
    return bank_signature === expectedSig && status === 'SUCCESS';
  }
}

module.exports = new BankService();

---

🌐 Route-lar — Ödəniş Başlatma və Callback

javascriptKopyala
// routes/payment.js
const express = require('express');
const router = express.Router();
const bankService = require('../services/bankService');

// Ödənişi başlat
router.post('/create', async (req, res) => {
  const { amount, description } = req.body;

  if (!amount || amount < 0.5) {
    return res.status(400).json({
      error: 'Minimum ödəniş məbləği 0.50 AZN-dir'
    });
  }

  const result = await bankService.createOrder(amount, description);

  if (result.success) {
    // Sifarişi DB-yə yaz (burada sadələşdirmişik)
    console.log(`Sifariş yaradıldı: ${result.orderId} — ${amount} AZN`);
    return res.json({
      payment_url: result.paymentUrl,
      order_id: result.orderId
    });
  }

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

// Bankdan callback
router.post('/callback', (req, res) => {
  const payload = req.body;
  console.log('Bank callback aldıq:', JSON.stringify(payload));

  const isValid = bankService.verifyCallback(payload);

  if (isValid) {
    // DB-də sifarişin statusunu yenilə
    console.log(`✅ Ödəniş təsdiqləndi: ${payload.order_id}`);
    // TODO: sifarişi "paid" et, müştəriyə email göndər
    return res.status(200).json({ received: true });
  }

  console.warn(`⚠️ Callback verifikasiya uğursuz: ${payload.order_id}`);
  return res.status(400).json({ error: 'Invalid signature' });
});

module.exports = router;

---

🚀 Server Faylı

javascriptKopyala
// server.js
require('dotenv').config();
const express = require('express');
const paymentRoutes = require('./routes/payment');

const app = express();
app.use(express.json());
app.use('/api/payment', paymentRoutes);

app.listen(process.env.PORT, () => {
  console.log(`Server ${process.env.PORT} portunda işləyir 🚀`);
});

---

⚠️ Təhlükəsizlik — Bunu Nəzərdən Qaçırma

Azərbaycanda bank inteqrasiyası edəndə bu məqamları mütləq düşün:

• Signature yoxlaması — callback-lərdə HMAC imzanı HƏMİŞƏ yoxla. Əks halda saxta callback göndərib ödənişsiz sifariş təsdiqləmək mümkündür
• Idempotency — eyni callback 2 dəfə gələ bilər. Order ID-yə görə dublikat yoxlaması et
• HTTPS — bank callback-ı HTTP-yə göndərməyəcək. SSL sertifikatın olmalıdır
• Timeout handling — bankın cavab verməsinə 30 saniyə ver, sonra müştəriyə xəbər ver
• Logging — hər sorğunu logla. Problem olanda bankın texniki dəstəyi səndən log istəyəcək

---

📊 Azərbaycan Bazarında Rəqəmlər

Fintech sahəsi haqqında bir neçə maraqlı fakt:

• Azərbaycanda 2025-ci ildə onlayn ödənişlərin həcmi 4.2 milyard AZN-i keçib (Mərkəzi Bank statistikası)
• Birbank, ABB Mobile və Kapital Bank tətbiqlərinin ümumi aktiv istifadəçi sayı 3 milyondan çoxdur
• Ödəniş inteqrasiyası bacaran backend developer-in orta maaşı Bakıda 2200-2800 AZN civarındadır
• Azərbaycandan kənara freelance işləyənlər eyni skill üçün $2000-4000/ay qazanır

---

🏁 Növbəti Addımlar

Bu məqalə sənə əsas axışı göstərdi. İndi nə etməlisən:

1. Sandbox mühiti al — bankların developer portalında test merchant hesabı aç
2. Webhook testing — ngrok istifadə edərək localhost-u callback üçün aç: ngrok http 3000
3. Error handling-i gücləndır — retry mexanizmi, dead letter queue əlavə et
4. Database əlavə et — PostgreSQL və ya MongoDB ilə sifarişləri saxla
5. Admin panel — ödəniş tarixçəsini izləmək üçün sadə dashboard qur

Bankın rəsmi dokumentasiyasını oxumağı unutma. Hər bankın öz nüansları var — bəziləri XML istəyir, bəziləri JSON. Bəziləri 3D Secure məcburi edir, bəziləri yox.

---

💡 Son Söz

Bank API inteqrasiyası çətin deyil, amma məsuliyyətlidir. Burda real pul axışı var — bir bug səbəbindən müştəri 50 AZN ödəyib məhsul almaya bilər, ya da əksinə, ödəmədən məhsul ala bilər. Hər iki hal biznesi vurur.

Test yaz, signature yoxla, logla, və hər zaman pessimist ol — "bu sorğu uğursuz ola bilər" düşüncəsi ilə kod yaz.

Sualın varsa, şərhlərdə yaz. Növbəti məqalədə recurring payments (aylıq abunə ödənişləri) mövzusuna baxacağıq.

Kod yazmağa davam! 🚀