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

# Onramp Flow (Fiat → Crypto)

> This document shows the complete onramp flow for converting fiat to crypto, including payment collection and crypto delivery.

**Available Countries**: South Africa, Ivory Coast, Benin, Congo B, Gabon, Burkina Faso, Malawi, Mozambique, Senegal, Sierra Leone, Zambia

***

## 1. Transaction Initiation

Creating an onramp transaction with rate locking.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Kotani Pay
    participant Integrator

    User->>Kotani Pay: POST /onramp/crypto
    Kotani Pay->>Kotani Pay: Validate API Key
    Kotani Pay->>Kotani Pay: Generate Transaction ID
    Kotani Pay->>Kotani Pay: Lock Exchange Rate (Fiat→Crypto)
    Kotani Pay->>Kotani Pay: Calculate Crypto Amount & Fees

    alt Has Crypto Wallet
        Kotani Pay->>Kotani Pay: Validate Wallet Address
        Note over Kotani Pay: Mode: CRYPTO_DELIVERY
    else No Crypto Wallet
        Note over Kotani Pay: Mode: FIAT_WALLET_CREDIT
    end

    Kotani Pay-->>User: Transaction ID & Payment Instructions
```

***

## 2. Fiat Payment Collection

### Mobile Money Payment

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Kotani Pay
    participant MNO as Mobile Money Network

    Kotani Pay->>MNO: Initiate Collection Request
    MNO-->>User: STK Push / USSD Prompt
    MNO->>MNO: Status: PENDING

    User->>MNO: Enter PIN / Confirm Payment
    MNO->>Kotani Pay: Payment Callback (Success/Failed)
    Kotani Pay->>Kotani Pay: Status: CRYPTO_PENDING
```

**Available Countries**: All supported countries
**Networks**: M-PESA, MTN Money, Airtel Money, Orange Money

### Bank Checkout Payment

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Kotani Pay
    participant Bank as Bank Provider

    Kotani Pay->>Bank: Create Checkout Session
    Bank-->>Kotani Pay: Checkout URL
    Kotani Pay-->>User: Redirect to Bank Portal

    User->>Bank: Complete Bank Payment
    Bank->>Kotani Pay: Payment Webhook
    Kotani Pay->>Kotani Pay: Status: CRYPTO_PENDING
```

### Fiat Wallet Deduction

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Kotani Pay

    Kotani Pay->>Kotani Pay: Check Fiat Balance
    alt Insufficient Balance
        Kotani Pay-->>User: 400 Insufficient Funds
    else Sufficient Balance
        Kotani Pay->>Kotani Pay: Reserve Fiat Amount
        Kotani Pay->>Kotani Pay: Status: CRYPTO_PENDING
    end
```

***

## 3. Crypto Delivery

### Lightning Network Delivery

```mermaid theme={null}
sequenceDiagram
    participant Kotani Pay
    participant Lightning as Lightning Network

    Kotani Pay->>Kotani Pay: Validate Lightning Invoice
    Kotani Pay->>Lightning: Pay Lightning Invoice
    Lightning-->>Kotani Pay: Payment Preimage

    alt Payment Success
        Kotani Pay->>Kotani Pay: Status: SUCCESS
        Kotani Pay->>Kotani Pay: Deduct Fiat
    else Payment Failed
        Kotani Pay->>Kotani Pay: Status: FAILED
        Kotani Pay->>Kotani Pay: Refund to Fiat Wallet
    end
```

### EVM Chain Delivery

```mermaid theme={null}
sequenceDiagram
    participant Kotani Pay
    participant Blockchain as EVM Chain

    Kotani Pay->>Kotani Pay: Validate EVM Address
    Kotani Pay->>Blockchain: Initiate Token Transfer
    Blockchain-->>Kotani Pay: Transaction Hash
    Kotani Pay->>Kotani Pay: Status: PROCESSING

    loop Monitor Confirmations (3+ blocks)
        Kotani Pay->>Blockchain: Check Status
        alt Confirmed
            Blockchain-->>Kotani Pay: Confirmed
            Kotani Pay->>Kotani Pay: Status: SUCCESS
            Kotani Pay->>Kotani Pay: Deduct Fiat
        else Failed
            Kotani Pay->>Kotani Pay: Retry (Max 3)
            alt Max Retries
                Kotani Pay->>Kotani Pay: Status: FAILED
                Kotani Pay->>Kotani Pay: Refund to Fiat Wallet
            end
        end
    end
```

