> ## 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.

# Deposit Flows

> Complete sequence diagrams for all deposit transaction types

## Mobile Money Deposit Flow

Collect payments via mobile money wallets (M-PESA, MTN Money, Airtel Money, etc.)

### Flow Diagram

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

    User->>Kotani Pay: POST /deposit/mobile-money
    Note right of User: Can provide reference_id<br/>or system generates one
    Kotani Pay->>Kotani Pay: Validate API Key & Customer
    Kotani Pay->>Kotani Pay: Generate/Use Transaction ID
    Kotani Pay->>Kotani Pay: Calculate Fees
    Kotani Pay->>Kotani Pay: Status: PENDING

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

    User->>MNO: Enter PIN / Confirm

    alt Provider Has Webhooks
        MNO->>Kotani Pay: Payment Webhook
    else Polling Required
        Note over CronJob: Every 5 Minutes
        CronJob->>Kotani Pay: Check Pending
        Kotani Pay->>MNO: Query Status
        MNO-->>Kotani Pay: Current Status
    end

    alt Payment Successful
        Kotani Pay->>Kotani Pay: Status: SUCCESSFUL
        Note over CronJob: Reconciliation
        CronJob->>Kotani Pay: Credit Deposit Balance

        Kotani Pay->>Integrator: Send Webhook
        alt Webhook Success
            Integrator-->>Kotani Pay: 200 OK
        else Webhook Failed
            Note over CronJob: Retry Every 2h (Max 24h)
        end

    else Payment Failed
        Kotani Pay->>Kotani Pay: Status: FAILED
        Kotani Pay->>Integrator: Send Failed Webhook

    else Timeout (24h)
        Kotani Pay->>Kotani Pay: Status: EXPIRED
        Kotani Pay->>Integrator: Send Timeout Webhook
    end

    User->>Kotani Pay: GET /deposit/mobile-money/status/:reference_id
    Kotani Pay-->>User: Status & Details
```

### Details

**Countries**: Kenya, Uganda, Tanzania, Ghana, Nigeria, Zambia, and more
**Networks**: M-PESA, MTN Money, Airtel Money, Tigo Pesa, Vodacom
**Flow**: STK Push or USSD prompt
**Speed**: Instant to few minutes

**Key Points**:

* Transaction ID can be integrator-provided or system-generated
* Funds credited after reconciliation (not immediate)
* 24-hour timeout for pending payments
* Automatic webhook retries

***

## Bank Checkout Deposit Flow

Collect payments via bank transfers with secure checkout portals.

### Flow Diagram

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

    User->>Kotani Pay: POST /deposit/bank-checkout
    Note right of User: Can provide reference_id<br/>or system generates one
    Kotani Pay->>Kotani Pay: Validate API Key & Customer
    Kotani Pay->>Kotani Pay: Generate/Use Transaction ID
    Kotani Pay->>Kotani Pay: Calculate Fees
    Kotani Pay->>Kotani Pay: Status: PENDING

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

    User->>Bank: Complete Payment
    Bank->>Kotani Pay: Payment Webhook

    alt Payment Successful
        Kotani Pay->>Kotani Pay: Status: SUCCESSFUL
        Note over CronJob: Reconciliation
        CronJob->>Kotani Pay: Credit Deposit Balance

        Kotani Pay->>Integrator: Send Webhook
        alt Webhook Success
            Integrator-->>Kotani Pay: 200 OK
        else Webhook Failed
            Note over CronJob: Retry Every 2h (Max 24h)
        end

    else Payment Failed
        Kotani Pay->>Kotani Pay: Status: FAILED
        Kotani Pay->>Integrator: Send Failed Webhook

    else Timeout (24h)
        Kotani Pay->>Kotani Pay: Status: EXPIRED
        Kotani Pay->>Integrator: Send Timeout Webhook
    end

    User->>Kotani Pay: GET /deposit/bank-checkout/status/:reference_id
    Kotani Pay-->>User: Status & Details
```

### Details

**Countries**: Kenya, South Africa
**Flow**: Redirect to secure bank portal
**Settlement**: Instant to 1 business day
**Banks**: Major banks in supported countries

**Key Points**:

* User redirected to secure bank portal
* Bank provider handles payment collection
* Webhook notification on completion
* Same reconciliation process as mobile money

***

## Card Deposit Flow

Collect payments via credit/debit cards with 3DS support.

