Payment Provider Setup

Overview

CrediBill supports 4 African payment providers. Each provider has different requirements, coverage, and features. This guide walks through configuring each provider.

Getting Started

General Setup Process

Get active merchant account with provider
Obtain API credentials (keys, tokens, secrets)
Configure webhook in provider dashboard
Add to CrediBill via settings
Test connection before going live

CrediBill Configuration Steps

Go to Settings → Payment Providers
Click Add Provider
Select provider from dropdown
Enter credentials
Choose environment (Test or Live)
Optionally set as primary provider
Click Save & Test Connection

Flutterwave

Coverage

Attribute	Details
Countries	Uganda, Kenya, Rwanda, Nigeria, Ghana, South Africa
Payment Methods	Mobile Money (MTN, Airtel, Tigo), Cards, Bank Transfer
Currencies	UGX, KES, RWF, NGN, GHS, ZAR, USD
Webhook Signature	SHA256 hash via `verif-hash` header
Documentation	Flutterwave Docs

Setup Steps

1. Create Account

Go to Flutterwave Dashboard
Complete business verification (KYC)
Wait for approval (1-3 business days)

2. Get Credentials

Test Mode:

Log in to Flutterwave dashboard
Navigate to Settings → API
Copy “Public Key (Test)” - format: FLWPUBK_TEST-xxx
Copy “Secret Key (Test)” - format: FLWSECK_TEST-xxx

Live Mode:

Complete business verification
Get approval from Flutterwave support
Switch to Live mode in dashboard
Copy “Public Key (Live)” - format: FLWPUBK-xxx
Copy “Secret Key (Live)” - format: FLWSECK-xxx

3. Configure Webhook

In Flutterwave dashboard, go to Settings → Webhooks
Set webhook URL to: https://your-credibill-instance.com/webhooks/flutterwave
Copy the webhook hash (this is your webhook secret)
Enable webhook notifications
Test webhook delivery

4. Add to CrediBill

In CrediBill Dashboard → Settings → Payment Providers:

Provider: Flutterwave
Public Key: FLWPUBK_TEST-xxx (or live key)
Secret Key: FLWSECK_TEST-xxx (or live key)
Webhook Secret: [webhook hash from step 3]
Environment: Test or Live
Set as Primary: Yes/No

Click Save & Test Connection

Testing

Test Cards

Visa (Success):
  Card Number: 5531886652142950
  CVV: 564
  Expiry: 09/32
  PIN: 3310
  OTP: 12345

Mastercard (Success):
  Card Number: 5531886652142950
  CVV: 564
  Expiry: 09/32

Test Mobile Money

MTN Uganda (Success):

Phone: +256772000000
Amount: Any amount

Airtel Uganda (Success):

Phone: +256700000000
Amount: Any amount

Test Failure Scenarios:

Insufficient Funds: +256772000001
Invalid Account: +256772000002
Declined: +256772000003

Webhook Format

Flutterwave sends webhooks in this format:

{
  "event": "charge.completed",
  "data": {
    "id": 123456,
    "tx_ref": "your-transaction-reference",
    "flw_ref": "FLW-REF-ABC123",
    "amount": 50000,
    "currency": "UGX",
    "status": "successful",
    "payment_type": "mobilemoneyuganda",
    "customer": {
      "id": 123456,
      "email": "[email protected]",
      "phone_number": "+256772123456",
      "name": "John Doe"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Troubleshooting

Issue	Solution
Test credentials not working	Verify environment is “Test”, check for extra spaces in keys
Webhook not received	Check webhook URL is accessible, verify firewall, enable in Flutterwave settings
Payment stuck pending	May take 5-10 seconds, check Flutterwave dashboard
Signature mismatch	Use exact webhook hash from Flutterwave, no modifications

PawaPay

Coverage

Attribute	Details
Countries	Uganda, Kenya, Tanzania, Rwanda, Zambia, Mozambique
Payment Methods	Mobile Money only (MTN, Airtel, Tigo, Vodacom)
Currencies	UGX, KES, TZS, RWF, ZMW, MZN
Webhook Signature	HMAC-SHA256 via `X-Signature` header
Documentation	PawaPay Docs

Setup Steps

1. Create Account

Contact PawaPay sales: [email protected]
Complete KYC (Know Your Customer) verification
Sign merchant agreement
Receive API credentials via email

2. Get Credentials

Test Mode:

API Token: Bearer test_xxx
API URL: https://api.sandbox.pawapay.io
Deposit URL: https://api.sandbox.pawapay.io/deposits

Live Mode:

API Token: Bearer prod_xxx
API URL: https://api.pawapay.io
Deposit URL: https://api.pawapay.io/deposits

3. Configure Webhook

Contact PawaPay support
Provide webhook URL: https://your-credibill-instance.com/webhooks/pawapay
Request webhook secret for signature verification
PawaPay will configure on their end and send you the secret

4. Add to CrediBill

In CrediBill Dashboard → Settings → Payment Providers:

Provider: PawaPay
API Token: Bearer test_xxx (or prod_xxx)
API URL: https://api.sandbox.pawapay.io (test) or https://api.pawapay.io (live)
Webhook Secret: [secret from PawaPay]
Environment: Test or Live
Set as Primary: Yes/No

Click Save & Test Connection

Testing

Test Mobile Money Numbers

MTN Uganda (Instant Success):

Phone: +256777000001
MSISDN: 256777000001

MTN Uganda (Delayed Success ~5s):

Phone: +256777000003
Result: Success after 5 seconds

Airtel Kenya (Success):

Phone: +254733000001
MSISDN: 254733000001

Failed Transactions:

Insufficient Funds: +256777000002
Invalid Account: +256777000004

Webhook Format

PawaPay sends webhooks in this format:

{
  "depositId": "dep_abc123",
  "status": "COMPLETED",
  "requestedAmount": "50000",
  "depositedAmount": "50000",
  "currency": "UGX",
  "country": "UGA",
  "correspondent": "MTN_MOMO_UGA",
  "payer": {
    "type": "MSISDN",
    "address": "256777123456"
  },
  "created": "2024-01-15T10:30:00Z"
}

Status values: PENDING, COMPLETED, FAILED, CANCELLED

Troubleshooting

Issue	Solution
API authentication fails	Check API token has “Bearer ” prefix, verify exact spacing
Webhook secret invalid	Contact PawaPay support for new secret, ensure copied exactly
Test numbers don’t work	Use exact numbers above, wait 5+ seconds for delayed scenarios
Payment stuck pending	PawaPay mobile money may take 1-5 minutes, check dashboard

Pesapal

Coverage

Attribute	Details
Countries	Kenya, Uganda, Tanzania, Rwanda, Malawi, Zambia
Payment Methods	Cards (Visa, Mastercard), Mobile Money (M-Pesa, Airtel, Tigo)
Currencies	KES, UGX, TZS, RWF, MWK, ZMW, USD
Webhook Signature	OAuth + API verification
Documentation	Pesapal Docs

Setup Steps

1. Create Account

Go to Pesapal
Register as merchant
Complete business verification (KYC)
Wait for approval

2. Get Credentials

Test Mode:

Log in to Pesapal dashboard
Go to Settings → API Integration
Copy “Consumer Key (Demo)” - format: qkio1BGGYAXTu2JOfm7XSXNruoZsrqEW
Copy “Consumer Secret (Demo)” - format: osGQ364R49cXKeOYSpaOnT++rHs=

Live Mode:

Switch to Live mode in dashboard
Copy “Consumer Key (Live)”
Copy “Consumer Secret (Live)“

3. Configure IPN (Webhook)

In Pesapal dashboard, go to Settings → IPN
Set IPN URL to: https://your-credibill-instance.com/webhooks/pesapal
Enable IPN notifications
Save settings

4. Add to CrediBill

In CrediBill Dashboard → Settings → Payment Providers:

Provider: Pesapal
Consumer Key: qkio1BGGYAXTu2JOfm7XSXNruoZsrqEW (or live key)
Consumer Secret: osGQ364R49cXKeOYSpaOnT++rHs= (or live secret)
IPN URL: https://your-credibill-instance.com/webhooks/pesapal
Environment: Test or Live
Set as Primary: Yes/No

Click Save & Test Connection

Testing

Test Cards

Visa (Success):

Card Number: 4111111111111111
CVV: 123
Expiry: 12/25

Mastercard (Success):

Card Number: 5500000000000004
CVV: 123
Expiry: 12/25

Test M-Pesa

Phone: +254722000000
PIN: Any 4 digits
Result: Success

Test Failure Scenarios

Insufficient Funds: 4000000000000002
Declined: 4000000000000069
Invalid Card: Any invalid number

Webhook Format

Pesapal sends IPN (Instant Payment Notification) in this format:

{
  "OrderTrackingId": "abc-123-def-456",
  "OrderMerchantReference": "your-transaction-ref",
  "OrderNotificationType": "COMPLETED",
  "Status": "COMPLETED",
  "OrderAmount": "500.00",
  "OrderCurrency": "KES"
}

Status values: COMPLETED, FAILED, CANCELLED, PENDING

Troubleshooting

Issue	Solution
Credentials not working	Verify copy-paste accuracy, check for leading/trailing spaces
IPN not received	Ensure HTTPS certificate is valid, check firewall
Test cards declined	Use exact numbers above, check expiry date format
Integration fails	Check OAuth credentials, verify IPN URL is HTTPS

DPO (Direct Pay Online)

Coverage

Attribute	Details
Countries	Pan-Africa (40+ countries)
Payment Methods	Cards (Visa, Mastercard, Amex), Mobile Money, EFT
Currencies	Multiple African currencies + USD, EUR, GBP
Webhook Signature	XML API verification with CompanyToken
Documentation	DPO Docs

Setup Steps

1. Create Account

Contact DPO sales: https://www.directpay.online/
Complete merchant application
Provide business documentation
Wait for approval (3-5 business days)

2. Get Credentials

Test Mode:

Company Token: 9F416C11-127B-4DE2-AC7A-D5E4E4CAA09C
Service Type: 3854
API URL: https://secure.3gdirectpay.com/

Live Mode:

Company Token: [Your unique token - provided by DPO]
Service Type: [Your service type - provided by DPO]
API URL: https://secure.3gdirectpay.com/

3. Configure Callback URL

Log in to DPO merchant portal
Go to Settings → Integration
Set Callback URL: https://your-credibill-instance.com/webhooks/dpo
Save settings

4. Add to CrediBill

In CrediBill Dashboard → Settings → Payment Providers:

Provider: DPO
Company Token: 9F416C11-127B-4DE2-AC7A-D5E4E4CAA09C (or live token)
Service Type: 3854 (or live service type)
API URL: https://secure.3gdirectpay.com/
Environment: Test or Live
Set as Primary: Yes/No

Click Save & Test Connection

Testing

Test Cards

Visa (Success):

Card Number: 4000000000000002
CVV: 123
Expiry: 12/25

Mastercard (Success):

Card Number: 5200000000000007
CVV: 123
Expiry: 12/25

Test Mobile Money

Select MTN Mobile Money
Phone: Any valid number format
Result: Simulated success

Test Failure Scenarios

Approved: 4000000000000002
Declined: 4000000000000010
Insufficient Funds: 4000000000000028

Webhook Format

DPO sends callbacks in XML format:

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>9F416C11-127B-4DE2-AC7A-D5E4E4CAA09C</CompanyToken>
  <Result>000</Result>
  <ResultExplanation>Transaction Paid</ResultExplanation>
  <TransactionToken>ABC-123-DEF</TransactionToken>
  <TransactionRef>your-transaction-reference</TransactionRef>
  <TransactionAmount>500.00</TransactionAmount>
  <TransactionCurrency>UGX</TransactionCurrency>
  <TransactionStatus>Paid</TransactionStatus>
  <TransactionDate>2024-01-15 10:30:00</TransactionDate>
</API3G>

Result codes: 000 (Paid), 001 (Failed), other codes for specific errors

Troubleshooting

Issue	Solution
Company Token rejected	Verify token format, check for extra spaces
Service Type incorrect	Use exactly “3854” for test, verify live type
Callback not received	Ensure callback URL has HTTPS, valid certificate
XML parsing error	Check raw callback response format

Multi-Provider Strategy

Primary + Backup Setup

Recommended configuration:

Set one provider as primary (default for all payments)
Add second provider as backup for failover
CrediBill automatically fails over if primary unavailable

Example:

Primary: Flutterwave (best coverage in Uganda)
Backup: PawaPay (mobile money specialist)

Country-Specific Routing

Route by customer country:

Uganda:
  Primary: Flutterwave
  Backup: PawaPay

Kenya:
  Primary: PawaPay
  Backup: Pesapal

Tanzania:
  Primary: PawaPay
  Backup: DPO

Multi-Country:
  Mobile Money: PawaPay (lowest fees)
  Cards: DPO (best coverage)

Payment Method Routing

Route by payment method:

Mobile Money:
  Primary: PawaPay (lowest fees, fastest)
  Backup: Flutterwave (wide coverage)

Cards:
  Primary: DPO (pan-African)
  Backup: Pesapal (strong in East Africa)

Bank Transfer:
  Primary: Flutterwave (best support)

Production Checklist

Provider Setup

Live merchant account created
Business verification completed with provider
Live API credentials obtained
Webhook URL configured in provider dashboard
Webhook signature verified working
SSL/HTTPS certificate is valid
Test connection succeeds in CrediBill

CrediBill Configuration

Environment set to Live (not Test)
Primary provider configured
Backup provider configured (optional)
Webhook secret matches provider exactly
No test data in production
Error notifications configured

Testing

Test successful payment end-to-end
Test failed payment and retry logic
Test webhook delivery and signature verification
Test multiple payment methods (if provider supports)
Test idempotency (duplicate webhook handling)
Monitor logs for first 24 hours

Monitoring

Payment success rate tracked (target: >95%)
Webhook delivery monitored (target: 99.9%)
Failed payments monitored
Error alerts configured
Provider status page monitored
Daily reconciliation spot-checks

Common Issues

Test Credentials Not Working

Cause: Using test credentials in Live mode or vice versa Solution:

Double-check environment is “Test” in CrediBill
Verify credentials are for test, not live
Don’t use live credentials in test environment

Webhook Not Received

Causes:

Webhook URL not publicly accessible
HTTPS certificate invalid
Firewall blocking provider IPs
Provider disabled webhooks

Solution:

Test webhook URL manually: curl -X POST https://your-url.com/webhooks/provider
Check provider dashboard for webhook delivery logs
Verify firewall rules
Enable webhooks in provider settings

Payment Stuck in Pending

Cause: Provider API slow response or webhook delivery delay Solution:

Check provider dashboard for payment status
Wait 5-10 minutes for mobile money
Check webhook logs for delivery attempts
Contact provider support if stuck > 1 hour

Signature Verification Fails

Cause: Webhook secret wrong or corrupted Solution:

Copy webhook secret again from provider dashboard
Don’t add/remove any characters
Clear any extra spaces
Test connection again in CrediBill

Support

Provider Support Contacts

Flutterwave: [email protected]
PawaPay: [email protected]
Pesapal: [email protected]
DPO: [email protected]

CrediBill Support

Technical issues: [email protected]
Integration help: [email protected]
Billing questions: [email protected]

Get Started

Core Concepts

Payments

Payment Provider Integration

Webhooks

Security

Billing Logic

API Reference

Support

​Overview

​Getting Started

​General Setup Process

​CrediBill Configuration Steps

​Flutterwave

​Coverage

​Setup Steps

​1. Create Account

​2. Get Credentials

​3. Configure Webhook

​4. Add to CrediBill

​Testing

​Test Cards

​Test Mobile Money

​Webhook Format

​Troubleshooting

​PawaPay

​Coverage

​Setup Steps

​1. Create Account

​2. Get Credentials

​3. Configure Webhook

​4. Add to CrediBill

​Testing

​Test Mobile Money Numbers

​Webhook Format

​Troubleshooting

​Pesapal

​Coverage

​Setup Steps

​1. Create Account

​2. Get Credentials

​3. Configure IPN (Webhook)

​4. Add to CrediBill

​Testing

​Test Cards

​Test M-Pesa

​Test Failure Scenarios

​Webhook Format

​Troubleshooting

​DPO (Direct Pay Online)

​Coverage

​Setup Steps

​1. Create Account

​2. Get Credentials

​3. Configure Callback URL

​4. Add to CrediBill

​Testing

​Test Cards

​Test Mobile Money

​Test Failure Scenarios

​Webhook Format

​Troubleshooting

​Multi-Provider Strategy

​Primary + Backup Setup

​Country-Specific Routing

​Payment Method Routing

​Production Checklist

​Provider Setup

​CrediBill Configuration

​Testing

​Monitoring

​Common Issues

​Test Credentials Not Working

​Webhook Not Received

​Payment Stuck in Pending

​Signature Verification Fails

​Support

​Provider Support Contacts

​CrediBill Support

Overview

Getting Started

General Setup Process

CrediBill Configuration Steps

Flutterwave

Coverage

Setup Steps

1. Create Account

2. Get Credentials

3. Configure Webhook

4. Add to CrediBill

Testing

Test Cards

Test Mobile Money

Webhook Format

Troubleshooting

PawaPay

Coverage

Setup Steps

1. Create Account

2. Get Credentials

3. Configure Webhook

4. Add to CrediBill

Testing

Test Mobile Money Numbers

Webhook Format

Troubleshooting

Pesapal

Coverage

Setup Steps

1. Create Account

2. Get Credentials

3. Configure IPN (Webhook)

4. Add to CrediBill

Testing

Test Cards

Test M-Pesa

Test Failure Scenarios

Webhook Format

Troubleshooting

DPO (Direct Pay Online)

Coverage

Setup Steps

1. Create Account

2. Get Credentials

3. Configure Callback URL

4. Add to CrediBill

Testing

Test Cards

Test Mobile Money

Test Failure Scenarios

Webhook Format

Troubleshooting

Multi-Provider Strategy

Primary + Backup Setup

Country-Specific Routing

Payment Method Routing

Production Checklist

Provider Setup

CrediBill Configuration

Testing

Monitoring

Common Issues

Test Credentials Not Working

Webhook Not Received

Payment Stuck in Pending

Signature Verification Fails

Support

Provider Support Contacts

CrediBill Support