Funding Session

A funding session lets you accept payments from your users through a hosted checkout, USSD prompt, or email flow (Open Banking, Mobile Money, Stablecoin, or Interac). Your server creates a funding session and receives an asynchronous webhook when funds settle.

The Funding Session object

string

Unique funding session identifier.

string

Funding session status. One of awaiting_user, processing, pending_settlement, settled, failed, expired, or cancelled.

string

The idempotency key provided at creation.

string

ISO 4217 currency code, or USC/UST for stablecoin funding sessions.

number

Amount in the smallest currency unit.

string

The ID of the account credited when the session settles.

string

The ID of the entity that owns the account. Present once the session has been validated (see Update a funding session).

string

Display text shown to the user on the checkout page.

string

The URL supplied at creation. Not present for momo funding sessions.

object

Rail-specific metadata. For momo, includes msisdn and channel. For interac, includes name and email.

string

Hosted checkout URL to redirect the user to. Present for open-banking and crypto funding sessions.

string

Identifier for the hosted checkout session. Present for crypto funding sessions only.

string

Provider-assigned reference for the payment. Present for interac funding sessions.

string

The ID of the underlying payment record. Present once the funding session’s transfer has been validated.

boolean

true when the customer must answer a security question to complete the transfer. Present for interac funding sessions only.

string

The security question the customer must answer. Present only when requires_authentication is true.

number | null

Unix timestamp in milliseconds when the checkout expires. null for crypto and interac, which don’t expose an expiry.

object

Present when status is failed or expired. See Funding session failure codes.

Show failure fields

string

Machine-readable failure reason.

string

Human-readable failure description.

number

Unix timestamp in milliseconds when the session failed.

number

Unix timestamp in milliseconds when the session was created.

number

Unix timestamp in milliseconds when the session was last updated.

Example funding session object

{
  "status": "success",
  "message": "Funding session retrieved successfully",
  "data": {
    "id": "01HXYZ5805ABCDEFGHJKMNPQRS",
    "status": "processing",
    "amount": 10000,
    "currency": "CAD",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "unique_reference": "order-2025-114",
    "narration": "Checking",
    "meta": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "redirect_url": "https://yourplatform.com/checkout/complete",
    "created": 1787946000000,
    "updated": 1787946100000
  }
}

Funding session statuses

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

Funding session failure codes

Present in failure.code when status is failed or expired.

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 by the provider
`provider_error`	Undocumented error from the provider
`session_expired`	Checkout URL expired before the user completed the payment flow

Subscribe to funding_sessions.updated to track a session in real time. See Event types for the full payload schema.

Create a funding session

POST /funding-sessions Creates a funding session. funding_type defaults to open-banking; specify it explicitly for momo, crypto, or interac.

Request parameters

number

required

Amount in the smallest currency unit. 10000 = £100.00 GBP. Minimum 1.

string

required

ISO 4217 currency code, or USC/UST for stablecoin funding sessions.

string

required

The ID of the account to credit when the session settles.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

required

A unique idempotency key for this session. 1–255 characters. Submitting a duplicate reference returns a 409 with the original session.

string

The funding rail. One of open-banking, momo, crypto, or interac. Defaults to open-banking.

string

HTTPS URL to redirect the user to after they complete or abandon the checkout. Required for open-banking, crypto, and interac; not used for momo.

string

ISO 3166-1 alpha-2 country code. Used for open-banking, crypto, and interac; not used for momo, where the country is inferred from meta.channel.

string

Display text shown to the user on the checkout page. Maximum 255 characters.

object

Rail-specific metadata. Required for momo and interac.

Show meta fields

string

The payer’s mobile number in international format. Required for momo.

string

The mobile money channel. One of TZ-AIRTEL-C2B, TZ-TIGO-C2B, TZ-HALOTEL-C2B, KE-SAFARICOM-C2B. Required for momo.

string

The payer’s full name. Required for interac.

string

The payer’s email address. Required for interac.

For momo, meta.channel must be one of:

Currency	Valid `channel` values
TZS	`TZ-AIRTEL-C2B`, `TZ-TIGO-C2B`, `TZ-HALOTEL-C2B`
KES	`KE-SAFARICOM-C2B`

Some rails enforce their own transaction limits. See Funding Sessions: Transaction limits for the current values.

Request

curl -X POST https://api.nuvion.dev/funding-sessions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 52000,
    "currency": "GBP",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "redirect_url": "https://yourplatform.com/checkout/complete",
    "unique_reference": "order-2025-111",
    "narration": "Payment for Order #1042",
    "country_code": "GB"
  }'

curl -X POST https://api.nuvion.dev/funding-sessions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "TZS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "unique_reference": "order-2025-112",
    "narration": "Checking",
    "funding_type": "momo",
    "meta": {
      "msisdn": "255712345678",
      "channel": "TZ-AIRTEL-C2B"
    }
  }'

curl -X POST https://api.nuvion.dev/funding-sessions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000000,
    "currency": "USC",
    "country_code": "US",
    "funding_type": "crypto",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "redirect_url": "https://yourplatform.com/checkout/complete",
    "unique_reference": "order-2025-113",
    "narration": "Payment for Order #1043"
  }'

curl -X POST https://api.nuvion.dev/funding-sessions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "CAD",
    "country_code": "CA",
    "funding_type": "interac",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "redirect_url": "https://yourplatform.com/checkout/complete",
    "unique_reference": "order-2025-114",
    "narration": "Checking",
    "meta": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }
  }'

Response

{
  "status": "success",
  "message": "Funding session created successfully",
  "data": {
    "id": "01HXYZ5801ABCDEFGHJKMNPQRS",
    "status": "awaiting_user",
    "unique_reference": "order-2025-111",
    "currency": "GBP",
    "amount": 52000,
    "checkout_url": "https://app.nuvion.dev/checkout/01HXYZ5801ABCDEFGHJKMNPQRS",
    "expires_at": 1787943900000
  }
}