### Flow Diagram

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Kotani Pay
    participant Card as Card Provider
    participant CronJob
    participant Integrator

    User->>Kotani Pay: POST /deposit/card
    Note right of User: Can provide reference_id<br/>or system generates one
    Kotani Pay->>Kotani Pay: Validate API Key & Customer
    Kotani Pay->>Kotani Pay: Generate/Use Transaction ID
    Kotani Pay->>Kotani Pay: Calculate Fees
    Kotani Pay->>Kotani Pay: Status: PENDING

    Kotani Pay->>Card: Create Card Session
    Card-->>Kotani Pay: Card Form URL
    Kotani Pay-->>User: Card Payment Form

    User->>Card: Submit Card & CVV

    alt 3DS Required
        Card->>User: Redirect to 3DS
        User->>Card: Complete 3DS Auth
    end

    Card->>Kotani Pay: Payment Webhook

    alt Payment Successful
        Kotani Pay->>Kotani Pay: Status: SUCCESSFUL
        Note over CronJob: Reconciliation
        CronJob->>Kotani Pay: Credit Deposit Balance

        Kotani Pay->>Integrator: Send Webhook
        alt Webhook Success
            Integrator-->>Kotani Pay: 200 OK
        else Webhook Failed
            Note over CronJob: Retry Every 2h (Max 24h)
        end

    else Payment Failed/Declined
        Kotani Pay->>Kotani Pay: Status: FAILED/DECLINED
        Kotani Pay->>Integrator: Send Failed Webhook

    else Timeout (24h)
        Kotani Pay->>Kotani Pay: Status: EXPIRED
        Kotani Pay->>Integrator: Send Timeout Webhook
    end

    User->>Kotani Pay: GET /deposit/card/status/:reference_id
    Kotani Pay-->>User: Status & Details
```

### Details

**Countries**: Multiple African countries
**Supported Cards**: Visa, Mastercard, Verve
**Security**: 3DS authentication supported
**Processing**: Instant authorization

**Key Points**:

* Card details not stored by system
* 3DS adds extra security layer
* Instant authorization from card provider
* Webhook confirms final status

***

## Transaction Statuses

| Status           | Description                                      |
| ---------------- | ------------------------------------------------ |
| `PENDING`        | Awaiting user payment or Payment being processed |
| `INITIATED`      | Payment request sent to provider                 |
| `IN_PROGRESS`    | Payment being processed                          |
| `REQUIRE_REVIEW` | Payment requires manual review                   |
| `SUCCESSFUL`     | Payment confirmed, funds will be credited        |
| `FAILED`         | Payment failed                                   |
| `EXPIRED`        | No confirmation within 24 hours                  |
| `CANCELLED`      | Transaction cancelled                            |
| `DECLINED`       | Payment declined by provider                     |
| `REVERSED`       | Payment reversed                                 |

***

## Common Features

### Transaction ID

* Can be **integrator-provided** via `reference_id`
* Or **system-generated** if not provided
* Must be unique per integrator

### No Rate Locking

Deposits collect fiat currency directly - no exchange rates involved.

### Automatic Reconciliation

* Successful deposits reconciled via cron job
* Funds credited to fiat wallet deposit balance
* Transaction records created for audit

### Status Monitoring

* Webhook callbacks for instant updates (when available)
* Polling every 5 minutes for pending transactions
* 24-hour timeout for unconfirmed payments

### Callback Retries

* Initial delivery via webhook
* Failed callbacks retry every 2 hours
* Maximum retry period: 24 hours

***

## Error Handling

### Insufficient Funds

```json theme={null}
{
  "status": "FAILED",
  "error": "Insufficient funds in account"
}
```

### Invalid Customer

```json theme={null}
{
  "status": "FAILED",
  "error": "Invalid phone number or account details"
}
```

### Card Declined

```json theme={null}
{
  "status": "DECLINED",
  "error": "Card declined by issuer"
}
```

### Timeout

```json theme={null}
{
  "status": "EXPIRED",
  "error": "Payment not confirmed within 24 hours"
}
```

### Duplicate Reference

```json theme={null}
{
  "statusCode": 400,
  "message": "Reference already used"
}
```

***

## Best Practices

### Unique References

Always provide unique `reference_id` values to track transactions.

### Implement Webhooks

Set up webhook endpoint for real-time status updates.

### Handle All Statuses

Integration should handle all transaction statuses gracefully.