Testing Cards

Testing Cards allow you to safely test card payment flows in Test Mode without moving real money.

They help you validate:

• Payment initialization
• Successful and failed transactions
• Webhook delivery
• Verification and reconciliation logic

When to Use Test Cards

Use test cards when you want to:

• Integrate card payments during development
• Simulate different transaction outcomes
• Verify webhook handling and payment verification
• Test edge cases like failures or insufficient funds

Test Mode Requirement

Before using test cards:

• Use a test secret key (CHAPA_TEST_...)
• Ensure your environment is set to test
• Use test checkout URLs or test direct charge flows

Supported Test Card Details

Success Card

Expected Result: Payment succeeds

Insufficient Funds (Failure)

Expected Result: Payment fails with INSUFFICIENT_FUNDS

Generic Decline

Expected Result: Payment fails with generic decline

Example Test Flow

1. Initialize payment (Hosted or Direct Charge)
2. Use a test card on checkout
3. Observe response: success or failed
4. Receive webhook event: payment.success or payment.failed
5. Verify payment using:

GET /v2/payments/{reference}/verify

Webhook Events in Test Mode

Webhook payloads in test mode include:

{
  "mode": "test"
}

This allows you to:

• Separate test vs live processing
• Prevent test data from affecting production logic

Common Test Scenarios

Best Practices

• Never use real card data in test mode
• Clearly label test transactions in your database
• Ignore test webhooks in production systems
• Test all status transitions before going live

Common Errors

Next Steps

• Testing Mobile - Test mobile money payments
• Test vs Live Mode - Environment configuration
• Webhooks - Handle payment events