Funding Session

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

number

required

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

string

required

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

string

required

HTTPS URL to redirect the user to after they complete or abandon the checkout. Must use HTTPS.

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.

string

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

string

required

The funding type for the session (open-banking, momo, interac, crypto).

object

Additional key-value metadata to attached for Mobile Money funding sessions.

Show meta fields

string

The payer’s mobile number in international format. Required for mobile money funding sessions.

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.

Example Funding Session Object

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

number

required

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

string

required

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

string

The funding type. For open banking, specify open-banking.

string

required

HTTPS URL to redirect the user to after they complete or abandon the checkout. Must use HTTPS.

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.

string

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

object

Additional key-value metadata to attached for mobile money funding session.

Show meta fields

string

The payer’s mobile number in international format. Required for mobile money funding sessions.

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.

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

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

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

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

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

Response

{
  "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
  }
}

Update a funding session

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

curl -X PATCH https://api.nuvion.dev/funding-sessions/01KT9NR04QNKRQ6CWAJD3H3ZXP\
  -H "Authorization: Bearer $NUVION_API_KEY"\
  -H "Content-Type: application/json"

{
  "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?"
  }
}

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.

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

{
  "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
          }
      ]
  }
}

Note: this endpoint has other funding session types included in them. Filtering by account_id shows funding session created under an account.

Retrieve a funding session

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

  -H "Authorization: Bearer $NUVION_API_KEY"\
  -H "Content-Type: application/json"\ 

{
  "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
  }
}

{
  "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
  }
}

Check session status

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

Note: Failure object is optional and only appears if session fails

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

  {
    "status": "error",
    "message": "The value for 'amount' should be between 1000 and 5000000.", 
    "type": "error_validation_value_out_of_range"
  }

{
  "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."
      }
    }
  ]
}

{
    "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"
}

{
    "status": "error",
    "message": "A record with this {resource} already exists. Please use different details or check your existing records.",
    "type": "error_duplicate_resource"
}

{
    "status": "error",
    "message": "One of our partner services is temporarily unavailable. Please try again in a few minutes.",
    "type": "error_system_dependency_unavailable"
}

Webhook

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

​The Funding Session object

​Funding session statuses

​Funding session failure codes

​Create a funding session

​Request Parameters

​Response

​Update a funding session

​Retrieve funding sessions

​Retrieve a funding session

​Check session status

​Error Response

​Webhook

The Funding Session object

Funding session statuses

Funding session failure codes

Create a funding session

Request Parameters

Response

Update a funding session

Retrieve funding sessions

Retrieve a funding session

Check session status

Error Response

Webhook