16 October Uncategorized

FinTech Libya API Standards — Hana Tech Standard Integration Framework (SIF)

🇱🇾 هذا المقال متاح باللغتين العربية والإنجليزية — Arabic & English

إطار التكامل المعياري (SIF) من هانا تك — معايير APIs لحلول التكنولوجيا المالية في ليبيا

المقدمة

يُعدّ القطاع المالي في ليبيا في مرحلة تحوّل رقمي متسارع، يتطلب أُسسًا تقنية موحدة تضمن التشغيل البيني بين المؤسسات المالية وتُمكّن المطورين من بناء حلول مبتكرة ومتوافقة مع المعايير الدولية. من هذا المنطلق، طوّرت هانا تك إطار التكامل المعياري (Standard Integration Framework — SIF): منظومة متكاملة من معايير APIs وأدوات SDK والوثائق التقنية التي تُشكّل المرجعية التقنية للبناء فوق البنية التحتية المالية الليبية.

شراكة هانا تك مع بنك التجارة والتنمية في ليبيا
هانا تك بالشراكة مع بنك التجارة والتنمية — تطبيق إطار التكامل المعياري في بيئة مصرفية حقيقية

هانا باي: أول منتج ليبي مبني على معايير SIF

يُجسّد هانا باي المثال الحي على ما يُمكن تحقيقه بالبناء على SIF. أول منتج مدفوعات ليبي مطوّر وفق أحدث المعايير الدولية، يُمكّن البنوك الليبية من الوصول إلى الشهادات الدولية وتلبية المتطلبات التنظيمية العالمية.

هانا باي - أول منتج مدفوعات ليبي مبني على إطار التكامل المعياري
هانا باي — يدعم Webhooks والإشعارات الفورية، مع آلية استرداد المدفوعات المُعيارية

لاستكشاف الوثائق: hanatechnology.org/sif | هانا باي

FinTech Libya API Standards — Hana Tech Standard Integration Framework (SIF) Developer Guide

Introduction

Libya’s financial sector is undergoing rapid digital transformation. Hana Tech developed the Standard Integration Framework (SIF) as the open technical standard for FinTech in Libya: a comprehensive ecosystem of API standards, SDKs, webhook protocols, and developer documentation that serves as the definitive reference for building on Libya’s financial infrastructure.

SIF Core Architecture

The framework is organized into four integration layers. Every layer exposes RESTful endpoints, publishes events via webhooks, and defines a standardized return mechanism so integrations remain predictable and auditable.

  1. Authentication & Identity Layer — OAuth 2.0 / OpenID Connect, MFA, KYC/AML endpoints
  2. Core Banking Integration Layer — Account inquiry, transaction history, fund transfers, real-time balances
  3. Payment Processing Layer — Domestic payment rails, payment initiation, settlement, recurring payments
  4. Compliance & Reporting Layer — Regulatory reporting, audit trails, ISO 20022 validation

Step 1 — Authentication: Get an Access Token

All SIF API calls require a bearer token via OAuth 2.0 client credentials. Tokens expire after 3600 seconds.

# Request an access token
curl -X POST https://api.hanatechnology.org/sif/v1/auth/token   -H "Content-Type: application/x-www-form-urlencoded"   -d "grant_type=client_credentials"   -d "client_id=YOUR_CLIENT_ID"   -d "client_secret=YOUR_CLIENT_SECRET"   -d "scope=payments:write accounts:read"
// Token response
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "payments:write accounts:read"
}

Step 2 — Initiate a Payment

Every payment request must include a webhook_url and a return_url. The SIF gateway POSTs status events to webhook_url at each lifecycle stage, and redirects the customer to return_url after authorization.

curl -X POST https://api.hanatechnology.org/sif/v1/payments/initiate   -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."   -H "Content-Type: application/json"   -H "X-Idempotency-Key: txn-2026-10-16-001"   -d '{
    "payment": {
      "amount": "500.00",
      "currency": "LYD",
      "payment_method": "bank_transfer",
      "description": "Invoice #INV-2026-001"
    },
    "debtor": {
      "account_number": "LY89COMM0000000012300695201",
      "account_type": "IBAN",
      "name": "Ahmed Al-Mansouri"
    },
    "creditor": {
      "account_number": "LY21HANA0000000098700111402",
      "account_type": "IBAN",
      "bank_code": "HANA-LY",
      "name": "Fatima Store"
    },
    "webhook_url": "https://your-app.com/webhooks/sif-payment",
    "return_url":  "https://your-app.com/payment/return?ref=txn-2026-10-16-001",
    "metadata": {
      "order_id": "ORD-9912",
      "customer_ref": "CUST-447"
    }
  }'
