> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments & Fonbnk Integration

> Fiat-to-Crypto On-Ramp and Crypto-to-Fiat Off-Ramp via Fonbnk, currency conversion, and webhook verification.

# Payments & Fonbnk Integration

LearnWay enables financial inclusion across emerging markets by allowing students to deposit fiat (to buy study credits/USDT) and withdraw reward earnings (Gems/USDT) straight into local bank accounts or mobile money wallets.

***

## Supported Fiat Currencies & Channels

| Currency | Country      | Supported Channels              |
| -------- | ------------ | ------------------------------- |
| **NGN**  | Nigeria      | Bank Transfer, USSD             |
| **KES**  | Kenya        | M-Pesa Mobile Money             |
| **GHS**  | Ghana        | MTN Mobile Money, Vodafone Cash |
| **UGX**  | Uganda       | Airtel Money, MTN               |
| **ZAR**  | South Africa | EFT Bank Transfer               |
| **BRL**  | Brazil       | PIX Instant Payment             |

***

## Off-Ramp Workflow (Cashing Out)

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User as Student
    participant API as LearnWay Backend
    participant Fonbnk as Fonbnk API
    participant Webhook as Fonbnk Webhook Guard
    participant DB as PostgreSQL

    User->>API: GET /api/v2/payment/quote (crypto=LISK_USDT, fiat=NGN)
    API->>Fonbnk: Request live rate quote
    Fonbnk-->>API: Quote (rate, fees, expiry)
    API-->>User: Present quote to user

    User->>API: POST /api/v2/payment/offramp/initialize (amount, bankDetails)
    API->>API: Verify Wallet PIN & User Balance
    API->>Fonbnk: Create Off-Ramp Order
    Fonbnk-->>API: Order Created (orderId, status=PENDING)
    API->>DB: Save fonbnk_orders record

    Fonbnk-->>Webhook: POST /api/v2/payment/webhook (signature, status=SUCCESS)
    Webhook->>API: Validate HMAC signature
    API->>DB: Update order status to COMPLETED
    API->>User: Push Notification ("Payout Successful")
```

***

## Security & Webhook Verification

Every webhook payload from Fonbnk is cryptographically validated using HMAC SHA-256 signatures via `FonbnkWebhookGuard`. Replay attacks are prevented via timestamp checks and idempotent order processing.