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

> Create and manage funding sessions to accept payments from your users.

A funding session allows you to accept payments from your users through various methods (Open Banking, Mobile Money, Stablecoin, and Interac). Your server creates a funding session, redirects the user to the checkout URL (or initiates a USSD prompt), and receives an asynchronous webhook when funds settle.

## The Funding Session object

<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`, `momo`, `interac`, `crypto`).
</ParamField>

<ParamField body="meta" type="object">
  Additional key-value metadata to attached for Mobile Money funding sessions.

  <Expandable title="meta fields">
    <ParamField body="msisdn" type="string">
      The payer's mobile number in international format. Required for mobile money funding sessions.
    </ParamField>

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

***

```bash Example Funding Session Object theme={null}
  {
    "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",
    "meta": {
      "msisdn": "255712345678",
      "channel": "TZ-AIRTEL-C2B"
    }
  }
```

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

### Funding session failure codes

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 |

***

## Create a funding session

POST /funding-sessions
Initiate a funding session via funding type.

### Request Parameters

<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="funding_type" type="string">
  The funding type. For open banking, specify `open-banking`.
</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="meta" type="object">
  Additional key-value metadata to attached for mobile money funding session.

  <Expandable title="meta fields">
    <ParamField body="msisdn" type="string">
      The payer's mobile number in international format. Required for mobile money funding sessions.
    </ParamField>

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

<CodeGroup>
  ```bash Open-Banking 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",
      "funding_type": "open-banking",
      "redirect_url": "https://yourplatform.com/checkout/complete",
      "unique_reference": "order-2025-001",
      "narration": "Payment for Order #1042"
    }'
  ```

  ```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"
      }
    }'
  ```

  ```bash stablecoin 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,
      "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"
    }'
  ```

  ```bash interac 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",
      "redirect_url": "https://yourplatform.com/checkout/complete",
      "unique_reference": "1q7178t82t1s65748",
      "narration": "Checking",
      "funding_type": "interac",
      "meta": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }'
  ```
</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>

***

***

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

***

## Retrieve funding sessions

To retrieve a paginated list of funding sessions for the authenticated entity.
Make a `GET` request to the `/funding-sessions` endpoint with optional query parameters for pagination and filtering.

<CodeGroup>
  ```bash curl https://api.nuvion.dev/funding-sessions \ theme={null}
    -H "Authorization: Bearer $NUVION_API_KEY"\
    -H "Content-Type: application/json"\
    -d '{
      "account_id": "01HXYZ5678EFGH",
      "status": "awaiting_user",
      "currency": "TZS",
      "created_after": 1735725600000,
      "created_before": 1735729200000,
      "limit": 25,
      "cursor": "eyJpZCI6ICIxM2FiYy00NTY3LTg5MGEtYWJjZC0xMjM0NTY3ODkwIn0",
      "pre_cursor": "eyJpZCI6ICIxM2FiYy00NTY3LTg5MGEtYWJjZC0xMjM0NTY3ODkwIn0"
    }'
  ```

  ```json 200 OK theme={null}
  {
    "message": "Funding sessions retrieved successfully",
    "status": "success",
    "data": {
        "meta": {
            "pagination": {
                "order": "desc",
                "has_next": true,
                "limit": 25,
                "has_previous": false,
                "next_cursor": "01KPDNM1H13KBBKR41YTVD79NC",
                "previous_cursor": null
            },
            "filters_applied": {
                "entity_id": "01KKM2WR1HDTBS5KCM8XPXV1P7",
                "sort": {
                    "field": "created",
                    "order": "desc"
                }
            }
        },
        "data": [
            {
                "id": "01KQVZBG2MNCFRB79HMJ8HW8KZ",
                "status": "expired",
                "amount": 1000,
                "currency": "TZS",
                "account_id": "01KQ72N09YBW311MKQXPYM34E0",
                "unique_reference": "1q778888265746",
                "created": 1777981571156,
                "updated": 1777981631166
            },
            {
                "id": "01KQCJ3HXPYRVBV99FD0GHJ9NT",
                "status": "awaiting_user",
                "amount": 1111,
                "currency": "GBP",
                "account_id": "01KN7GAYJPJ99CYG7PCQ0SF9YH",
                "unique_reference": "x13qx111xxzz1cqxx",
                "checkout_url": "{base_url}/checkout/01KQCJ3HXPYRVBV99FD0GHJ9NT",
                "created": 1777464362934,
                "updated": 1777464362934
            },
            {
                "id": "01KQ2HDETAGC4AFYSVVRPWRJ8A",
                "status": "expired",
                "amount": 5000,
                "currency": "GBP",
                "account_id": "01KN7GAYJPJ99CYG7PCQ0SF9YH",
                "unique_reference": "1777128086338",
                "checkout_url": "{base_url}/checkout/01KQ2HDETAGC4AFYSVVRPWRJ8A",
                "redirect_url": "https://success.com/complete",
                "created": 1777128094538,
                "updated": 1777129594551
            },
            {
                "id": "01KPDXDT0P5CYM0FV38RTNTG75",
                "status": "failed",
                "amount": 5000,
                "currency": "GBP",
                "account_id": "01KN7GAYJPJ99CYG7PCQ0SF9YH",
                "unique_reference": "x10qx3x1zz11cqx1x",
                "checkout_url": "http://localhost:2559/checkout/01KPDXDT0P5CYM0FV38RTNTG75",
                "redirect_url": "https://failure.com/complete",
                "created": 1776436045846,
                "updated": 1776436084490
            }
        ]
    }
  }
  ```
</CodeGroup>

<Note>
  **Note**:  this endpoint has other funding session types included in them. Filtering by account\_id shows funding session created under an account.
</Note>

## Retrieve a funding session

Retrieves the full details of a specific funding session.
Make a `GET` request to the `/funding-sessions/{id}` endpoint.

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

  ```json 200 OK INITIATION STATE theme={null}
  {
    "message": "Funding session retrieved successfully",
    "status": "success",
    "data": {
        "id": "01KQY2VAX8JWWDJ7RZ7M9D25GA",
        "status": "awaiting_user",
        "amount": 1000,
        "currency": "TZS",
        "account_id": "01KQ72N09YBW311MKQXPYM34E0",
        "unique_reference": "1q778dt8265748",
        "narration": "Checking",
        "meta": {
            "msisdn": "255712345678",
            "channel": "TZ-AIRTEL-C2B"
        },
        "created": 1778052344744,
        "updated": 1778052344744
    }
  }
  ```

  ```json 200 OK TERMINAL STATE theme={null}
  {
    "status": "success",
    "message": "Funding session retrieved successfully",
    "data": {
      "id": "01KT9NR04QNKRQ6CWAJD3H3ZXP",
      "status": "expired",
      "amount": 100000,
      "currency": "TZS",
      "account_id": "01KT9KRMA5NM6VHQF23CN36K94",
      "unique_reference": "1q7178t82t1s65748",
      "narration": "Checking",
      "meta": {
        "msisdn": "255712345678",
        "channel": "TZ-AIRTEL-C2B"
      },
      "failure": {
        "code": "SESSION_EXPIRED",
        "message": "The session expired before the user completed the payment flow",
        "failed_at": 1780588800773
      },
      "created": 1780588740759,
      "updated": 1780588800773,
      "expires_at": 1780588800759
    }
  }
  ```
</CodeGroup>

## Check session status

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/v1/funding-sessions/01HXYZ9012MNOP \
    -H "Authorization: Bearer $NUVION_API_KEY"
  ```