// Initiation response
{
  "payment_id": "sif_pay_9KzT4mR2vXqL8pN",
  "status": "PENDING",
  "amount": "500.00",
  "currency": "LYD",
  "created_at": "2026-10-16T12:00:00Z",
  "estimated_settlement": "2026-10-16T16:00:00Z",
  "redirect_url": "https://api.hanatechnology.org/sif/v1/payments/sif_pay_9KzT4mR2vXqL8pN/authorize",
  "webhook_registered": true,
  "return_url": "https://your-app.com/payment/return?ref=txn-2026-10-16-001"
}

Step 3 — Webhook Handler

The SIF gateway dispatches signed webhook events to your webhook_url at every lifecycle transition. Respond with HTTP 200 within 5 seconds. Failed deliveries are retried with exponential backoff (1s → 5s → 30s → 5m → 30m). Always verify the X-SIF-Signature header before processing.

// Node.js / Express — Webhook endpoint
const express = require('express');
const crypto  = require('crypto');
const app     = express();

app.use(express.raw({ type: 'application/json' })); // raw body required for signature check

const SIF_WEBHOOK_SECRET = process.env.SIF_WEBHOOK_SECRET;

app.post('/webhooks/sif-payment', (req, res) => {
  // 1. Verify HMAC-SHA256 signature
  const sigHeader = req.headers['x-sif-signature'];
  const expected  = 'sha256=' + crypto
    .createHmac('sha256', SIF_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sigHeader), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);

  // 2. Handle lifecycle events
  switch (event.event_type) {
    case 'payment.pending':
      console.log('Awaiting authorization:', event.payment_id);
      break;
    case 'payment.processing':
      console.log('Sent to bank rails:', event.payment_id);
      break;
    case 'payment.completed':
      markOrderPaid(event.metadata.order_id, event.payment_id);
      break;
    case 'payment.failed':
      handleFailure(event.payment_id, event.error.code, event.error.message);
      break;
    case 'payment.reversed':
      processReversal(event.payment_id, event.reversal_reason);
      break;
    default:
      console.warn('Unknown event:', event.event_type);
  }

  // 3. Acknowledge — always 200 immediately
  res.status(200).json({ received: true });
});

app.listen(3000);

Webhook Event Payload

// payment.completed event payload
{
  "event_id":    "evt_7nYqR2mKpLsX4tZ",
  "event_type":  "payment.completed",
  "api_version": "2026-01",
  "created_at":  "2026-10-16T16:03:22Z",
  "payment_id":  "sif_pay_9KzT4mR2vXqL8pN",
  "status":      "COMPLETED",
  "amount":      "500.00",
  "currency":    "LYD",
  "settlement_ref": "LY-SETTLE-20261016-88821",
  "debtor":   { "account_number": "LY89COMM0000000012300695201", "name": "Ahmed Al-Mansouri" },
  "creditor": { "account_number": "LY21HANA0000000098700111402", "name": "Fatima Store" },
  "metadata": { "order_id": "ORD-9912", "customer_ref": "CUST-447" },
  "return_url": "https://your-app.com/payment/return?ref=txn-2026-10-16-001"
}

Step 4 — Return Redirect: Handling the Customer Return

After the customer completes authorization, SIF redirects them to your return_url with a signed sig parameter. Verify the signature server-side before showing a result. Always treat the webhook event as the source of truth — the redirect is for UX only.

# SIF redirects the customer to:
https://your-app.com/payment/return
  ?ref=txn-2026-10-16-001
  &payment_id=sif_pay_9KzT4mR2vXqL8pN
  &status=completed
  &sig=sha256%3D8a3f2c1d4e...
# Python — Validate the return redirect signature
import hmac, hashlib, urllib.parse

def verify_return_signature(params: dict, secret: str) -> bool:
    sig_received = params.pop('sig', '')
    signed_keys  = sorted(['payment_id', 'ref', 'status'])
    payload = '&'.join(f"{k}={urllib.parse.quote(str(params[k]))}" for k in signed_keys)
    expected = 'sha256=' + hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig_received, expected)

