Business API

External Partner Documentation

Overview

This describes the Wakapay Business API for external partners. Using this API you can authenticate, manage wallet balances, obtain FX rates, verify recipients, initiate payouts, and query transactions — all over secure HTTPS.

All requests and responses use JSON. Code examples use curl for clarity.

Environments & Base URLs

Wakapay provides separate Test and Production environments.

Test Environment

• Base URL: https://api.test.wakapay.io
• Purpose: Development and testing without processing real transactions
• Test Credentials: Provided when you create a developer account
• No real money processed

Production Environment

• Base URL: https://api.wakapay.io
• Purpose: Live transactions with real money
• Requires: KYB verification
• All transactions are final

TESTENV Test Credentials

Use these credentials for testing in the test environment:

Test Phone Numbers (Mobile Money)

Test Lipa Numbers (Till/Paybill)

Test Account Balance

Test account balances vary by account. New accounts may start with zero balance. You can request a balance top-up from the admin team if needed for testing.

Check your current balance using the Balance API.

Configured FX Rates

• USD → KES: 129 (configured and working)

Note: Non-test phone numbers in TESTENV will return verified: false or account not active errors.

Authentication

All API requests require authentication using Bearer tokens. Learn more in our Authentication guide.

curl https://api.test.wakapay.io/business/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Request & Response Format

Content Type

All requests should include the Content-Type: application/json header.

Response Format

All responses are returned in JSON format with a consistent structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful"
}

Error Responses

Errors follow a standard format:

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be greater than 0"
  }
}

Rate Limiting

API requests are rate limited to ensure system stability:

• Production: 100 requests per minute per API key
• Testing: 60 requests per minute per API key

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Environments

Test Environment URLs

Use the test environment to develop and test your integration without processing real transactions.

• URL: https://api.test.wakapay.io
• Test credentials are provided when you create a developer account
• No real money is processed

Production Environment URLs

The production environment processes real transactions.

• URL: https://api.wakapay.io
• Requires KYB verification
• All transactions are final

Next Steps

Ready to start building? Continue to our Quick Start guide to make your first API call in minutes.