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

# Funding Sessions

Nuvion allows you to accept payments from your users through the funding sessions API, `/funding-sessions`. Your server creates a funding session, redirects the user to the checkout URL, and receives a webhook when funds settle.
The available funding sessions are:

* Open Banking: This allows you to accept payment from your users through a hosted bank transfer checkout. The user is redirected to the checkout URL where they can complete the transfer within a time frame. Once the transfer is complete, Nuvion notifies you via webhook.
* MOMO: This allows you to accept payment from your users through mobile money. The user is redirected to a USSD flow on their supplied `msisdn` where they can complete the transfer within a time frame. Once the transfer is complete, Nuvion notifies you via webhook.
* Stablecoin: This allows you to accept stablecoin payment from your users through a hosted crypto checkout. The user is redirected to the checkout URL where they can complete the transfer within a time frame. Once the transfer is complete, Nuvion notifies you via webhook.
* Interac: This allows you to accept payment from your users through a Interac checkout. The user receives an email from interac to complete the payment flow.

### Funding session statuses

| Status               | Terminal | Description                                        |
| -------------------- | -------- | -------------------------------------------------- |
| `awaiting_user`      | No       | Session created, user has not started              |
| `processing`         | No       | User has initiated the bank transfer               |
| `pending_settlement` | No       | Transfer accepted by the bank, awaiting settlement |
| `settled`            | Yes      | Funds credited to the account                      |
| `failed`             | Yes      | Transfer rejected by the bank                      |
| `expired`            | Yes      | Session expired before the user completed payment  |
| `cancelled`          | Yes      | Session was cancelled                              |

When `failed`, the response includes a `failure_code`:

| Code                        | Description                                                     |
| --------------------------- | --------------------------------------------------------------- |
| `payment_blocked`           | Payment was blocked for violating compliance rules              |
| `payment_rejected`          | Payment was rejected by the financial institution               |
| `payment_cancelled`         | User cancelled the payment during authorisation                 |
| `insufficient_funds`        | Account does not have enough funds                              |
| `institution_unavailable`   | Financial institution is temporarily down or not responding     |
| `institution_not_supported` | Financial institution is no longer supported on provider        |
| `provider_error`            | undocumented error fromm provider                               |
| `session_expired`           | Checkout URL expired before the user completed the payment flow |

### Open Banking

Nuvion hosts the bank transfer checkout page. Your server creates a funding session, redirects the user to the hosted URL, and receives a webhook when funds settle.

**Supported currencies:** `GBP`, `EUR`

### Create an Open Banking funding session

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/funding-sessions \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 100000,
      "redirect_url": "https://yourplatform.com/checkout/complete",
      "account_id": "01KR3NQSCAY9SC8WVKWAX2XJAB",
      "unique_reference": "order-2025-111324",
      "narration": "Payment for Order 042",
      "funding_type": "open-banking"
      
    }'
  ```
</CodeGroup>

<ParamField body="amount" type="number" required>
  Amount in the smallest currency unit. `10000` = £100.00 GBP. Minimum: `1`.
</ParamField>

<ParamField body="account_id" type="string" required>
  The ID of the account to credit when the payment settles.
</ParamField>

<ParamField body="redirect_url" type="string" required>
  HTTPS URL to redirect the user to after they complete or abandon the checkout. Must use HTTPS.
</ParamField>

<ParamField body="unique_reference" type="string" required>
  A unique idempotency key for this session. 1–255 characters. Submitting a duplicate reference returns a `409` with the original session's `payment_id`.
</ParamField>

<ParamField body="narration" type="string">
  Display text shown to the user on the checkout page. Max 255 characters.
</ParamField>

<ParamField body="funding_type" type="string" required>
  The funding type for the session (`open-banking`).
</ParamField>

#### Response

```json theme={null}
{
    "status": "success",
    "message": "Funding session created successfully",
    "data": {
        "id": "01KX3R9H42S4RYGK9984FRAPZJ",
        "status": "awaiting_user",
        "unique_reference": "order-2025-111324",
        "amount": 100000,
        "checkout_url": "https://app.nuvion.dev/checkout/01KX3R9H42S4RYGK9984FRAPZJ",
        "expires_at": 1783612811234
    }
}
```

***

### Mobile Money (MOMO) funding session

MOMO funding sessions allow you to accept payments from your users through mobile money. Your server creates a funding session, redirects the user to the USSD flow on their supplied `msisdn`, and receives a webhook when funds settle.

<CodeGroup>
  ```bash TZS theme={null}
  curl -X POST https://api.nuvion.dev/funding-sessions \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 10000,
      "account_id": "acc_01HXYZ5678EFGH",
      "unique_reference": "1q778t8265748",
      "narration": "Checking",
      "funding_type": "momo",
      "meta":{
        "msisdn": "255712345678",
        "channel": "TZ-AIRTEL-C2B"
      }
    }'
  ```

  ```bash KES theme={null}
  curl -X POST https://api.nuvion.dev/funding-sessions \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 1000,
      "account_id": "acc_01HXYZ5678EFGH",
      "unique_reference": "1q778t8265748",
      "narration": "Checking",
      "funding_type": "momo",
      "meta":{
        "msisdn": "254712345678",
        "channel": "KE-SAFARICOM-C2B"
      }
    }'
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Funding session created successfully",
    "data": {
      "id": "01KT9NR04QNKRQ6CWAJD3H3ZXP",
      "status": "awaiting_user",
      "unique_reference": "1q7178t82t1s65748",
      "currency": "TZS",
      "amount": 100000,
      "channel": "TZ-AIRTEL-C2B",
      "msisdn": "255712345678",
      "expires_at": 1780588800759
    }
  }
  ```
</CodeGroup>

<ParamField body="amount" type="string" required>
  The transaction amount.

  <Note>
    Transaction Limits (Stated in Main Currency Units):

    TZS: Min: 1,000 | Max: 5,000,000 | Cents Allowed: No

    KES: Min: 20 | Max: 250,000 | Cents Allowed: No.
  </Note>
</ParamField>

<ParamField body="account_id" type="string" required>
  The ID of the account.
</ParamField>

<ParamField body="unique_reference" type="string" required>
  A unique transaction reference
</ParamField>

<ParamField body="narration" type="string">
  Optional description for the transaction.
</ParamField>

<ParamField body="funding_type" type="string" required>
  Momo, optional: open-banking.
</ParamField>

<ParamField body="meta" type="object" conditional>
  Required meta for momo funding sessions:

  <Expandable title="meta fields">
    <ParamField body="msisdn" type="string" required>
      The payer's mobile number in international format. 254 for KE OR 255 for TZ.
    </ParamField>

    <ParamField body="channel" type="string" required>
      The mobile money channel. One of `TZ-AIRTEL-C2B`, `TZ-TIGO-C2B`, `TZ-HALOTEL-C2B`, `KE-SAFARICOM-C2B`.
    </ParamField>
  </Expandable>
</ParamField>

***

### Funding session for Stablecoin

To fund using stablecoin, create a funding session with `funding_type: crypto`. The user is redirected to a hosted checkout page where they can complete the transfer. Once the transfer is complete, Nuvion notifies you via webhook.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/funding-sessions \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 10000,
      "currency": "USD",
      "account_id": "01HXYZ5678EFGH",
      "redirect_url": "https://yourplatform.com/checkout/complete",
      "unique_reference": "order-2025-001",
      "narration": "Payment for Order 042",
      "funding_type": "crypto"
    }'
  ```