</CodeGroup>

<Note>
  **Note:** Failure object is optional and only appears if session fails
</Note>

The `failure.code` field identifies why a payment failed. The `failure.message` field provides a human-readable description of the failure. The `failure.failed_at` field is a timestamp indicating when the failure occurred.
Here are the possible `failure.code` values for a funding session:

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

## Error Response

* Validation errors: Triggered if the payload does not meet the general or provider-specific specifications
* upstream account-issuing client errors: If the downstream account-issuing service returns a 4xx error during creation

<CodeGroup>
  ```json 400 Bad request theme={null}
    {
      "status": "error",
      "message": "The value for 'amount' should be between 1000 and 5000000.", 
      "type": "error_validation_value_out_of_range"
    }
  ```

  ```json 422 Unprocessed content theme={null}
  {
    "status": "error",
    "message": "Validation failed for one or more fields",
    "type": "error_validation_error",
    "validations": [
      {
        "funding_type": {
          "type": "error_validation_value_not_supported",
          "message": "The value 'wrong-value' is not supported for funding_type yet. Please use a supported funding_type."
        }
      }
    ]
  }
  ```

  ```json 404 Not Found theme={null}
  {
      "status": "error",
      "message": "We couldn't find that {resource}. It may have been deleted or the ID might be incorrect.",
      "type": "error_resource_not_found"
  }
  ```

  ```json 409 Conflict theme={null}
  {
      "status": "error",
      "message": "A record with this {resource} already exists. Please use different details or check your existing records.",
      "type": "error_duplicate_resource"
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
      "status": "error",
      "message": "One of our partner services is temporarily unavailable. Please try again in a few minutes.",
      "type": "error_system_dependency_unavailable"
  }
  ```
</CodeGroup>

***

## Webhook

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