SenjaroPay Documentation | SenjaroPay Docs

SenjaroPay is a payment API built for African markets. Use it to collect money via mobile money, accept card checkout, pay bills and utilities, and send bank payouts — all through straightforward REST endpoints.

Base URL

https://api.senjaropay.com

All request URLs in this documentation are relative to that host unless stated otherwise. Merchant API operations use POST with a JSON body.

Authentication

Every merchant request must include both credentials:

x-api-key: YOUR_API_KEY_HERE
x-api-secret: YOUR_API_SECRET_HERE

Treat your API key like a password. Store it in server-side secrets (environment variables, a vault, or your host’s secret manager) and never expose it in client-side code or public repositories.

All payloads and responses shown in this documentation are mock examples for integration guidance only.

Sub-merchant ID

submerchant_id is optional on mobile money and card payments. Send it when the payment belongs to a sub-merchant. Send "" when it does not.

Sign in to the SenjaroPay dashboard.
Open Shortcuts → Sub Merchants.
Copy the Submerchant ID for that business. Use the copy control in the Submerchant ID column.
Pass that value as submerchant_id on POST /senjaropay/merchant/payments/create and POST /senjaropay/merchant/card/pay.

If the list is empty, choose New sub-merchant, then copy the ID after it appears.

Quick start

Authentication — Learn how to authenticate requests using API key and API secret.
Mobile money — USSD push to authorize.
Card payments — Hosted card checkout. Confirm with a webhook, or read status if the webhook does not arrive.
Bill payments — Browse billers, look up accounts, pay utilities, and check status.
Payouts — Look up a bank account, then send a TZS bank payout.
Payment status — Retrieve the status of a mobile payment over POST after it is created.
Webhooks — Receive real-time notifications when payments update or complete.

Payment types

Mobile money

Type: mobile money / MNO collection

The customer completes payment on their operator’s network (for example via USSD prompt or wallet flow, depending on channel configuration).

Supported networks (mobile collection): Vodacom (M-Pesa), Airtel Money, Tigo Pesa / Mixx by Yas, Halotel.

Typical use: airtime-style collections, bill pay, e-commerce with local wallets.

Card

Type: hosted card checkout

Configure Success, Fail, and Cancel URLs in the merchant portal. Call POST /senjaropay/merchant/card/pay, open checkout_url, then poll POST /senjaropay/merchant/card/status until the result is final. SenjaroPay also redirects the browser to the matching portal URL after checkout.

Send a new UUID in x-idempotency-key on each card payment. The status call does not use that header. See Card payments.

Bill payments

Type: utilities, government bills, TV, and other billers

Browse categories, look up the customer account when required, then pay from your merchant wallet. Confirm unsettled results with POST /api/billPayments/status. See Bill payments.

Payouts

Type: bank cashout / disbursement

Look up the beneficiary account name, then transfer from your merchant wallet. Bank payouts currently support TZS — always send currency. USD and mobile money payouts will follow. See Payouts.

Integration flow

Get API keys

Create a SenjaroPay account and generate API keys from the dashboard. Copy the key into your server environment as YOUR_API_KEY_HERE (or similar).

Create a payment

Call POST https://api.senjaropay.com/senjaropay/merchant/payments/create with mobile money fields (payment_type, details, phone_number, customer). Include x-api-key, x-api-secret, and a unique x-idempotency-key.

Handle the response

The customer authorizes the collection on their mobile money wallet (for example USSD or in-app confirmation, depending on the operator). Track the outcome via payment status or webhooks.

Confirm completion

Verify success using your chosen mechanism (callback, webhook, or status API) before fulfilling the order or service.

Idempotency

For create/charge requests (for example POST https://api.senjaropay.com/senjaropay/merchant/payments/create), send a unique idempotency key so retries do not create duplicate charges:

POST https://api.senjaropay.com/senjaropay/merchant/payments/create
Content-Type: application/json
x-api-key: YOUR_API_KEY_HERE
x-api-secret: YOUR_API_SECRET_HERE
x-idempotency-key: unique-key-123

If you repeat the same request with the same x-idempotency-key, you should receive the same outcome as the first successful attempt (exact behavior is defined by the API implementation).

Rate limits

API traffic may be rate-limited. When limits apply, responses can include headers such as:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests left before the window resets
`X-RateLimit-Reset`	When the current window resets (often as a timestamp or seconds)

If you receive 429 Too Many Requests, slow down and retry with exponential backoff (increase delay between attempts).

Response format

Successful responses typically wrap payloads in a consistent envelope, for example:

Success

{
  "status": "success",
  "code": 200,
  "data": {
  }
}

Errors return a machine-readable code and a message you can log or show in support tooling:

Error

{
  "status": "error",
  "code": 400,
  "error_code": "validation_error",
  "message": "Description of the error"
}

Exact field names may match your live API; confirm payloads and status codes against your integration environment and the endpoint definitions in this documentation.