omega-api-documentation.md

Omega Airtime API Documentation

Overview

This documentation covers the external API endpoints for airtime selling flows in the Cronos system. These APIs are designed for external clients to integrate airtime recharge functionality.

Base URL

http://api.omega.sendai.co.zw

Authentication

The API uses PIN-based authentication with JWT tokens. All airtime operations require authentication.

Authentication Flow

1. Create an account (if not already registered)
2. Authenticate using PIN to get JWT token
3. Include JWT token in Authorization header for subsequent requests
4. Token format: Bearer <jwt_token>

Endpoints

1. Create Account

Create a new account in the system. This is typically the first step before authentication.

Endpoint: POST /api/v1/onboarding/accounts

Request Body:

{
  "name": "Sean Inc",
  "type": "company",
  "level": "superagent",
  "contact_name": "Sean",
  "contact_email": "[email protected]",
  "contact_phone": "0775265552",
  "address": "63 Glenelg Road Vainona",
  "city": "Harare",
  "user_firstname": "Sean",
  "user_lastname": "Omega",
  "user_email": "[email protected]",
  "user_phone": "0775265552"
}

Request Validation:

• name: Required, account/company name
• type: Required, account type (e.g., "company")
• level: Required, account level (e.g., "superagent")
• contact_name: Required, primary contact person name
• contact_email: Required, valid email format
• contact_phone: Required, contact phone number
• address: Required, physical address
• city: Required, city name
• user_firstname: Required, user's first name
• user_lastname: Required, user's last name
• user_email: Required, user's email (valid email format)
• user_phone: Required, user's phone number

Response (Success - 200):

{
  "status": "success",
  "message": "account created successfully",
  "data": {
    "id": "019886e5-01c3-70ff-87db-bbfbc642a29a",
    "name": "Sean Inc",
    "number": "9444-5339-1364",
    "address": "63 Glenelg Road Vainona",
    "city": "",
    "contact_name": "Sean",
    "contact_email": "[email protected]",
    "contact_phone": "263775265552",
    "account_type": "company",
    "account_level": "superagent"
  }
}

Notes:

• Phone numbers are automatically formatted to international format (e.g., "0775265552" becomes "263775265552")
• A unique account number is automatically generated
• This endpoint does not require authentication

2. PIN Authentication

Authenticate user with phone number and PIN to obtain JWT token.

Endpoint: POST /auth/pin-authentication

Request Body:

{
  "phone": "+263771234567",
  "pin": "1234"
}

Request Validation:

• phone: Required, must be valid phone number format
• pin: Required

Response (Success - 200):

{
  "status": "success",
  "message": "authenticated",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-01T12:00:00Z"
  }
}

Response (Error - 401):

{
  "message": "Invalid credentials"
}

3. PIN Reset

Reset user's PIN (sends new PIN via configured method).

Endpoint: POST /auth/pin-reset

Request Body:

{
  "phone": "+263771234567"
}

Request Validation:

• phone: Required, must be valid phone number format

Response (Success - 200):

{
  "status": "success",
  "message": "pin was rest successfully",
  "data": null
}

Response (Error - 422):

{
  "message": "User not found"
}

4. Get Current User

Get authenticated user information.

Endpoint: GET /auth/user

Headers:

Authorization: Bearer <jwt_token>

Response (Success - 200):

{
  "status": "success",
  "message": "user retrieved",
  "data": {
    "id": "user-id",
    "email": "[email protected]",
    "phone": "+263771234567",
    "account_id": "account-id"
  }
}

5. Single Airtime Recharge

Credit airtime to a phone number.

Endpoint: POST /api/v1/recharges/airtime

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "phone": "+263771234567",
  "amount": 100,
  "currency": "USD",
  "reference": "unique-reference-123"
}

Request Validation:

• phone: Required, must be valid phone number format
• amount: Required, integer amount in cents/smallest currency unit
• currency: Required, currency code (e.g., "USD", "ZWL")
• reference: Required, unique transaction reference

Response (Success - 200):

{
  "status": "success",
  "message": "successful airtime recharge",
  "data": {
    "transaction_id": "txn-12345",
    "reference": "unique-reference-123",
    "phone": "+263771234567"
  }
}

Response (Insufficient Funds - 422):

{
  "status": "error",
  "message": "Insufficient funds",
  "data": null
}

Response (Wallet Not Found - 422):

{
  "status": "error",
  "message": "Wallet not found",
  "data": null
}

Rate Limiting: This endpoint is rate-limited based on server configuration.

6. Batch Airtime Recharge

Process multiple airtime recharges in batch.

Endpoint: POST /api/v1/recharges/airtime/batch

Request Body:

{
  "account": "account-id",
  "recharges": [
    {
      "phone": "+263771234567",
      "amount": 100,
      "currency": "USD",
      "reference": "ref-001"
    },
    {
      "phone": "+263779876543",
      "amount": 200,
      "currency": "USD",
      "reference": "ref-002"
    }
  ]
}

Response (Success - 200):

{
  "status": "success",
  "message": "batch recharge created",
  "data": {
    "batch_id": "batch-12345",
    "total_count": 2,
    "status": "processing"
  }
}

Error Handling

Standard Error Response Format

{
  "status": "error",
  "message": "Error description",
  "data": null
}

Common HTTP Status Codes

• 200 - Success
• 400 - Bad Request (validation errors)
• 401 - Unauthorized (authentication required/invalid)
• 422 - Unprocessable Entity (business logic errors)
• 429 - Too Many Requests (rate limited)
• 500 - Internal Server Error

Common Error Scenarios

1. Invalid Phone Number: Phone number format validation fails
2. Insufficient Funds: User's wallet balance is insufficient for the recharge
3. Wallet Not Found: User doesn't have a wallet in the specified currency
4. Rate Limiting: Too many requests in the rate limit window
5. Invalid PIN: Authentication fails due to incorrect PIN
6. User Not Found: Phone number is not registered in the system

Integration Notes

Phone Number Format

• Must be in international format (e.g., +263771234567)
• System validates phone number format before processing
• During account creation, local format numbers are automatically converted to international format

Currency Handling

• Amounts are specified in the smallest currency unit (cents for USD, etc.)
• Supported currencies depend on server configuration

Transaction References

• Must be unique per transaction
• Used for idempotency and tracking
• Recommended format: timestamp-based or UUID

Authentication Best Practices

• Store JWT tokens securely
• Handle token expiration gracefully
• Implement proper logout functionality

Rate Limiting

• Single airtime endpoint has rate limiting enabled
• Monitor response headers for rate limit information
• Implement proper backoff strategies

Security Considerations

• All communication must be over HTTPS
• JWT tokens have expiration times
• PIN-based authentication provides additional security layer
• Rate limiting prevents abuse