Service definition

GET /v1/services/{serviceCode} : form schema, limits, and country context for one service.

GET /v1/services/{serviceCode}

Returns everything a client needs to render a purchase flow for one service: the ordered input steps, country-scoped rules and limits, the payment methods resolvable for this customer, and the country_context selector contract.

Path and query

Param	In	Required	Notes
`serviceCode`	path	yes	Catalogue code, e.g. `electricity`
`country`	query	no	Service country. Omit to resolve from the customer's home

Request

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

Response `200`

{
  "data": {
    "service_code": "electricity",
    "title": "Electricity",
    "description": "Prepaid electricity",
    "icon": "zap",
    "category": "utilities",
    "country_code": "NG",
    "requires_validation": true,
    "steps": [
      {
        "type": "select-variant",
        "label": "Meter Type",
        "placeholder": "Prepaid / Postpaid"
      },
      {
        "type": "select-operator",
        "label": "Distribution Company",
        "placeholder": "Select DisCo"
      },
      {
        "type": "account-input",
        "label": "Meter Number",
        "placeholder": "Enter 10-13 digit meter number",
        "min_length": 10,
        "requires_validation": true,
        "keyboard": "number-pad",
        "labels_by_variant": {
          "prepaid": "Prepaid Meter Number",
          "postpaid": "Postpaid Meter Number"
        }
      },
      {
        "type": "amount-input",
        "label": "Purchase Amount",
        "min_amount": 100,
        "quick_amounts": [1000, 2000, 5000, 10000]
      }
    ],
    "country_context": {
      "home_country": { "code": "NG", "name": "Nigeria" },
      "selection": {
        "mode": "home_country",
        "can_select_other_country": false,
        "enabled": true
      },
      "available_countries": [
        { "code": "NG", "name": "Nigeria", "is_home_country": true }
      ]
    },
    "rules": { "meter_types": ["prepaid", "postpaid"] },
    "limits": { "min_amount_minor": 10000, "max_amount_minor": 5000000 },
    "payment_methods": [
      { "method": "wallet", "enabled": true },
      { "method": "card", "enabled": true }
    ]
  }
}

Steps

steps is the server-owned form schema. Render the inputs in order; the API can add labels, constraints, and new services without a client release.

Step type	Collects	Options come from
`select-operator`	`operator_code`	`GET /services/{code}/operators`
`select-variant`	`meter_type`	`GET /services/{code}/variants`
`select-plan`	`product_code`	`GET /services/{code}/plans`
`phone-input`	`phone`	customer input
`account-input`	`account_ref`	customer input, verify via `/validate`
`email-input`	recipient email	customer input
`amount-input`	`provider_cost_minor`	customer input within `limits`
`review`	confirmation	render the quote before ordering

Step fields clients should honour: label, placeholder, min_length, max_length, keyboard, requires_validation, quick_amounts, min_amount, labels_by_variant, placeholders_by_variant, picker.

`country_context`

The country selector contract for this service and customer. Render a country picker only when selection.can_select_other_country is true, and limit the choices to available_countries. See Countries for the full model.

Errors

HTTP	`error.code`	Cause
403	`SERVICE_COUNTRY_NOT_ELIGIBLE`	Requested `country` not eligible for the account
404	`NOT_FOUND`	Unknown `serviceCode`
422	`SERVICE_UNAVAILABLE`	Service not available in the resolved country
422	`SERVICE_NOT_EXECUTABLE`	Visible but not purchasable (e.g. `coming_soon`)

SERVICE_NOT_EXECUTABLE responses carry the tile presentation (title, icon, state, actions) so clients can render a coming-soon screen without inventing copy.

Availability

GET /v1/services/{serviceCode}/availability

Compact selector check: whether the customer can pick another country for this service, and the countries they may pick. Use it to decide whether to render a country row before loading the full definition.

{
  "data": {
    "service": { "code": "airtime", "name": "Airtime", "status": "active" },
    "country_context": {
      "home_country": { "code": "BJ", "name": "Benin" },
      "selection": {
        "mode": "selectable",
        "can_select_other_country": true,
        "enabled": true
      },
      "available_countries": [
        { "code": "BJ", "name": "Benin", "is_home_country": true },
        { "code": "NG", "name": "Nigeria", "is_home_country": false }
      ]
    }
  }
}

Payment methods

GET /v1/services/{serviceCode}/payment-methods?country=NG

Policy-resolved payment methods for this service and country: the subset of payment_methods from the definition, evaluated for the customer's current lifecycle state. country defaults to the customer's home country when omitted.

{
  "data": {
    "items": [{ "method": "wallet", "enabled": true }],
    "service_code": "airtime",
    "country_code": "NG",
    "channel": "mobile"
  }
}

Service definition

On this page