Epoint və PAYRIFF: Azərbaycan Fintech Ödəniş API İnteqrasiyası

Niyə yerli ödəniş API-ləri vacibdir?

Bakıda bir e-commerce layihə və ya SaaS məhsul yazırsan. Stripe yoxdur, PayPal məhdudiyyətlidir. Sənin əlində iki əsas silah var: Epoint və PAYRIFF (Kapital Bank). Bu iki provayder Azərbaycan bazarının ödəniş infrastrukturunun 80%-dən çoxunu təşkil edir.

Bu məqalədə hər ikisinin API arxitekturasını, real inteqrasiya kodunu və production-da qarşılaşacağın reallıqları danışacağıq.

---

Epoint vs PAYRIFF: Hansını seçməli?

Qısa müqayisə:

Əgər sürətli MVP atırsan — Epoint daha sadə API və daha az bürokratiya tələb edir. Əgər bank level etibarlılıq və korporativ müştərilər üçün işləyirsən — PAYRIFF daha ciddi görünür.

---

Epoint İnteqrasiyası: Addım-addım

1. Merchant hesabı aç

Epoint.az saytından müraciət et. Sandbox üçün test credentials alırsan — adətən 1-2 iş günü çəkir. Sənə public_key və secret_key verilir.

2. Ödəniş yaratma (Backend — Node.js)

Epoint REST API istifadə edir. Ödəniş yaratmaq üçün base64-encoded JSON + HMAC imza lazımdır:

javascriptKopyala
const crypto = require('crypto');
const axios = require('axios');

const EPOINT_URL = 'https://epoint.az/api/1/request';
const PUBLIC_KEY = process.env.EPOINT_PUBLIC_KEY;
const SECRET_KEY = process.env.EPOINT_SECRET_KEY;

async function createPayment(amount, orderId, description) {
  const payload = {
    public_key: PUBLIC_KEY,
    amount: amount, // AZN — məsələn 15.00
    currency: 'AZN',
    language: 'az',
    order_id: orderId,
    description: description,
    success_redirect_url: 'https://myapp.az/payment/success',
    error_redirect_url: 'https://myapp.az/payment/error',
  };

  const data = Buffer.from(JSON.stringify(payload)).toString('base64');
  const signature = crypto
    .createHmac('sha1', SECRET_KEY)
    .update(data)
    .digest('base64');

  try {
    const response = await axios.post(EPOINT_URL, {
      data: data,
      signature: signature,
    });

    // response.data.redirect_url — istifadəçini bura yönləndir
    return response.data;
  } catch (error) {
    console.error('Epoint xətası:', error.response?.data);
    throw error;
  }
}

// İstifadə:
createPayment(25.00, 'ORD-20260402-001', 'Premium abunəlik')
  .then(res => console.log('Redirect URL:', res.redirect_url));

3. Callback (Webhook) qəbul etmə

Ödəniş tamamlandıqda Epoint sənin serverinə POST göndərir. Mütləq imzanı yoxla — əks halda saxta callback-lər qəbul edə bilərsən:

javascriptKopyala
app.post('/webhook/epoint', (req, res) => {
  const { data, signature } = req.body;

  const expectedSignature = crypto
    .createHmac('sha1', SECRET_KEY)
    .update(data)
    .digest('base64');

  if (signature !== expectedSignature) {
    console.warn('Saxta callback aşkarlandı!');
    return res.status(400).send('Invalid signature');
  }

  const payload = JSON.parse(
    Buffer.from(data, 'base64').toString('utf-8')
  );

  if (payload.status === 'success') {
    // Sifarişi DB-də "ödənildi" olaraq yenilə
    markOrderAsPaid(payload.order_id, payload.transaction_id);
  }

  res.status(200).send('OK');
});

---

PAYRIFF İnteqrasiyası: Əsas fərqlər

PAYRIFF (Kapital Bank) bir qədər fərqli yanaşma tətbiq edir — Bearer token ilə autentifikasiya və daha strukturlaşdırılmış endpoint-lər:

javascriptKopyala
const PAYRIFF_URL = 'https://api.payriff.com/api/v2/createOrder';
const PAYRIFF_SECRET = process.env.PAYRIFF_SECRET_KEY;
const PAYRIFF_MERCHANT = process.env.PAYRIFF_MERCHANT_ID;

async function createPayriffOrder(amount, orderId) {
  const body = {
    body: {
      amount: amount * 100, // qəpiklərlə — 25.00 AZN = 2500
      currencyType: 'AZN',
      description: `Sifariş #${orderId}`,
      language: 'AZ',
      approveURL: 'https://myapp.az/payment/approve',
      cancelURL: 'https://myapp.az/payment/cancel',
      declineURL: 'https://myapp.az/payment/decline',
    },
    merchant: PAYRIFF_MERCHANT,
  };

  const response = await axios.post(PAYRIFF_URL, body, {
    headers: {
      Authorization: `Bearer ${PAYRIFF_SECRET}`,
      'Content-Type': 'application/json',
    },
  });

  // response.data.payload.paymentUrl — istifadəçini bura yönləndir
  return response.data.payload;
}

Diqqət: PAYRIFF amount-u qəpiklərlə qəbul edir (25.00 AZN = 2500). Epoint isə manatla (25.00). Bu kiçik fərq production-da böyük baş ağrısına çevrilə bilər.

---

Production-a keçərkən 7 vacib məsləhət

1. İmzanı HƏMİŞƏ yoxla — webhook spoofing real təhlükədir
2. Idempotency key istifadə et — eyni ödəniş iki dəfə processing olunmasın
3. Amount-u backend-də hesabla — frontend-dən gələn qiymətə güvənmə
4. Timeout təyin et — API cavab verməsə 10-15 saniyə timeout qoy
5. Retry mexanizmi — network xətalarında 3 cəhd, exponential backoff ilə
6. Loqlama — hər transaction-u transaction_id ilə birlikdə logla
7. Test kartları ilə sınaq — Epoint sandbox kartı: 4169 7414 0000 0000, PAYRIFF üçün dokumentasiyadan bax

---

Maaş reallığı və fürsət

Azərbaycanda fintech bilən backend developer-ə tələbat artır. 2025-2026 statistikasına görə:

• Junior (ödəniş inteqrasiyası təcrübəsi ilə): 1000-1800 AZN
• Middle (Epoint + PAYRIFF + bank API təcrübəsi): 2000-3500 AZN
• Senior (PCI DSS biliyinə yaxın, arxitektura): 3500-6000+ AZN

Birbaş.az, HelloJob və LinkedIn-də "payment integration" açar sözü ilə axtarış etsən, Bakıda ayda 15-20 vakansiya görəcəksən — əksəriyyəti bank, fintech startup və e-commerce şirkətlərindəndir.

---

Nəticə

Epoint və PAYRIFF Azərbaycanda ödəniş qəbul etmək üçün ən real yollardır. İkisi də REST API təqdim edir, ikisinin də sandbox-u var. Fərq detallardadır — amount formatı, autentifikasiya metodu, callback strukturu.

Məsləhətim: bu həftə sandbox açıb test payment keçir. Portfolio-na "payment integration" əlavə etmək sənin CV-ni Bakı bazarında ciddi şəkildə fərqləndirəcək.

Sualın varsa — GitHub repo-nu və ya Telegram kanalımızı izlə. Kod yazmağa davam! 🚀