SonicPesa API Documentation

Base URL

https://api.sonicpesa.com/api/v1

Authentication

All API requests require authentication using your API key in the X-API-KEY header.

X-API-KEY: YOUR_API_KEY

ℹ️

Get your API key from the API Settings page after logging in.

Create Order

Create a new payment order using Push USSD Direct. This will create an order and send a Push USSD request to the customer's phone.

Endpoint

POST https://api.sonicpesa.com/api/v1/payment/create_order

Request Body

{
  "buyer_email": "customer@example.com",
  "buyer_name": "John Doe",
  "buyer_phone": "255682812345",
  "amount": 10000,
  "currency": "TZS"
}

Response

{
  "status": "success",
  "message": "Payment order created successfully! Push USSD sent to your phone.",
  "data": {
    "order_id": "sp_696a7e8c101e3",
    "reference": "S20376448003",
    "amount": 200,
    "currency": "TZS",
    "payment_status": "PENDING",
    "status": "PENDING",
    "creation_date": "2026-01-16 21:09:49",
    "transid": null,
    "channel": null,
    "msisdn": "255699183634",
    "order_status_data": {
      "order_id": "sp_696a7e8c101e3",
      "creation_date": "2026-01-16 21:09:49",
      "amount": "200",
      "payment_status": "PENDING",
      "transid": null,
      "channel": null,
      "reference": null,
      "msisdn": null
    }
  }
}

⚠️

The API will automatically send a Push USSD request to the customer's phone. The customer needs to approve the payment on their phone to complete the transaction.

Create Order (Simplified)

A simplified version of the Create Order endpoint. This endpoint waits for up to 45 seconds for payment confirmation and returns the final status immediately if completed. Ideal for simple "fire-and-forget" integrations.

Endpoint

POST https://api.sonicpesa.com/api/v1/payment/create_order_simple

Request Body

{
  "buyer_email": "customer@example.com",
  "buyer_name": "John Doe",
  "buyer_phone": "255682812345",
  "amount": 10000,
  "currency": "TZS"
}

Response (Success)

{
  "status": "success",
  "message": "Order processed",
  "data": {
    "order_id": "sp_678912345abcdef",
    "status": "SUCCESS",
    "amount": 10000,
    "payment_details": { ... }
  }
}

Response (Pending/Timeout)

{
  "status": "success",
  "message": "Order processed",
  "data": {
    "order_id": "sp_678912345abcdef",
    "status": "PENDING",
    "amount": 10000,
    "payment_details": {
      "order_id": "sp_696eb23838068",
      "creation_date": "2026-01-20 01:39:21",
      "amount": "200",
      "payment_status": "PENDING",
      "transid": null,
      "channel": null,
      "reference": null,
      "msisdn": null
    }
  }
}

ℹ️

This endpoint performs long-polling (waits) for up to 45 seconds. Set your HTTP client timeout to at least 60 seconds.

Check Order Status

Check the current status of a payment order. Use this to poll for payment status updates.

Endpoint

POST https://api.sonicpesa.com/api/v1/payment/order_status

Request Body

{
  "order_id": "sp_67890abcdef"
}

Response

{
  "status": "success",
  "message": "Order status retrieved successfully!",
  "data": {
    "order_id": "sp_696a7e8c101e3",
    "creation_date": "2026-01-16 21:09:49",
    "amount": "200",
    "payment_status": "COMPLETED",
    "transid": "807399829307",
    "channel": "AIRTELMONEY",
    "reference": "1540671137",
    "msisdn": "255699183634"
  },
  "transaction": {
    "order_id": "sp_696a7e8c101e3",
    "status": "SUCCESS",
    "amount": "200",
    "buyer_email": "customer@example.com",
    "buyer_name": "Juma Ali"
  }
}

Payment Status Values

PENDING

Payment is pending customer approval

COMPLETED

Payment completed successfully

CANCELLED

Payment was cancelled

USERCANCELLED

User cancelled the payment

REJECTED

Payment was rejected

INPROGRESS

Payment is in progress

List Transactions

Retrieve a list of all transactions for the authenticated user.

Endpoint

POST https://api.sonicpesa.com/api/v1/transactions/readbyId

Request Body

{
  "page": 1
}

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "order_id": "sp_67890abcdef",
      "amount": "10000",
      "currency": "TZS",
      "status": "SUCCESS",
      "phone": "255682812345",
      "reference": "0289999288",
      "transid": "TXN123456",
      "channel": "AIRTELMONEY",
      "msisdn": "255682812345",
      "created_at": "2025-01-07T12:00:00.000000Z",
      "updated_at": "2025-01-07T12:05:00.000000Z"
    }
  ]
}

Webhooks

Configure webhooks to receive real-time notifications about payment events. Set your webhook URL in the API Settings page.

Webhook URL

POST https://your-domain.com/webhook

Set this URL in your API settings. We will send POST requests to this URL when payment events occur.

Webhook Payload

{
  "event": "payment.completed",
  "order_id": "sp_67890abcdef",
  "amount": 10000,
  "currency": "TZS",
  "status": "SUCCESS",
  "transid": "TXN123456",
  "channel": "AIRTELMONEY",
  "reference": "0289999288",
  "msisdn": "255682812345",
  "timestamp": "2025-01-07T12:05:00Z"
}

Webhook Events

payment.completed

Payment completed successfully

payment.failed

Payment failed

payment.cancelled

Payment was cancelled

payment.pending

Payment is pending

⚠️

Your webhook endpoint must return a 200 status code within 5 seconds. We will retry failed webhooks up to 3 times with exponential backoff.

Webhook Signature Verification

For security, verify webhook signatures using your API secret key:

// Example verification (PHP)
$signature = hash_hmac('sha256', $payload, $apiSecret);
if ($signature === $headers['X-SonicPesa-Signature']) {
    // Webhook is authentic
}

Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`500`	Internal Server Error

Need Help?

If you have any questions or need assistance with the API, please contact our support team.

📱

WhatsApp

+255 627 360 144

📧

Email

support@sonicpesa.com