API Reference

Welcome to the Maraboo API Reference. This section provides detailed technical specifications for all API endpoints.

Base URLs

Environment	Base URL
Sandbox	https://sandbox.mara.boo
Production	https://gateway.mara.boo

Authentication

All API requests require HMAC-SHA256 authentication. See the Authentication Guide for details.

Required Headers:

Authorization: HMAC-SHA256 PUBLIC_KEY:PRIVATE_KEY
X-Origin: third-party-api
X-Timestamp: 2025-10-12T14:30:00.000Z
Content-Type: application/json

Resources

Wallets

• List Wallets - GET /api-access/purses/wallets
• Get Wallet - GET /clients/api/business/wallets/{wallet_id}

Transactions

• List Transactions - GET /clients/transactions/sessions

Payments

• Create Payment Session - POST /api-access/transactions/client/sessions/payment

Response Format

All API responses follow a consistent structure:

{
  "data": { /* Response data */ },
  "success": true,
  "message": "Success message",
  "detail": {}
}

Error Responses

All error responses follow a consistent structure:

{
  "success": false,
  "message": "Error description",
  "mb_error_code": "ERROR_CODE",
  "errors": {}
}

Common Error Examples

404 - Route Not Found:

{
  "success": false,
  "message": "Path not found",
  "mb_error_code": "path_not_found",
  "errors": {}
}

404 - Resource Not Found:

{
  "success": false,
  "message": "Could not find recipient",
  "mb_error_code": "RECIPIENT_NOT_FOUND",
  "errors": {}
}

Note: The message and error code vary based on the resource type.

401 - Unauthorized:

{
  "success": false,
  "message": "Authentication required",
  "mb_error_code": "permission_error",
  "errors": {}
}

403 - Forbidden:

{
  "success": false,
  "message": "Access denied to users:read. Insufficient permissions.",
  "mb_error_code": "permission_error",
  "errors": {}
}

Note: The message varies based on the specific permission requirement.

Common HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Resource or path doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

Some endpoints have rate limits to prevent abuse. Rate-limited endpoints include:

• OTP endpoints (send, resend, validate)
• Additional endpoints may be added over time

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "mb_error_code": "rate_limit_exceeded",
  "errors": {}
}

Note: Specific rate limit thresholds and time windows vary by endpoint. Contact support for detailed rate limit information.