Schoolcomms API - General principles (Cashless retailer)

  • The Schoolcomms APIs are available over HTTPS as a SOAP Web Service.
  • The APIs are designed to be invoked by the Cashless Retailing partner. This will enable the partner to push or pull data to and from Schoolcomms as appropriate.
  • It is anticipated that the Cashless retailing partner will invoke the APIs at regular intervals to keep both Schoolcomms and themselves up to date. The frequency with which calls are made will need to be agreed based on the requirements of both parties. It is anticipated that this will be discussed and agreed during the integration set up.
  • Each call requires that the Schoolcomms user credentials are passed so that the partner can be authenticated.
  • The following types of data can be exchanged
    • Account payments which are funds received through Schoolcomms for school dinner money accounts for a member
    • Transaction records which model real world activities that results in a change to a member’s cashless retailing balance. There are three ‘flavours’ of transaction record
      • Sales - the details of the purchases made through the tills. This can be presented as a single record with a description that combines all items bought at the till (e.g. ‘Ham, eggs and cola’) or a single record per purchase item.
      • Top-ups – represents an account payment (or a withdrawal if supported by the cashless retailer).
      • Balance Only - provided to allow cashless retailers who do not report to Schoolcomms at transaction level detail to be able to upload current member balances.

      It is assumed that every transaction submitted to the schoolcomms database via the API will include the latest accurate balance for the member in question.
      To ensure data transfer is not duplicated it is assumed that all partners will provide a unique ID with every transaction they upload (see the API definition below for more details). If this is going to pose a problem for a partner then please let the Schoolcomms team know as early as possible in the integration process. If you cannot provide us with a unique ID for each transaction then you must provide us with a daily ‘balance only’ transaction for each school member. This will be used as the source for calculating each members balance.

      • Account payments are pulled by the cashless retailing system from Schoolcomms (master data source). It is anticipated that the cashless retailer will immediately ‘echo’ this back to Schoolcomms in the form of a Top-up transaction record that holds the new balance.
      • Transaction records are pushed by the cashless retailing system (master data source) to Schoolcomms
      • The API requires partners to pass each member’s unique SIMS ID during data exchanges with Schoolcomms to act as a common identifier that both parties recognise.
      • It is assumed that each partner deals with students and staff in exactly the same way and that they will pass us data for both with the appropriate SIMS ID.