broRacks API Reference

Integrate mobile money payments into your application in minutes. Collect payments, send disbursements, and track transactions with our developer-friendly REST API.

Base URL

https://api.broracks.online

Getting Started

The broRacks API uses REST over HTTPS. All request and response bodies are JSON-encoded. Authentication uses a token exchange flow — exchange your API keys for a short-lived session token via POST /v1/auth/token.

💡

Quick start: Log in to the dashboard → go to Credentials → generate a test API key → use it in the Authorization header as Bearer <session_token>.

⚠️

Never expose your secret key in client-side code, Git repos, or public files. Use it only from your server. If compromised, immediately revoke it from the dashboard.

Authentication

API authentication uses a two-step token exchange. First, exchange your public_key and secret_key for a short-lived session token via POST /v1/auth/token. Then use that token as a Bearer token in the Authorization header for all API requests.

POST/v1/auth/tokenExchange API keys for a session token

Request Body

Parameter	Type	Required	Description
public_key	string	required	Your public key (`pk_test_` or `pk_live_`)
secret_key	string	required	Your secret key (`sk_test_` or `sk_live_`)

# Step 1: Exchange your API keys for a session token
curl -X POST https://api.broracks.online/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "pk_test_your_public_key",
    "secret_key": "sk_test_your_secret_key"
  }'
# Response: { "data": { "token": "eyJhbG..." } }

# Step 2: Use the session token for API requests
curl -X GET https://api.broracks.online/v1/merchant/me \
  -H "Authorization: Bearer eyJhbG..."

🔑

Where to get your API keys: Log in to the merchant dashboard → go to Credentials → generate a test or live API key. Both the public key (pk_*) and secret key (sk_*) are shown only once — store them securely.

⚠️

Raw keys are no longer accepted. Passing sk_* directly as a Bearer token will return AUTH_METHOD_CHANGED. You must exchange your keys for a session token via POST /v1/auth/token first.

Collections

Collect money from a customer's mobile money account. The customer receives a push prompt on their phone to confirm the payment. Use the Idempotency-Key header to prevent duplicate charges.

POST/v1/collections/initiateInitiate a mobile money collection

Request Body

Parameter	Type	Required	Description
payer_name	string	required	Name of the person paying
phone_number	string	required	E.164 format (e.g. `+256771234567`)
amount	integer	required	Amount in UGX (500–7,000,000)
description	string	optional	Payment description / reason

Headers

Header	Required	Description
Authorization	required	`Bearer sk_test_xxxxx` or `Bearer sk_live_xxxxx`
Idempotency-Key	recommended	Unique key to prevent duplicate charges

curl -X POST https://api.broracks.online/v1/collections/initiate \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-001" \
  -d '{
    "payer_name": "John Doe",
    "phone_number": "+256771234567",
    "amount": 5000,
    "description": "Payment for Order #1234"
  }'

Response (202 Accepted)

{
  "status": "success",
  "data": {
    "reference": "BRR-a1b2c3d4-...",
    "broracks_ref": "BRR-xxxxxxxx",
    "amount": 5000,
    "fee": 400,
    "net_amount": 4600,
    "status": "PENDING",
    "phone_number": "+256771234567",
    "environment": "test",
    "created_at": "2026-02-23T10:00:00"
  },
  "message": "Collection initiated. Customer must approve on their phone."
}

Disbursements

Withdraw money from your wallet directly to your registered mobile money number. Funds are sent immediately after validation. A gateway fee is charged per withdrawal based on the amount tier.

📌

Disbursements always go to the merchant's registered phone number. You cannot specify a custom destination for security reasons.

POST/v1/disbursements/initiateRequest a withdrawal

Request Body

Parameter	Type	Required	Description
amount	integer	required	Amount in UGX (500–7,000,000)
description	string	required	Reason for the withdrawal

curl -X POST https://api.broracks.online/v1/disbursements/initiate \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: withdrawal-001" \
  -d '{
    "amount": 10000,
    "description": "Salary payment"
  }'

Response (202 Accepted)

{
  "status": "success",
  "data": {
    "reference": "BRR-d4e5f6g7-...",
    "broracks_ref": "BRR-yyyyyyyy",
    "amount": 11200,
    "destination_phone": "256771234567",
    "status": "PENDING",
    "environment": "test",
    "created_at": "2026-02-23T10:00:00"
  },
  "message": "Withdrawal initiated. Funds will be sent to your registered phone."
}

Transactions

Retrieve your transaction history with powerful filters. Supports pagination, type filtering (COLLECTION / DISBURSEMENT), status filtering, and date ranges.