**Supported Networks**: Ethereum, Polygon, Arbitrum, Base, Optimism
**Tokens**: USDT, USDC, DAI

### TRON Network Delivery

```mermaid theme={null}
sequenceDiagram
    participant Kotani Pay
    participant TRON as TRON Network

    Kotani Pay->>Kotani Pay: Validate TRON Address
    Kotani Pay->>TRON: Initiate TRC20 Transfer
    TRON-->>Kotani Pay: Transaction Hash
    Kotani Pay->>Kotani Pay: Status: PROCESSING

    loop Monitor TronGrid
        Kotani Pay->>TRON: Check Confirmation
        alt Confirmed
            Kotani Pay->>Kotani Pay: Status: SUCCESS
            Kotani Pay->>Kotani Pay: Deduct Fiat
        else Failed
            Kotani Pay->>Kotani Pay: Status: FAILED
            Kotani Pay->>Kotani Pay: Refund to Fiat Wallet
        end
    end
```

**Tokens**: USDT (TRC20)

### Fiat Wallet Credit (No Crypto Wallet)

```mermaid theme={null}
sequenceDiagram
    participant Kotani Pay

    Note over Kotani Pay: No crypto wallet provided
    Kotani Pay->>Kotani Pay: Credit Fiat Wallet
    Kotani Pay->>Kotani Pay: Status: SUCCESS
    Note over Kotani Pay: Credited at crypto rate
```

***

## 4. Webhook Notification

```mermaid theme={null}
sequenceDiagram
    participant Kotani Pay
    participant CronJob
    participant Integrator

    Kotani Pay->>CronJob: Queue Callback Job
    CronJob->>Integrator: POST Webhook (Signed)

    alt Webhook Success
        Integrator-->>CronJob: 200 OK
        CronJob->>Kotani Pay: CALLBACK_SENT
    else Webhook Failed
        CronJob->>CronJob: Retry 3x with Backoff
        alt Retries Exhausted
            CronJob->>CronJob: Cron Retry (Every 2h, Max 24h)
        end
    end
```

***

## Transaction Statuses

| Status             | Description                                  |
| ------------------ | -------------------------------------------- |
| `PENDING`          | Awaiting fiat payment                        |
| `PENDING_PROVIDER` | Payment initiated with provider              |
| `CRYPTO_PENDING`   | Fiat confirmed, crypto transfer in progress  |
| `PROCESSING`       | Blockchain transaction submitted             |
| `SUCCESS`          | Crypto delivered successfully                |
| `FAILED`           | Transaction failed (fiat refunded to wallet) |
| `TIMEOUT`          | Payment not confirmed within 24 hours        |

***

## Key Features

### Rate Locking

* Exchange rate locked at transaction creation
* Valid for 30 minutes
* Auto-refreshed upon payment confirmation

### Flexible Delivery

* **Has Crypto Wallet**: Crypto delivered to user's address
* **No Crypto Wallet**: Fiat credited at crypto rate

### Safety Mechanisms

* Failed crypto transfers automatically refund to fiat wallet
* Up to 3 retry attempts for blockchain transactions
* Balance never lost

***

## Error Handling

### Insufficient Fiat Wallet Balance

```json theme={null}
{
  "statusCode": 400,
  "message": "Insufficient balance in fiat wallet"
}
```

### Invalid Crypto Address

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid crypto address"
}
```

### Crypto Transfer Failed (Auto-Refund)

```json theme={null}
{
  "status": "FAILED",
  "message": "Crypto transfer failed after 3 attempts",
  "refund": {
    "amount": 10000,
    "currency": "KES",
    "destination": "Fiat Wallet",
    "status": "REFUNDED"
  }
}
```

***

## Best Practices

* **Pre-Check Rates**: Use `/rates/onramp-rate` before creating transaction
* **Validate Addresses**: Verify address format matches network
* **Handle Callbacks**: Implement webhook endpoint with HMAC verification
* **Monitor Status**: Poll status endpoint and display transaction hash to users

***

## Testing

Use sandbox mode with test credentials provided in sandbox documentation.