Service Catalog

Users are provided access to different services, and can retrieve all available services with their details using the below endpoints. The default structure is:

Category
└── Provider
    └── Service
        ├── Inputs
        └── Outputs

For example for mobile bill payment, the values will be:

Telecom
└── Vodafone
    └── Bill Payments
        ├── Inputs: Phone number
        └── Outputs: Bill due amount

Providers

Providers (including their services) can be retrieved per category

HTTP Method

GET

Endpoint

/api/v1/categories/<category_id>/providers/

Request Body

None

Headers

Authentication: <signature> (details here)

Response Sample

[
  {
    "id": 321,
    "name": "ڤودافون - فاتورة الموبايل",
    "services": [
      {
        "id": 123,
        "name": "دفع فواتير",
        "fees_inquiry_only": false,
        "can_replicate_payment": false,
        "partial_payment_allowed": true,
        "inputs": [
          {
            "description": "رقم الموبايل",
            "max_amount": null,
            "min_amount": null,
            "char_limit": 11,
            "name": "phone_number",
            "data_type": "str",
            "input_type": "numeric",
            "mandatory": true,
            "choices": [],
            "has_choices": false,
            "topup_rate": null
          }
        ],
        "inquiry_outputs": [
          {
            "description": "اسم العميل",
            "name": "client_name",
            "data_type": "str",
            "is_hidden": false
          },
          {
            "description": "تاريخ الفاتورة",
            "name": "due_date",
            "data_type": "str",
            "is_hidden": false
          },
          {
            "description": "محل الإقامة",
            "name": "location",
            "data_type": "str",
            "is_hidden": false
          }
        ],
        "payment_outputs": [
          {
            "description": "اسم العميل",
            "name": "client_name",
            "data_type": "str",
            "is_hidden": false
          },
          {
            "description": "محل الإقامة",
            "name": "location",
            "data_type": "str",
            "is_hidden": false
          },
          {
            "description": "رقم الفاتورة",
            "name": "invoice_number",
            "data_type": "float",
            "is_hidden": false
          },
          {
            "description": "رقم الموبايل",
            "name": "phone_number",
            "data_type": "str",
            "is_hidden": false
          }
        ],
        "custom_tag": null,
        "receipt_footer": "",
        "async_inquiry": false,
        "async_payment": false,
        "can_inquire_multiple_bills": false,
        "can_pay_multiple_bills": false,
        "must_pay_in_order": false
      }
    ]
  },
  {
    "id": 654,
    "name": "ڤودافون - كروت شحن",
    "services": [
      {
        "id": 456,
        "name": "كارت فكة 2.5",
        "fees_inquiry_only": false,
        "can_replicate_payment": true,
        "partial_payment_allowed": false,
        "inputs": [
          {
            "description": "المبلغ",
            "max_amount": null,
            "min_amount": null,
            "char_limit": null,
            "name": "amount",
            "data_type": "float",
            "input_type": "decimal",
            "mandatory": true,
            "choices": [
              "2.5"
            ],
            "has_choices": true,
            "topup_rate": null
          }
        ],
        "inquiry_outputs": [],
        "payment_outputs": [
          {
            "description": "كود التفعيل",
            "name": "voucher_code",
            "data_type": "str",
            "is_hidden": false
          }
        ],
        "custom_tag": null,
        "receipt_footer": "",
        "async_inquiry": false,
        "async_payment": false,
        "can_inquire_multiple_bills": false,
        "can_pay_multiple_bills": false,
        "must_pay_in_order": false
      }
    ]
  }
]

Response Description

Field	Type	Description
`id`	Integer	Unique provider id
`name`	String	Provider name in the specified language (see localization section)
`services`	List	List of available services for provider

Services

Field	Type	Description
`id`	Integer	Unique service id which will be used for consuming the service
`name`	String	Service name in the specified language (see localization section)
`fees_inquiry_only`	Boolean	Indicates if this service used normal inquiry (i.e: `/inquire/`) or only fees inquiry (i.e: `/inquire_fees/`)
`can_replicate_payment`	Boolean	Indicates if user can repeat this service inquiry & payment without new inputs
`partial_payment_allowed`	Boolean	Indicates if partial payment is allowed for this service
`can_inquire_multiple_bills`	Boolean	Indicates if multiple inquiries is available on this services, see (see multiple bills inquiry section)
`can_pay_multiple_bills`	Boolean	Indicates if multiple bills can be selected for payment in case of multiple bills inquiry, see (see multiple bills inquiry section)
`must_pay_in_order`	Boolean	Indicates if oldest bill should be paid first in case of multiple bills inquiry, see (see multiple bills inquiry section)
`custom_tag`	String	Indicates any custom tag for this service. The client can use it to guide to a different UX. Available tags: `prepaid_electricity`, `multiple_bills`
`receipt_footer`	String	Footer to be added at the receipt. Defaults to `null`
`inputs`	List	List of service inputs
`inquiry_outputs`	List	List of service outputs returned in inquiry response `data` field. Note that `inquiry_id` will always return inside `data`
`payment_outputs`	List	List of service outputs returned in payment response `data` field
`async_inquiry`	Boolean	Indicates if this service `/inquiry/` / `/fees_inquiry/` response is returned asynchronously (see async requests section)
`async_payment`	Boolean	Indicates if this service `/payment/` response is returned asynchronously (see async requests section)

Inputs

Field	Type	Description
`name`	String	Field name (key) that should be sent to the API
`data_type`	String	Input data type. One of (`str` - `float`). Make sure to cast the value to this type when sent over the API
`mandatory`	Boolean	Is this field mandatory or not
`input_type`	String	This field can guide to select the keyboard or the allowed characters for the input. Allowed values are `numeric` for numbers only - `decimal` for numbers but allowing a decimla point - `character` for alphanumeric character inputs
`has_choices`	Boolean	Does this input has fixed choices or not
`choices`	List[String]	List of available choices (only used if `has_choices` is `true`)
`description`	String	Description of the input in the specified language (see localization section)
`min_amount`	Float	Minimum allowed amount to be entered (only for amount fields). Defaults to `null`
`max_amount`	Float	Maximum allowed amount to be entered (only for amount fields). Defaults to `null`
`char_limit`	Integer	Limit of allowed characters to be entered. Defaults to `null`
`topup_rate`	Float	Only used for topup, in some cases, if the user wants to recharge by 70 EGP, they will pay 100 EGP. The rate will be 42.86% which means that the user will pay 70 * 42.86. This field is only added for enhancing the experience and should not alter the user data send to the backend

Outputs

Inquiry Outputs

The keys that are returned in inquiry/fees_inquiry response.

Note that: inquiry_id - amount - fees - date_created are always returned in inquiry response, any other extra fields will be shown in this key

Payment Outputs

Extra keys returned in payment response.

Both outputs follow the below schema

Field	Type	Description
`name`	String	Field name (key) that will be returned by the API
`data_type`	String	Output data type. One of (`str` - `float` - `list`)
`description`	String	Description of the input in the specified language (see localization section)
`is_hidden`	Boolean	Should this field be displayed or not. Defaults to False

Service Catalog

Categories

HTTP Method

Endpoint

Request Body

Headers

Response Sample

Response Description

Providers

HTTP Method

Endpoint

Request Body

Headers

Response Sample

Response Description

Services

Inputs

Outputs

Inquiry Outputs

Payment Outputs

Both outputs follow the below schema