Integration Best Practices

This section is designed to help developers integrate with our API more efficiently and reliably. It highlights best practices, common pitfalls, and configuration tips.

We strongly recommend reviewing this page before starting your integration.

​

Phone Number Validation

Proper phone number validation is essential to avoid rejected transactions or delivery failures. Here’s what to keep in mind:

​

Validation Rules

• Length Requirements:
  • Minimum: 8 digits (excluding country code)
  • Maximum: 15 digits (including country code)
• Characters:
  • Only digits allowed. No spaces, +, or symbols.

​

Country Code Formatting

• Always prepend the correct country code.
• Example:
  • Kenya: 254712345678
  • Ghana: 233501234567
• Do not prefix with +, 00, or local formats like 07xxx.

​

Common Pitfalls

• Using local formats (e.g., 0712...) without converting to international format.
• Adding trailing symbols ike +
• Mismatching country code and country sent for the API

​

Callback Configuration

Callbacks allow us to notify your system of transaction events. To ensure proper delivery, follow the setup guidelines below:

​

Required Fields

• Your endpoint must accept POST requests with:
  • reference
  • status
  • amount
  • timestamp
  • transaction_id

​

Valid Endpoint Format

• Must be publicly accessible.
• Should respond with HTTP status 200 to confirm receipt.

​

Expected responses

• The expected status codes and statuses sent within the callback body can be found here

​

Callback Testing Tips

• Use tools like Webhook.site or Postman’s Mock Server for initial testing.
• Monitor logs to ensure your server handles callback retries properly.
• Simulate various status codes (e.g., failed, success, pending) for robust testing.

See detailed callback response schema

​

Transaction Status API Usage

The Transaction Status API lets you query the transaction status besides the callback notifications.

​

When to Use It

• To verify transaction status post-callback
• To check pending or delayed payments

​

Best Practices

• Avoid frequent polling — respect API rate limits.
• Cache results where possible to reduce unnecessary requests.
• Always handle 4xx and 5xx errors gracefully:
  • Retry on 5xx with exponential backoff.
  • Log and escalate 4xx (e.g., 404 for invalid reference).