{ }

API Reference

REST API v1.0 — Base URL: https://jiyudata.app/api/external/v1

Get API Access
Section: authentication
1

Authentication

All API requests require authentication via a Bearer token in the Authorization header. You can generate and manage API keys from your dashboard after signing up.

API Key Format

Authorization: Bearer jd_live_abc123def456xyz789

API keys are prefixed with jd_ and are shown only once at creation. Store them securely — treat them like passwords.

2

Errors

The API uses standard HTTP status codes. All errors return a JSON object with an error field describing what went wrong.

Error Response Format

{
  "error": "A human-readable error message describing what went wrong"
}

HTTP Status Codes

200SuccessRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid parameters or request body
401UnauthorizedMissing or invalid API key
403ForbiddenAPI key lacks required permissions
404Not FoundResource doesn't exist
429Too Many RequestsRate limit exceeded
500Server ErrorInternal server error
502Bad GatewayUpstream service error
3

Rate Limits

API requests are limited to 100 requests per minute per API key. Rate limit headers are included in all responses so you can track your usage.

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600
X-RateLimit-Limit

Max requests per window

X-RateLimit-Remaining

Requests remaining in window

X-RateLimit-Reset

Unix timestamp when window resets

GET

Bundles

Retrieve available data bundles with pricing information. Optionally filter by network.

GET/bundles

List all active data bundles

Parameters

networkoptional
string

Filter by network — mtn, telecel, or airteltigo

Response

{
  "bundles": [
    {
      "id": "cm3abc123def456",
      "network": "mtn",
      "sizeGb": 5,
      "validityDays": 7,
      "priceGHS": 15.50
    },
    {
      "id": "cm3xyz789ghi012",
      "network": "mtn",
      "sizeGb": 10,
      "validityDays": 14,
      "priceGHS": 28.00
    }
  ]
}
POST/GET

Orders

Create new data bundle orders and check their delivery status.

POST/orders

Create a new data bundle order

Parameters

networkrequired
string

Network: mtn, telecel, or airteltigo

sizeGboptional
number

Custom size in GB (1–100)

bundleIdoptional
string

Preset bundle ID (alternative to network + sizeGb)

recipientPhonerequired
string

Recipient phone number (e.g. 0241234567)

callbackUrloptional
string

Webhook URL for status updates

Response

{
  "orderId": "cm3order123abc",
  "authorizationUrl": "https://checkout.moolre.com/pay/ref_abc123xyz789",
  "reference": "ref_abc123xyz789",
  "expiresAt": "2026-07-07T09:00:00Z"
}
GET/orders/{orderId}

Retrieve order status and details

Parameters

orderIdrequired
string

Order ID returned from order creation

Response

{
  "id": "cm3order123abc",
  "status": "DELIVERED",
  "network": "mtn",
  "sizeGb": 5,
  "validityDays": 7,
  "recipientPhone": "0241234567",
  "amountGHS": 15.50,
  "externalRef": "ref_abc123xyz789",
  "supplierRef": "sup_456def",
  "createdAt": "2026-07-07T08:30:00Z",
  "deliveredAt": "2026-07-07T08:31:15Z"
}
GET

Networks

List all supported mobile networks in Ghana available for data bundle purchases.

GET/networks

List all supported networks

Response

{
  "networks": [
    {
      "id": "mtn",
      "name": "MTN",
      "color": "#FFD700",
      "textColor": "#000000",
      "description": "MTN Ghana data bundles"
    },
    {
      "id": "telecel",
      "name": "Telecel",
      "color": "#E4002B",
      "textColor": "#FFFFFF",
      "description": "Telecel Ghana data bundles"
    },
    {
      "id": "airteltigo",
      "name": "AirtelTigo",
      "color": "#3654FF",
      "textColor": "#FFFFFF",
      "description": "AirtelTigo Ghana data bundles"
    }
  ]
}
&

Webhooks

Receive real-time notifications when your order status changes. Configure your webhook endpoint URL when creating orders via the callbackUrl parameter.

Webhook Events

order.createdOrder was created and is pending payment
order.paidPayment confirmed — order is being fulfilled
order.deliveredData bundle has been delivered to recipient
order.failedOrder failed during fulfillment
order.refundedOrder was refunded

Webhook Payload

{
  "event": "order.delivered",
  "orderId": "cm3order123abc",
  "status": "DELIVERED",
  "timestamp": "2026-07-07T08:31:15Z"
}

Your endpoint must respond with 200 OK within 5 seconds. We'll retry up to 3 times with exponential backoff if your endpoint doesn't respond.

Need help? Contact support or get started with your integration.