Endpoint
POST https://api.rohopay.com/api/v1/checkout
Content-Type: application/json
Unlike other v1 endpoints, checkout authenticates via api_key in the request body (not the Authorization header). This allows secure checkout from a browser without exposing the key in headers.
Request Body
{
"api_key": "live_YOUR_KEY",
"amount": 75000,
"currency": "UGX",
"customer_name": "Jane Mukasa",
"customer_email": "jane@example.com",
"description": "Premium subscription",
"return_url": "https://your-app.com/checkout/return",
"card_number": "4111111111111111",
"card_expiry": "10/26",
"card_cvv": "123"
}
| Field | Type | Required | Description |
|---|
api_key | string | ✅ | Your RohoPay API key |
amount | integer | ✅ | Amount in smallest unit (e.g., 75000 for UGX 75,000) |
currency | string | ✅ | UGX, KES, TZS, or RWF |
customer_name | string | ✅ | Cardholder full name |
customer_email | string | ✅ | Cardholder email |
description | string | — | Payment description |
return_url | string | ✅ | URL to redirect after 3DS completes |
card_number | string | ✅ | 16-digit card number (no spaces) |
card_expiry | string | ✅ | Expiry in MM/YY format |
card_cvv | string | ✅ | 3-digit CVV |
Response (200 OK)
{
"success": true,
"data": {
"transaction_id": "01j5m6n7p8q9r0s1t2u3vwxy",
"internal_reference": "RHP-2024-CARD001",
"payment_url": "https://payments.rohopay.com/3ds/abc123xyz",
"status": "pending",
"amount": 75000,
"currency": "UGX"
}
}
payment_url. This is a one-time 3DS session link.
Return URL Parameters
After 3DS completes, the provider redirects to your return_url with:
?status=success&reference=RHP-2024-CARD001&order_ref=relworx-ref
Do not trust ?status=success alone. Always verify via polling or webhook before fulfilling the order.
Rate Limit
30 requests per minute per IP.
Error Responses
| HTTP | Code | Description |
|---|
| 400 | VALIDATION_ERROR | Invalid card number, expiry, CVV, or email |
| 400 | CARD_EXPIRED | Card expiry date is in the past |
| 401 | UNAUTHORIZED | Invalid api_key in body |
| 429 | RATE_LIMIT_EXCEEDED | 30 req/min exceeded |
| 503 | PROVIDER_LINE_DOWN | Payment provider unavailable |
