List services

GET /v1/services

Returns the service catalogue for a service country, already resolved for the authenticated customer: items the customer cannot see are omitted, and each item carries its server-computed visibility and executability state.

Query parameters

Param	Type	Required	Notes
`country`	string	yes	ISO 3166-1 alpha-2 service country, e.g. `NG`

country is the service country, not the customer's account country. Pass the customer's home country for the home catalogue. Requesting a country the customer is not eligible for returns 403 with SERVICE_COUNTRY_NOT_ELIGIBLE.

Request

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

Response `200`

{
  "data": {
    "country_code": "NG",
    "items": [
      {
        "service_code": "airtime",
        "title": "Airtime",
        "description": "Mobile airtime top-up",
        "icon": "phone",
        "icon_url": null,
        "category": "mobile",
        "sort_order": 1,
        "state": "active",
        "access": { "visible": true, "executable": true },
        "availability": { "status": "available", "reason": null },
        "presentation": {}
      },
      {
        "service_code": "internet",
        "title": "Internet",
        "description": "ISP and broadband",
        "icon": "globe",
        "icon_url": null,
        "category": "utilities",
        "sort_order": 8,
        "state": "coming_soon",
        "access": { "visible": true, "executable": false },
        "availability": { "status": "coming_soon", "reason": "rolling_out" },
        "presentation": { "badge": { "label": "Coming soon", "tone": "info" } }
      }
    ]
  }
}

Item fields

Field	Type	Notes
`service_code`	string	Stable code used on every other services call
`title`	string	Display name for this country (localized where configured)
`category`	string	Catalogue group: `mobile`, `utilities`, `entertainment`, `education`, `finance`
`state`	string	`active`, `coming_soon`, `maintenance`, `unavailable`
`access`	object	`visible` / `executable`: render and purchase gates
`availability`	object	`status` + machine-readable `reason` when not available
`presentation`	object	Server-owned badges and display hints
`actions`	array	Optional campaign actions (e.g. interest sign-up)

Only render tiles where access.visible is true (items failing that check are not returned). Only attempt a purchase where access.executable is true: a coming_soon tile is browsable but its definition endpoint rejects with SERVICE_NOT_EXECUTABLE.

Cache the catalogue

The catalogue is cacheable for a few minutes per country. Availability state can change with maintenance windows and feature rollouts, so re-resolve before checkout rather than caching across sessions.

Errors

HTTP	`error.code`	Cause
400	`VALIDATION`	Missing or malformed `country`
403	`SERVICE_COUNTRY_NOT_ELIGIBLE`	Country not eligible for this account
404	`NOT_FOUND`	Country not found or disabled
503	`MAINTENANCE`	Catalogue under a maintenance window