# Flask / Django view
def payment_return(request):
    params   = dict(request.GET)
    is_valid = verify_return_signature(params, SIF_WEBHOOK_SECRET)

    if not is_valid:
        return render(request, 'payment_error.html', {'msg': 'Invalid return signature'})

    return render(request, 'payment_result.html', {
        'status':     request.GET.get('status'),   # completed | failed | pending
        'payment_id': request.GET.get('payment_id'),
        'note': 'Order confirmed once bank settlement completes.'
    })

Step 5 — Check Payment Status (Pull API)

curl -X GET https://api.hanatechnology.org/sif/v1/payments/sif_pay_9KzT4mR2vXqL8pN   -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
{
  "payment_id":  "sif_pay_9KzT4mR2vXqL8pN",
  "status":      "COMPLETED",
  "amount":      "500.00",
  "currency":    "LYD",
  "created_at":  "2026-10-16T12:00:00Z",
  "completed_at":"2026-10-16T16:03:22Z",
  "settlement_ref": "LY-SETTLE-20261016-88821",
  "lifecycle": [
    { "status": "PENDING",    "timestamp": "2026-10-16T12:00:00Z" },
    { "status": "PROCESSING", "timestamp": "2026-10-16T12:01:45Z" },
    { "status": "COMPLETED",  "timestamp": "2026-10-16T16:03:22Z" }
  ]
}

Step 6 — Payment Reversal & Refund

Full and partial reversals are supported. A reversal triggers a payment.reversed webhook event and redirects to your return_url with status=reversed.

curl -X POST https://api.hanatechnology.org/sif/v1/payments/sif_pay_9KzT4mR2vXqL8pN/reverse   -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."   -H "Content-Type: application/json"   -H "X-Idempotency-Key: rev-txn-2026-10-16-001"   -d '{
    "amount":      "500.00",
    "reason":      "CUSTOMER_REQUEST",
    "description": "Customer cancelled order ORD-9912",
    "webhook_url": "https://your-app.com/webhooks/sif-payment"
  }'
{
  "reversal_id":          "sif_rev_4pLmK8nXqTz2vW",
  "original_payment_id":  "sif_pay_9KzT4mR2vXqL8pN",
  "status":               "REVERSAL_PENDING",
  "amount":               "500.00",
  "currency":             "LYD",
  "estimated_completion": "2026-10-17T10:00:00Z"
}

Standard Error Codes

// Error response structure
{
  "error": {
    "code":        "INSUFFICIENT_FUNDS",
    "http_status": 422,
    "message":     "The debtor account does not have sufficient funds.",
    "request_id":  "req_2mKpXqL8tZ7nY",
    "docs_url":    "https://hanatechnology.org/sif/docs/errors#INSUFFICIENT_FUNDS"
  }
}

// SIF Error Code Reference:
// INVALID_ACCOUNT          Account number format invalid or not found
// INSUFFICIENT_FUNDS       Debtor account balance too low
// BANK_UNREACHABLE         Target bank system temporarily unavailable
// DUPLICATE_IDEMPOTENCY    X-Idempotency-Key reused with a different payload
// COMPLIANCE_HOLD          Payment flagged by AML / KYC compliance engine
// REVERSAL_WINDOW_CLOSED   Past the allowed reversal window for this payment type
// WEBHOOK_UNVERIFIABLE     Provided webhook_url returned non-200 on validation ping

Hana Pay — Built on SIF, Ready for Libyan Banks

Hana Pay is the first Libyan payment product built entirely on the SIF standard — supporting the full webhook event lifecycle, signed return redirects, reversals, and ISO 20022 compliance. It serves as both a live product and a reference architecture for banks adopting SIF.

Hana Pay product datasheet - first Libyan payment product on SIF standards
Hana Pay — the reference SIF implementation: webhooks, return redirects, reversals, ISO 20022 compliance. The first Libyan product built to international standards.

Partnership with Bank of Commerce & Development

Hana Tech’s collaboration with Bank of Commerce and Development (BCD) demonstrates SIF operating in a real Libyan banking environment — validating the framework’s API standards, webhook infrastructure, and compliance layer against live banking operations.

Hana Tech and Bank of Commerce and Development Libya - SIF implementation
Hana Tech & Bank of Commerce and Development (BCD) — implementing the Standard Integration Framework to modernize Libya’s financial API infrastructure

Get Started with SIF

Hana Tech is committed to democratizing financial technology in Libya — making international-grade API standards, SDKs, webhook tooling, and developer resources accessible to every Libyan fintech builder and financial institution.

Leave A Comment

Categories