POST /api/v1/collect
Initiate a mobile money collection from a customer's wallet.
Endpoint
output.txtText
POST https://api.rohopay.com/api/v1/collect
Headers
| Header | Required | Value |
|---|---|---|
Authorization | ✅ | Bearer {api_key} |
Content-Type | ✅ | application/json |
Idempotency-Key | ✅ | UUID v4 (unique per business event) |
Request Body
response.jsonJSON
{
"phone": "256700123456",
"amount": 50000,
"currency": "UGX",
"description": "Order #1001",
"callback_url": "https://your-app.com/webhooks/rohopay",
"payment_method": "mobile_money"
}
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | ✅ | International format phone (256XXXXXXXXX) |
amount | integer | ✅ | Amount in smallest currency unit |
currency | string | ✅ | UGX, KES, TZS, or RWF |
description | string | — | Payment description (max 255 chars) |
callback_url | string | — | HTTPS webhook endpoint |
payment_method | string | — | Always "mobile_money" |
Response (200 OK)
response.jsonJSON
{
"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": 500,
"commission_rate": 0.01,
"provider_fee_amount": 0,
"net_amount": 49500,
"description": "Order #1001",
"environment": "live",
"created_at": "2024-07-15T08:30:00Z",
"updated_at": "2024-07-15T08:30:00Z"
},
"message": "Payment initiated"
}
Error Responses
| HTTP | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid phone, amount, or currency |
| 400 | MISSING_IDEMPOTENCY_KEY | Idempotency-Key header missing |
| 401 | UNAUTHORIZED | Invalid or missing API key |
| 422 | PROVIDER_ERROR | Provider rejected the request |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests (100/min) |
| 503 | PROVIDER_LINE_DOWN | Provider network unavailable |
Rate Limit
100 requests per minute per IP.