</CodeGroup>

#### Response

<CodeGroup>
  ```json 201 created theme={null}
  {
    "status": "success",
    "message": "Funding session created successfully",
    "data": {
        "id": "01KX3BDKYF01BTNFV38YTW8C7F",
        "status": "awaiting_user",
        "unique_reference": "order-2025-001",
        "currency": "USD",
        "amount": 10000,
        "checkout_url": "https://app.nuvion.dev/crypto-deposit/01KX3BDKYF01BTNFV38YTW8C7F?checkout_id=90c19e84-457b-4be2-a44e-20d96ef262eb&amount=10000",
        "checkout_id": "90c19e84-457b-4be2-a44e-20d96ef262eb",
        "expires_at": null
    }
  }
  ```
</CodeGroup>

<ResponseField name="checkout_id" type="string">
  Unique identifier for the crypto checkout session.
</ResponseField>

***

### Interac Funding Session

Create an Interac funding session to receive funds via Interac payment experience. Once the customer completes the transfer, call the Update Funding Session endpoint to validate the transfer and progress the funding session status.

<CodeGroup>
  ```bash curl -X POST https://api.nuvion.dev/funding-sessions\ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY"\
    -H "Content-Type: application/json"\
    -d '{
      "amount": 10000,
      "account_id": "acc_01HXYZ5678EFGH",
      "redirect_url": "https://yourplatform.com/checkout/complete",
      "unique_reference": "1q7178t82t1s65748",
      "narration": "Checking",
      "funding_type": "interac",
      "meta": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }'
  ```

  ```json 200 OK theme={null}
  {
      "status": "success",
      "message": "Funding session created successfully",
      "data": {
        "id": "01KT9NR04QNKRQ6CWAJD3H3ZXP",
        "amount": 10000,
        "status": "awaiting_user",
        "unique_reference": "1q7178t82t1s65748",
        "reference_number": "ref_01HXYZ7K3M9PQRST4UVWXY2Z6",
      }
  }
  ```
</CodeGroup>

<ParamField body="funding_type" type="string" required>
  interac
</ParamField>

### Update a funding session

After the customer completes the Interac transfer, call this endpoint to validate the transfer and update the funding session status.

<CodeGroup>
  ```bash theme={null}
  curl -X PATCH https://api.nuvion.dev/funding-sessions/01KT9NR04QNKRQ6CWAJD3H3ZXP\
    -H "Authorization: Bearer $NUVION_API_KEY"\
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Funding session updated successfully",
    "data": {
      "id": "01KT9NR04QNKRQ6CWAJD3H3ZXP",
      "amount": 10000,
      "status": "processing",
      "unique_reference": "1q7178t82t1s65748",
      "reference_number": "ref_01HXYZ7K3M9PQRST4UVWXY2Z6",
      "requires_authentication": true,
      "security_question": "What is your mother's maiden name?"
    }
  }
  ```
</CodeGroup>

This endpoint does not require a request body.

Calling this endpoint triggers a validation of the completed Interac transfer and updates the funding session status if funds have been received.

## Webhook

Listen for `funding_session.updated` to receive real-time status changes. Nuvion retries webhook delivery for 72 hours with exponential backoff.