{
  "status": "success",
  "message": "Funding session created successfully",
  "data": {
    "id": "01HXYZ5802ABCDEFGHJKMNPQRS",
    "status": "awaiting_user",
    "unique_reference": "order-2025-112",
    "currency": "TZS",
    "amount": 100000,
    "channel": "TZ-AIRTEL-C2B",
    "msisdn": "255712345678",
    "expires_at": 1787944200000
  }
}

{
  "status": "success",
  "message": "Funding session created successfully",
  "data": {
    "id": "01HXYZ5804ABCDEFGHJKMNPQRS",
    "status": "awaiting_user",
    "unique_reference": "order-2025-113",
    "currency": "USC",
    "amount": 100000000,
    "checkout_url": "https://app.nuvion.dev/crypto-deposit/01HXYZ5804ABCDEFGHJKMNPQRS?checkout_id=11111111-1111-1111-1111-111111111111&amount=100000000",
    "checkout_id": "11111111-1111-1111-1111-111111111111",
    "expires_at": null
  }
}

{
  "status": "success",
  "message": "Funding session created successfully",
  "data": {
    "id": "01HXYZ5805ABCDEFGHJKMNPQRS",
    "status": "awaiting_user",
    "unique_reference": "order-2025-114",
    "currency": "CAD",
    "amount": 10000,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "reference_number": "CA1111111111",
    "requires_authentication": false,
    "expires_at": null
  }
}

Update a funding session

PATCH /funding-sessions/{id} Validates a completed Interac transfer and progresses the funding session status. This endpoint does not require a request body, and applies only to interac funding sessions.

string

required

Funding session ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl -X PATCH https://api.nuvion.dev/funding-sessions/01HXYZ5805ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

{
  "status": "success",
  "message": "Funding session updated successfully",
  "data": {
    "id": "01HXYZ5805ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
    "payment_id": "01HXYZ5851ABCDEFGHJKMNPQRS",
    "status": "processing",
    "unique_reference": "order-2025-114",
    "amount": 10000,
    "reference_number": "CA1111111111"
  }
}

If the issuer requires additional authentication, the response also includes requires_authentication: true and a security_question to present to the customer.

Retrieve a funding session

GET /funding-sessions/{id} Returns a single funding session, with rail-specific metadata nested under meta.

string

required

Funding session ID.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl https://api.nuvion.dev/funding-sessions/01HXYZ5805ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

{
  "status": "success",
  "message": "Funding session retrieved successfully",
  "data": {
    "id": "01HXYZ5805ABCDEFGHJKMNPQRS",
    "status": "processing",
    "amount": 10000,
    "currency": "CAD",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "unique_reference": "order-2025-114",
    "narration": "Checking",
    "meta": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "redirect_url": "https://yourplatform.com/checkout/complete",
    "created": 1787946000000,
    "updated": 1787946100000
  }
}

{
  "status": "success",
  "message": "Funding session retrieved successfully",
  "data": {
    "id": "01HXYZ5806ABCDEFGHJKMNPQRS",
    "status": "expired",
    "amount": 100000,
    "currency": "TZS",
    "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
    "unique_reference": "order-2025-115",
    "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": 1787950800000
    },
    "created": 1787950500000,
    "updated": 1787950800000
  }
}

List funding sessions

GET /funding-sessions Returns a paginated list of funding sessions for the authenticated entity.

string

Filter by account.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

Filter by status.

string

Filter by currency.

number

Filter by creation date, as a Unix timestamp in milliseconds.

number

Filter by creation date, as a Unix timestamp in milliseconds.

integer

Number of records to return. Between 1 and 100. Defaults to 20.

string

Pagination cursor from a previous response. Omit for the first page.

This endpoint returns funding sessions across all rails. Filter by account_id to see sessions created under a specific account.

Request

curl "https://api.nuvion.dev/funding-sessions?limit=3" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

{
  "status": "success",
  "message": "Funding sessions retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ5805ABCDEFGHJKMNPQRS",
        "status": "processing",
        "amount": 10000,
        "currency": "CAD",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "unique_reference": "order-2025-114",
        "redirect_url": "https://yourplatform.com/checkout/complete",
        "created": 1787946000000,
        "updated": 1787946100000
      },
      {
        "id": "01HXYZ5804ABCDEFGHJKMNPQRS",
        "status": "awaiting_user",
        "amount": 100000000,
        "currency": "USC",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "unique_reference": "order-2025-113",
        "redirect_url": "https://yourplatform.com/checkout/complete",
        "created": 1787945000000,
        "updated": 1787945000000
      },
      {
        "id": "01HXYZ5806ABCDEFGHJKMNPQRS",
        "status": "expired",
        "amount": 100000,
        "currency": "TZS",
        "account_id": "01HXYZ5503ABCDEFGHJKMNPQRS",
        "unique_reference": "order-2025-115",
        "created": 1787950500000,
        "updated": 1787950800000
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": true,
        "limit": 3,
        "has_previous": false,
        "next_cursor": "01HXYZ5806ABCDEFGHJKMNPQRS",
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ5502ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "created",
          "order": "desc"
        }
      }
    }
  }
}

​The Funding Session object

​Funding session statuses

​Funding session failure codes

​Create a funding session

​Request parameters

​Request

​Response

​Update a funding session

​Request

​Response

​Retrieve a funding session

​Request

​Response

​List funding sessions

​Request

​Response

The Funding Session object

Funding session statuses

Funding session failure codes

Create a funding session

Request parameters

Request

Response

Update a funding session

Request

Response

Retrieve a funding session

Request

Response

List funding sessions

Request

Response