​
Endpoint

POST https://api.rohopay.com/api/v1/collect
Authorization: Bearer {api_key}
Idempotency-Key: {uuid_v4}
Content-Type: application/json

​
Request Fields

​
phone
string
required
Payer’s phone in international format without +. Uganda: 256700123456, Kenya: 254712345678.
​
amount
integer
required
Amount in smallest currency unit. 10000 = UGX 10,000.
​
currency
string
required
UGX, KES, TZS, or RWF.
​
description
string
Payment description shown in your dashboard. Max 255 characters.
​
callback_url
string
HTTPS URL where RohoPay sends a webhook when status resolves. Recommended for production.

​
Request Examples

curl -X POST https://api.rohopay.com/api/v1/collect \
  -H "Authorization: Bearer live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "phone": "256700123456",
    "amount": 50000,
    "currency": "UGX",
    "description": "Order #1001",
    "callback_url": "https://your-site.com/webhook/rohopay"
  }'

​
Response

{
  "success": true,
  "data": {
    "id": "01j2k3m4n5p6q7r8s9t0uvwx",
    "internal_reference": "RHP-2024-ABC123",
    "provider_reference": "9876543210",
    "status": "pending",
    "type": "collection",
    "payment_method": "mobile_money",
    "phone_number": "256700123456",
    "amount": 50000,
    "currency": "UGX",
    "commission_amount": 500,
    "commission_rate": 0.01,
    "net_amount": 49500,
    "environment": "live",
    "created_at": "2024-07-15T08:30:00Z"
  }
}
The default commission rate is 1%. Your net credit is amount - commission_amount. You can view your current rate in Dashboard → Settings.

​
After the Request

The initial status is always pending. The user receives a USSD prompt on their phone. When they approve (or reject), RohoPay:
  1. Updates the transaction status to successful or failed
  2. POSTs a deposit.successful or similar event to your callback_url
Use the Webhooks guide to handle this event, or poll the status if you prefer.

​
Test Mode

With a test_ key, use 256700000000 as the phone number — the payment completes immediately without a real USSD push.