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

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

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

Response

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

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

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

string

required

The transaction amount.

Transaction Limits (Stated in Main Currency Units):TZS: Min: 1,000 | Max: 5,000,000 | Cents Allowed: NoKES: Min: 20 | Max: 250,000 | Cents Allowed: No.

string

required

The ID of the account.

string

required

A unique transaction reference

string

Optional description for the transaction.

string

required

Momo, optional: open-banking.

object

Required meta for momo funding sessions:

Show meta fields

string

required

The payer’s mobile number in international format. 254 for KE OR 255 for TZ.

string

required

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

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.

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

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

string

Unique identifier for the crypto checkout session.

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.

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

{
    "status": "success",
    "message": "Funding session created successfully",
    "data": {
      "id": "01KT9NR04QNKRQ6CWAJD3H3ZXP",
      "amount": 10000,
      "status": "awaiting_user",
      "unique_reference": "1q7178t82t1s65748",
      "reference_number": "ref_01HXYZ7K3M9PQRST4UVWXY2Z6",
    }
}

string

required

interac

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.

Webhook

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

Get Started

Core Concepts

Webhooks

Guides

Funding Sessions