API Documentation

Introduction

The Paisha API base URL is:

https://api.paisha.africa/whatsapp

Create an account, activate a plan, connect your WhatsApp number, and generate an API key from your dashboard. Every request returns JSON.

Authentication

Send your API key in the X-API-Key header on every request. Keep it secret — treat it like a password.

X-API-Key: pa_live_xxxxxxxxxxxxxxxxxxxx

Requests without a valid key return 401. Without an active subscription you'll get 402. Suspended accounts get 403.

Connect a number

Start a session and get a QR code to scan from WhatsApp → Linked devices. You can also do this visually in the dashboard.

curl -X POST https://api.paisha.africa/whatsapp/session/connect \
  -H "X-API-Key: $PAISHA_KEY"

Connection status

curl https://api.paisha.africa/whatsapp/session/status \
  -H "X-API-Key: $PAISHA_KEY"

# { "session": "...", "status": "connected", "phone_number": "2557..." }

Send a text message

curl -X POST https://api.paisha.africa/whatsapp/messages/send-text \
  -H "X-API-Key: $PAISHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "255700000000@c.us", "text": "Hello from Paisha 👋" }'

# 200 OK
# { "id": "wamid.HBgL...", "status": "sent" }

Address recipients as <number>@c.us for people and <id>@g.us for groups — international number, no + or 00.

Send media

Images, documents and other types follow the same pattern — just change the endpoint.

curl -X POST https://api.paisha.africa/whatsapp/messages/send-image \
  -H "X-API-Key: $PAISHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "255700000000@c.us", "url": "https://example.com/receipt.jpg", "caption": "Your receipt" }'

Receive messages (webhooks)

Set a webhook URL in your dashboard to receive incoming messages in real time. Paisha will POST a JSON event to your URL whenever your number receives a message.

POST https://your-app.com/webhook
{
  "event": "message",
  "data": { "from": "255700000000", "type": "text", "body": "Hi!" }
}

Usage

Check how many messages you've sent and received.

curl https://api.paisha.africa/whatsapp/usage \
  -H "X-API-Key: $PAISHA_KEY"

# { "sent": 1280, "received": 642 }

Errors