Wallet topups
Request Wallet Top-up
Create a new top-up request for the authenticated storefront account.
Endpoint
POST /api/v1/top-ups/request
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
amount | number | Yes | Must be greater than 0 and at least 10 |
paymentMethod | "MomoPay" or "Momo" | Yes | Requested payment channel |
Business rules
- only
AgentandSuperAgentprofiles can request wallet top-ups - a second processing top-up request is blocked until the existing one resolves
- requests are inserted as
Top-Uptransactions withchannel: "API"
Response
Returns the top-up transaction record when created:
{
"success": true,
"data": {
"_id": "v123...",
"_creationTime": 1234567890123,
"userProfileId": "usr456",
"amount": 150,
"channel": "MomoPay",
"status": "Pending",
"reference": "TU20240331123456"
}
}Response fields
| Field | Type | Notes |
|---|---|---|
_id | txns id | Transaction record ID |
_creationTime | number | Creation timestamp (unix ms) |
userProfileId | userProfiles id | Request owner |
amount | number | GHS amount requested |
channel | string | Payment method (MomoPay or Momo) |
status | string | Pending initially, transitions to Approved or Rejected |
reference | string | Transaction reference code |
Errors
403- Insufficient permissions (not Agent/SuperAgent)400- Invalid amount (must be >= 10)429- Another top-up request already in progress