GET/v1/transactionsList all transactions (paginated)

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	50	Results per page (max 100)
type	string	—	`COLLECTION` or `DISBURSEMENT`
status	string	—	`PENDING`, `SUCCEEDED`, `FAILED`, etc.
from_date	string	—	ISO date (e.g. `2026-01-01`)
to_date	string	—	ISO date (e.g. `2026-12-31`)

# List transactions (with filters)
curl -X GET "https://api.broracks.online/v1/transactions?type=COLLECTION&status=SUCCEEDED&page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

# Get single transaction by reference
curl -X GET "https://api.broracks.online/v1/transactions/BRR-abc123" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

GET/v1/transactions/{reference}Get a single transaction by reference

Phone Verification

Verify a mobile money phone number before initiating a transaction. Returns the registered name on the account, helping you confirm the recipient's identity and reduce failed payments.

POST/v1/verify/phoneLook up the registered name for a phone number

Request Body

Parameter	Type	Required	Description
phone_number	string	required	MTN/Airtel Uganda number (e.g. `+256771234567` or `256771234567`)

💡

Sandbox mode: In the test environment, this endpoint always returns "Test User" as the registered name.

curl -X POST https://api.broracks.online/v1/verify/phone \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+256771234567"
  }'

# Response:
# {
#   "status": "success",
#   "data": {
#     "phone_number": "+256771234567",
#     "registered_name": "JOHN DOE"
#   }
# }

✅

Use case: Call this endpoint before initiating a collection to auto-populate the payer_name field, or to let your users confirm they're paying the right person.

Webhooks

Get real-time notifications when transaction statuses change. Configure your webhook URL and we'll POST events to it with HMAC-signed payloads.

POST/v1/webhooks/configureSet up your webhook endpoint

Request Body

Parameter	Type	Required	Description
url	string	required	HTTPS URL to receive webhook events
events	string[]	optional	Events to subscribe to (defaults to all)

🔐

Available events: collection.success, collection.failed, disbursement.success, disbursement.failed

curl -X POST https://api.broracks.online/v1/webhooks/configure \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/broracks",
    "events": [
      "collection.success",
      "collection.failed",
      "disbursement.success",
      "disbursement.failed"
    ]
  }'

Signature Verification

Every webhook payload is signed with your webhook secret using HMAC-SHA256. Always verify the signature to ensure the request came from broRacks and hasn't been tampered with.

Webhook Headers

Header	Description
X-BroRacks-Timestamp	Unix timestamp when the webhook was sent
X-BroRacks-Signature	HMAC-SHA256 signature: `sha256=hex_digest`

⏱️

Replay prevention: Reject any webhook with a timestamp older than 5 minutes. This prevents replay attacks.

# Webhook payloads are sent with these headers:
# X-BroRacks-Timestamp: 1700000000
# X-BroRacks-Signature: sha256=abcdef...
#
# Verify by computing:
# HMAC-SHA256(secret, timestamp + "." + raw_body)

Error Handling

All errors follow a consistent JSON format. Check the error.code field for programmatic handling.

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet only has 5,000 UGX but you need 11,200 UGX."
  }
}

HTTP	Error Code	Meaning
400	`INSUFFICIENT_BALANCE`	Not enough funds in wallet
401	`INVALID_CREDENTIALS`	Wrong email/password or invalid API key
401	`TOKEN_EXPIRED`	JWT access token has expired
403	`MERCHANT_SUSPENDED`	Merchant account is suspended
422	`INVALID_AMOUNT`	Amount outside 500–7,000,000 UGX range
422	`INVALID_PHONE`	Phone number is not in E.164 format
429	`RATE_LIMIT_EXCEEDED`	Too many requests — slow down
502	`GATEWAY_ERROR`	Upstream provider error
504	`GATEWAY_TIMEOUT`	Upstream provider took too long

Rate Limits

API endpoints are rate-limited to protect against abuse and ensure fair usage.

Endpoint	Limit
`POST /v1/auth/login`	5 requests / minute
`POST /v1/collections/initiate`	30 requests / minute
`POST /v1/disbursements/initiate`	30 requests / minute
`POST /v1/auth/refresh`	10 requests / minute

💡

When rate-limited, you'll receive a 429 Too Many Requests response. Wait before retrying — use exponential backoff for best results.

Environments

broRacks supports two environments. Your API key determines which environment is used.

Environment	Key Prefix	Description
Test (Sandbox)	`sk_test_`	No real money moves. Use admin simulate-callback to test flows.
Live	`sk_live_`	Real mobile money transactions. Requires domain whitelisting.

🔒

Live keys require domain whitelisting. When creating a live API key, you must specify the allowed domains that can use it. Server-to-server calls (no Origin header) are always allowed.