Guides

Payment Providers

Configure global and African payment providers to process payments for your tenants.

Payment Providers

NovaBilling supports multiple payment providers for global and African markets. Configure one or more providers to process payments for your tenants.

Supported Providers

Provider	Coverage	Payment Methods
Stripe	Global (195+ countries)	Cards, Bank Transfers, Wallets (Apple Pay, Google Pay)
Flutterwave	Nigeria, Kenya, Ghana, South Africa, Uganda, Tanzania	Cards, Bank Transfer, Mobile Money, USSD
Paystack	Nigeria, Ghana	Cards, Bank Transfer, USSD
M-Pesa	Kenya	Mobile Money (STK Push)

Configure Stripe

Stripe is the recommended provider for international payments and customers outside Africa.

curl -X POST http://localhost:3000/api/payment-providers \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "STRIPE",
    "credentials": {
      "secretKey": "sk_live_xxxxx",
      "webhookSecret": "whsec_xxxxx"
    },
    "isActive": true,
    "priority": 1
  }'

import { NovaBillingClient } from 'novabilling';

const client = new NovaBillingClient({ token: 'sk_live_a1b2c3d4...' });

const provider = await client.paymentProviders.configure({
  providerName: 'STRIPE',
  credentials: {
    secretKey: 'sk_live_xxxxx',
    webhookSecret: 'whsec_xxxxx'
  },
  isActive: true,
  priority: 1
});

from novabilling import NovaBilling

client = NovaBilling(token="sk_live_a1b2c3d4...")

provider = client.payment_providers.configure(
    provider_name="STRIPE",
    credentials={
        "secret_key": "sk_live_xxxxx",
        "webhook_secret": "whsec_xxxxx"
    },
    is_active=True,
    priority=1
)

Get your Stripe API keys from the Stripe Dashboard. Use test keys (sk_test_...) for development and live keys (sk_live_...) for production.

Configure Flutterwave

curl -X POST http://localhost:3000/api/payment-providers \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "FLUTTERWAVE",
    "credentials": {
      "publicKey": "FLWPUBK-xxxxx",
      "secretKey": "FLWSECK-xxxxx",
      "encryptionKey": "xxxxx"
    },
    "isActive": true,
    "priority": 2
  }'

const provider = await client.paymentProviders.configure({
  providerName: 'FLUTTERWAVE',
  credentials: {
    publicKey: 'FLWPUBK-xxxxx',
    secretKey: 'FLWSECK-xxxxx',
    encryptionKey: 'xxxxx'
  },
  isActive: true,
  priority: 2
});

provider = client.payment_providers.configure(
    provider_name="FLUTTERWAVE",
    credentials={
        "public_key": "FLWPUBK-xxxxx",
        "secret_key": "FLWSECK-xxxxx",
        "encryption_key": "xxxxx"
    },
    is_active=True,
    priority=2
)

Configure Paystack

curl -X POST http://localhost:3000/api/payment-providers \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "PAYSTACK",
    "credentials": {
      "publicKey": "pk_live_xxxxx",
      "secretKey": "sk_live_xxxxx"
    },
    "isActive": true,
    "priority": 3
  }'

const provider = await client.paymentProviders.configure({
  providerName: 'PAYSTACK',
  credentials: {
    publicKey: 'pk_live_xxxxx',
    secretKey: 'sk_live_xxxxx'
  },
  isActive: true,
  priority: 3
});

provider = client.payment_providers.configure(
    provider_name="PAYSTACK",
    credentials={
        "public_key": "pk_live_xxxxx",
        "secret_key": "sk_live_xxxxx"
    },
    is_active=True,
    priority=3
)

Configure M-Pesa

curl -X POST http://localhost:3000/api/payment-providers \
  -H "Authorization: Bearer sk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "MPESA",
    "credentials": {
      "consumerKey": "xxxxx",
      "consumerSecret": "xxxxx",
      "shortcode": "174379",
      "passkey": "xxxxx",
      "environment": "production"
    },
    "isActive": true,
    "priority": 4
  }'

const provider = await client.paymentProviders.configure({
  providerName: 'MPESA',
  credentials: {
    consumerKey: 'xxxxx',
    consumerSecret: 'xxxxx',
    shortcode: '174379',
    passkey: 'xxxxx',
    environment: 'production'
  },
  isActive: true,
  priority: 4
});

provider = client.payment_providers.configure(
    provider_name="MPESA",
    credentials={
        "consumer_key": "xxxxx",
        "consumer_secret": "xxxxx",
        "shortcode": "174379",
        "passkey": "xxxxx",
        "environment": "production"
    },
    is_active=True,
    priority=4
)

Test a Connection

Before going live, test that your provider credentials are valid:

curl -X POST http://localhost:3000/api/payment-providers/provider_abc123/test \
  -H "Authorization: Bearer sk_live_a1b2c3d4..."

const result = await client.paymentProviders.testConnection('provider_abc123');
console.log(result.success); // true

result = client.payment_providers.test_connection("provider_abc123")
print(result.success)  # True

When multiple providers are configured, NovaBilling uses the priority field to determine which provider to try first. Lower numbers = higher priority. If the primary provider fails, the system automatically falls back to the next provider.

A recommended setup for a global billing system:

Priority	Provider	Use Case
1	Stripe	International cards and wallets
2	Flutterwave	African markets (NG, KE, GH, ZA, UG, TZ)
3	Paystack	Nigerian market fallback
4	M-Pesa	Kenyan mobile money

Credential Security

All provider credentials are encrypted at rest using AES-256 encryption. They are never logged or exposed in API responses.

Edit this pageorReport an issue

Invoices & Payments

Manage invoices and process payments through multiple providers.

Analytics

Track revenue, subscriptions, customers, and payment performance with built-in analytics.