openapi: 3.0.3
info:
  title: MyFatoorah Invoicing Shipping API
  description: 'MyFatoorah is a GCC/MENA online payment gateway and invoicing platform. This OpenAPI document models a representative subset of the MyFatoorah v2 REST API: payment method discovery (InitiatePayment), invoice creation against a gateway (ExecutePayment), payment-link invoicing (SendPayment), payment status inquiry (GetPaymentStatus), refunds (MakeRefund), embedded sessions, marketplace suppliers, shipping, recurring payments, and webhook retrieval.


    Access model: MyFatoorah uses a single shared TEST/sandbox host and separate per-country LIVE hosts (Kuwait/Bahrain/Jordan/Oman share one host; Saudi Arabia, UAE, Qatar, and Egypt each have their own). All requests are authenticated with a Bearer API token issued per country from the merchant portal (Integration Settings -> API Key). The `servers` list below enumerates the real hosts; pick the one matching your account''s country.


    Endpoint status: InitiatePayment, ExecutePayment, SendPayment, GetPaymentStatus, and MakeRefund are CONFIRMED from the public documentation (method, path, and core request/response fields). Remaining operations (sessions, suppliers, shipping, recurring, webhooks, supplier refunds, token cancellation) are documented by name and follow MyFatoorah''s `/v2/<Endpoint>` POST convention; their request/response schemas here are MODELED representative shapes and are marked with `x-status: modeled`. Verify exact fields against docs.myfatoorah.com before production use.'
  version: '2.0'
  contact:
    name: MyFatoorah
    url: https://myfatoorah.com
  x-api-version-note: MyFatoorah versions its REST endpoints under a /v2 path prefix. There is no documented public WebSocket API; asynchronous notifications are delivered as HTTP POST webhooks to a merchant-configured URL.
servers:
- url: https://apitest.myfatoorah.com/v2
  description: Test / Sandbox (shared, all regions)
- url: https://api.myfatoorah.com/v2
  description: Live - Kuwait, Bahrain, Jordan, Oman
- url: https://api-sa.myfatoorah.com/v2
  description: Live - Saudi Arabia
- url: https://api-ae.myfatoorah.com/v2
  description: Live - United Arab Emirates
- url: https://api-qa.myfatoorah.com/v2
  description: Live - Qatar
- url: https://api-eg.myfatoorah.com/v2
  description: Live - Egypt
security:
- bearerAuth: []
tags:
- name: Shipping
  description: Shipping lookups, charges, and pickups.
paths:
  /GetCities:
    post:
      operationId: getCities
      tags:
      - Shipping
      summary: List cities for a country
      description: Retrieves cities belonging to a country for shipping address selection. MODELED representative shape.
      x-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                CountryCode:
                  type: string
                ShippingMethod:
                  type: integer
      responses:
        '200':
          description: Cities list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing, invalid, or insufficiently-permissioned token. MyFatoorah returns 401 with a message such as "The token does not have the required permissions!".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponse'
  schemas:
    GenericResponse:
      type: object
      description: MyFatoorah standard envelope shared by all endpoints.
      properties:
        IsSuccess:
          type: boolean
        Message:
          type: string
        ValidationErrors:
          type: array
          nullable: true
          items:
            type: object
            properties:
              Name:
                type: string
              Error:
                type: string
        Data:
          type: object
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Per-country API token issued from the MyFatoorah portal (Integration Settings -> API Key). Passed as `Authorization: Bearer {token}`. Each enabled country requires its own token.'