​
Endpoint

POST https://api.rohopay.com/api/v1/collect

​
Headers

HeaderRequiredValue
Authorization✅Bearer {api_key}
Content-Type✅application/json
Idempotency-Key✅UUID v4 (unique per business event)

​
Request Body

{
  "phone": "256700123456",
  "amount": 50000,
  "currency": "UGX",
  "description": "Order #1001",
  "callback_url": "https://your-app.com/webhooks/rohopay",
  "payment_method": "mobile_money"
}
FieldTypeRequiredDescription
phonestring✅International format phone (256XXXXXXXXX)
amountinteger✅Amount in smallest currency unit
currencystring✅UGX, KES, TZS, or RWF
descriptionstring—Payment description (max 255 chars)
callback_urlstring—HTTPS webhook endpoint
payment_methodstring—Always "mobile_money"

​
Response (200 OK)

{
  "success": true,
  "data": {
    "id": "01j2k3m4n5p6q7r8s9t0uvwx",
    "internal_reference": "RHP-2024-ABC123",
    "provider_reference": "9876543210",
    "status": "pending",
    "type": "collection",
    "payment_method": "mobile_money",
    "provider": "relworx",
    "phone_number": "256700123456",
    "amount": 50000,
    "currency": "UGX",
    "commission_amount": 1000,
    "commission_rate": 0.02,
    "provider_fee_amount": 0,
    "net_amount": 49000,
    "description": "Order #1001",
    "environment": "live",
    "created_at": "2024-07-15T08:30:00Z",
    "updated_at": "2024-07-15T08:30:00Z"
  },
  "message": "Payment initiated"
}

​
Error Responses

HTTPCodeDescription
400VALIDATION_ERRORInvalid phone, amount, or currency
400MISSING_IDEMPOTENCY_KEYIdempotency-Key header missing
401UNAUTHORIZEDInvalid or missing API key
422PROVIDER_ERRORProvider rejected the request
429RATE_LIMIT_EXCEEDEDToo many requests (100/min)
503PROVIDER_LINE_DOWNProvider network unavailable

​
Rate Limit

100 requests per minute per IP.