Getting Started

Build with WasaaPay API

Welcome to the WasaaPay Partner API documentation. Get started in minutes with our comprehensive guides and API reference.

5 min setup

Quick integration

Secure by default

Enterprise-grade

99.99% uptime

Reliable APIs

What you can build

The WasaaPay Partner API gives you everything you need to build payment experiences:

Create and manage users with digital wallets
Process instant P2P transfers between wallets
Accept deposits via M-Pesa STK Push
Send payouts to M-Pesa via B2C
Pay bills and utilities on behalf of users
Receive real-time webhooks for all events

Base URL

All API requests should be made to one of these endpoints:

# Production
https://api.wasaapay.com/api/v1/partner

# Sandbox (for testing)
https://sandbox.wasaapay.com/api/v1/partner

Quick Start

Get your API key

Create a free account and get your sandbox API key from the API Keys dashboard. You'll get separate keys for sandbox and production.

API Key:sk_sandbox_xxxxxxxxxxxx

Make your first API call

Let's create a user. All POST requests require an X-Idempotency-Key header to ensure safe retries.

create-user.js

// Make your first API call
const response = await fetch('https://api.wasaapay.com/api/v1/partner/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sk_sandbox_your_api_key',
    'X-Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    externalUserId: 'user_001',
    phoneNumber: '+254712345678',
    firstName: 'John',
    lastName: 'Doe',
  }),
});

const { data } = await response.json();
console.log('User created:', data.id);

Or with cURL:

Terminal

curl -X POST https://api.wasaapay.com/api/v1/partner/users \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_sandbox_your_api_key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "externalUserId": "user_001",
    "phoneNumber": "+254712345678",
    "firstName": "John",
    "lastName": "Doe"
  }'

Handle the response

A successful response includes the created resource:

Response (200 OK)

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": "pu_abc123xyz",
    "externalUserId": "user_001",
    "phoneNumber": "+254712345678",
    "firstName": "John",
    "lastName": "Doe",
    "environment": "SANDBOX",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "requestId": "req_xyz789"
}

Environments

WasaaPay provides two environments for development and production:

Environment	Purpose	API Key Prefix
Sandbox	Testing and development	`sk_sandbox_`
Production	Live transactions with real money	`sk_live_`

Testing in Sandbox

The sandbox environment simulates real payment behavior. Use these test patterns:

SuccessAny amount not ending in 01
FailedAmounts ending in 01 (e.g., 10001, 5001)
PendingAmounts ending in 02 (e.g., 10002, 5002)

Next Steps

Authentication

Learn about API keys, headers, and security best practices.

Users

Create and manage users in your partner account.

Wallets

Set up digital wallets and manage balances.

Transfers

Move money between wallets instantly.