Service options

Three endpoints resolve the options behind a service's select-* steps. All are scoped by service country and re-check the customer's eligibility for that country.

Operators

GET /v1/services/{serviceCode}/operators?country=NG

The operators behind a service: mobile networks for airtime/data, distribution companies for electricity, TV providers for tv, exam bodies for education, insurers for insurance. The catalogue is normalized across fulfilment rails: one code + title per operator.

curl "https://api.ouipay.africa/v1/services/airtime/operators?country=NG" \
  -H "Authorization: Bearer sk_test_..."

{
  "data": {
    "service_code": "airtime",
    "country_code": "NG",
    "items": [
      {
        "code": "mtn",
        "title": "MTN",
        "service_code": "airtime",
        "country": "NG"
      },
      {
        "code": "airtel",
        "title": "Airtel",
        "service_code": "airtime",
        "country": "NG"
      }
    ]
  }
}

Pass the selected code as operator_code on plan listing, validation, quote, and order calls. For the networks each market carries today, see Supported networks.

Plans

GET /v1/services/{serviceCode}/plans?country=NG&operator=mtn

Fixed-price products for a service and operator: data bundles, TV bouquets, coverage tiers, exam PIN packages.

curl "https://api.ouipay.africa/v1/services/data/plans?country=NG&operator=mtn" \
  -H "Authorization: Bearer sk_test_..."

{
  "data": {
    "service_code": "data",
    "country_code": "NG",
    "operator_code": "mtn",
    "kind": "plans",
    "presentation": {
      "picker": "tabs",
      "categories": ["daily", "weekly", "monthly"]
    },
    "items": [
      {
        "code": "mtn-1gb-daily",
        "title": "1GB - 1 day",
        "operator_code": "mtn",
        "service_code": "data",
        "country": "NG",
        "amount_minor": 35000,
        "currency": "NGN",
        "validity": "1 day",
        "category": "daily",
        "pricing": "fixed"
      }
    ]
  }
}

presentation.picker is the server-owned render verdict: tabs for large categorized catalogues, select otherwise. Render presentation.categories as the tab order.

Some catalogues price per destination (the same operator can return different bundles per phone number). When a definition's plan step appears before the recipient input, pass phone or account_ref once collected to refresh the list.

Variants

GET /v1/services/{serviceCode}/variants?country=NG

Country-configured variants for a service, most commonly meter type on electricity (prepaid, postpaid). Variants are platform configuration, not a vendor catalogue: a country whose rail has no metered billing returns an empty list, and the definition drops its select-variant step.

{
  "data": {
    "service_code": "electricity",
    "country_code": "NG",
    "items": [
      { "code": "prepaid", "title": "Prepaid" },
      { "code": "postpaid", "title": "Postpaid" }
    ]
  }
}

Pass the selected code as meter_type on validate, quote, and order calls.

Errors