Test Mode vs Live Mode

Understand the difference between Test and Live environments for safe development and production.

Chapa provides two separate environments so you can safely build, test, and deploy your payment integration:

Test Mode — for development and QA (no real money)
Live Mode — for production (real transactions)

Understanding the difference between these modes is critical to avoid failed payments, invalid keys, and environment-mismatch errors.

Environment Comparison

Feature	Test Mode	Live Mode
Real money	No	Yes
API keys	`CHAPA_TEST_...`	`CHAPA_LIVE_...`
Checkout experience	Simulated	Real payment flows
Webhooks	Test webhook events	Live webhook events
Use case	Development & testing	Production

API Keys

Each environment has its own set of API keys.

Test Key:

CHAPA_TEST_xxxxxxxxxxxxx

Live Key:

CHAPA_LIVE_xxxxxxxxxxxxx

Never mix keys across environments. Using a test key in live mode (or vice versa) will cause authentication or environment errors.

Base URL (Same, Behavior Differs)

Both Test and Live mode use the same API base URL:

https://api.chapa.co

The environment is determined entirely by the API key you send in the Authorization header.

Test Mode Behavior

In Test Mode:

Payments are simulated
No real charges occur
You can safely test:
- Hosted checkout
- Direct charge
- Payouts
- Refunds
- Webhooks

Ideal Use Cases

Local development
Staging environments
QA testing
Automated tests (CI/CD)

Recommended Testing in Test Mode

Test all payment states:

success
failed
cancelled
incomplete
blocked
auth_needed

Verify:

Webhook handling logic
Retry behavior
Idempotency handling
Verification flows

Live Mode Behavior

In Live Mode:

Real customers pay real money
Payouts move real funds
Refunds affect real balances
Webhooks reflect real transactions
Errors impact real users

Treat Live Mode with production-level care.

Before Switching to Live Mode

Make sure you have:

Checklist Item	Status
Completed full testing in Test Mode	Required
Verified webhook endpoint is live and reachable	Required
Enabled required payment methods in the dashboard	Required
Implemented proper error handling and logging	Required
Secured live API keys (secrets manager / env vars)	Required

Webhooks: Test vs Live

Webhook payloads include a mode field.

Test Mode Webhook:

{
  "mode": "test"
}

Live Mode Webhook:

{
  "mode": "live"
}

Always check the mode field if your system processes both test and live events.

Common Environment Errors

API Key Environment Mismatch

Error Message	Meaning
API key environment does not match business environment	Test key used in live mode or live key used in test mode

Payment Not Found

Usually caused by:

Verifying a test transaction using a live key
Verifying a live transaction using a test key
Mixing references across environments

Deployment Checklist (Live Mode)

Before going live, confirm:

Item	Description
API keys	All API calls use `CHAPA_LIVE_...`
Webhook URL	Production-ready and publicly accessible
Webhook handler	Idempotent and handles retries
Payment verification	Enforced before fulfillment
Key storage	Sensitive keys stored securely
Test logic	Test-only logic disabled in production

Best Practices

Use separate configs for test and live environments
Never hardcode API keys in source code
Log environment (test vs live) per transaction
Display environment clearly in admin dashboards
Restrict live keys to production servers only

Next Steps

Quick Start - Get started with Chapa API v2
Accept Payments - Full payment integration guide
Webhooks - Handle payment events in real-time

Test Mode vs Live Mode

On this page