Countries

OuiPay scopes every account and every operation to countries. Two distinct concepts exist, and conflating them is the most common integration bug:

Home country is the customer's residency: it comes from the authenticated identity, never from request input. Service country is a per-transaction choice: the destination market for a service purchase.

Home services, cross-border by capability

The home catalogue (GET /v1/services?country=<home>) is always the customer's home country. Cross-border purchase is an intentional, per-service action gated by platform configuration and eligibility: a Benin account can buy Nigerian airtime when airtime is enabled for cross-country use, without the account becoming a Nigerian account.

Two error codes keep the distinction honest:

The country_context selector

Service definitions and /availability return country_context: the server-resolved answer to "can this customer pick another country for this service, and which ones".

{
  "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 }
    ]
  }
}

Branch on can_select_other_country, never on a capability flag. When the mode is home_country, pass the home code as country on catalogue, quote, and order calls.

The public country catalogue

The countries endpoints are unauthenticated and safe to call at boot: they carry the display and capability metadata clients need to render locale, currency, and feature surfaces.