Multiple Bills Inquiry

Some services allow to return multiple bills in case the user has multiple dues. This is optional for the API client to use.

Procedure

Call /inquiry/multiple/ this will return a list of inquiry objects in the data key
If the user is going to pay a single bill, use its inquiry_id with the /payment/ endpoint directly
If the user is going to pay multiple bills, send the inquiry ids to the endpoint /inquiry/bundle/ and this will return a single inquiry_id which can then be used with /payment/ endpoint

Important Note

There are 3 important flags in the service object (defined here) that should be respected in the flow of multiple bill payments: i. can_inquire_multiple_bills: Multiple bill inquiry is only allowed if this flag is set to true, otherwise client will receive MultipleBillInquiryNotAllowed error ii. can_pay_multiple_bills: If this flag is set to true, then the client can use /inquiry/bundle/ endpoint and pay multiple bills, else, the client should only select one inquir_id from the returned list of dictionaries, and use it in payment directly. iii. must_pay_in_order: If this flag is set to true then the bills should be paid in order (oldest to newest), as this is usually a constraint from the service provider, otherwise, the user can pay multiple bills at any order

Multiple Inquiry

Returns multiple bills for a single user input

HTTP Method

POST

Endpoint

/api/v1/inquiry/multiple/

Headers

Authentication: <signature> (details here)

Request Sample

Same as normal /inquiry/ payload

{
  "service_id": 123,
  "service_params": {
    "mobile_number": "01234567890"
  }
}

Request Description

Field	Type	Description	Mandatory
`service_id`	Integer	Unique service ID of the requested service	Yes
`service_params`	Dictionary	The service parameters as returned in the catalog	Yes, even if the service requires no parameters it should be sent as an empty dictionary

Response Sample

{
  "code": "0000",
  "request_id": "89f13824-05a4-4f9c-8c5a-43765a4f4baf",
  "data": [
    {
      "inquiry_id": 22498,
      "amount": 116.22,
      "fees": 23.24,
      "date_created": "2023-08-29T15:39:30.411869+03:00",
      "client_name": "اسم العميل رباعي هنا",
      "location": "المعادي - القاهرة"
    },
    {
      "inquiry_id": 22499,
      "amount": 96.34,
      "fees": 19.27,
      "date_created": "2023-08-29T15:39:30.435272+03:00",
      "client_name": "اسم العميل رباعي هنا",
      "location": "المعادي - القاهرة"
    },
    {
      "inquiry_id": 22500,
      "amount": 141.15,
      "fees": 28.23,
      "date_created": "2023-08-29T15:39:30.438232+03:00",
      "client_name": "اسم العميل رباعي هنا",
      "location": "المعادي - القاهرة"
    }
  ]
}

Response Description

Field	Type	Description
`code`	String	API Response code indicating the status of the request. List of codes defined here
`request_id`	String	Unique request id that can be used afterwards for logging/debugging
`data`	List[Dictionary]	Response payload of the inquiry. Includes the list of dicts containing expected outputs defined in the catalog
`data` : `inquiry_id`	Integer	Inquiry ID for each bill. This will be returned with for all inquiries without being stated in the outputs. This is used afterwards in the payment
`data` : `amount`	Float	Total amount to be paid for each bill
`data` : `fees`	Float	Total fees to be paid for each bill
`data` : `date_created`	Datetime	Datetime of the transaction in ISO format, in Africa/Cairo timezone.

Bundle Inquiries

In case the user is paying multiple bills, the client must call this endpoint in order to bundle the inquiries into a single inquiry_id that can then be used to perform a transaction.