3rd Party Cash Off Integrations

 

Back Office > Terminal Sales > Terminal Cash Off

 

Description

 

SwiftPOS integrates with the following 3rd Party systems enhancing the Terminal Cash Off processes:

 

  1. Banktech - The integration with Banktech provides SwiftPOS Sites/Venues with fast, accurate and secure Cash Declarations which can then be committed in SwiftPOS Back Office.

 

Pre-Requisites

 

  1. SwiftPOS V10.40 or higher.
  2. A SwiftPOS Web API licence is required for at least one Location.
  3. Ensure the Create terminal cash off records option is selected for the Location Groups (Venues) in which he 3rd Party integration is going to be used.
  4. Ensure the Function Print Reports POS Key is added to the appropriate Layout using the Keyboard Designer.
  5. At each SwiftPOS Touch terminal ensure the following:
    1. The Media Declaration at POS when resetting reports option is unselected.
    2. Ensure a Report is configured with the Reset sales after print option is selected.
    3. Liaise with the Site/Venue and set the Cash Off by Cash Drawer option appropriately to reflect whether the Site/Venue makes use of multi-cash drawers. Set to ensure that the correct Drawer ID is passed to the 3rd Party.

  6. Ensure all Terminal Cash Offs are Cashed Off (committed) prior to the 3rd Party integration being used. The Integration is designed to tag all uncommitted Cash Offs with an External Trans ID (for example a Banktech Declaration ID). Note : It maybe advisable to use the Merge Cash Offs feature to merge uncommitted Cash Offs where possible and commit them in one action.
  7. The Cloud Onboarding process must be completed for the Site's/Venue's Customer Number.
  8. Ensure the SwiftPOS Gateway Client service is running.
  9. Ensure the Sales Processing service is running.
  10. Ensure the setup of the SwiftAPI has been done and is accessible from wherever the SwiftPOS Gateway Client service is running.
  11. Ensure a Location has been configured as a Web API Location Type here and has been Activated ensuring that a Cloud Client ID is displayed.

 

Overview

 

For a more full and detailed explanation see Operation below.

 

  1. A reset Z Report is run at a SwiftPOS Touch Terminal.
  2. Once the Z Report has been processed by the Sales Processing Service a Terminal Cash Off entry should appear in Back Office. Note : This entry will NOT have a value in the External Trans ID column
  3. Tthe 3rd Party will then connect to SwiftPOS via API calls to locate undeclared and uncommitted Cash Offs commencing with the oldest:
    1. An Actual value will be returned by the 3rd Party to be recorded against the Cash Off entry in SwiftPOS. SwiftPOS will calculate any potential Variance.
    2. The 3rd Party will also return an External Trans ID which will also be recorded against the Cash Off entry indicating that a Cash Off has been done.
  4. The Cash Off entry can then be Committed in SwiftPOS and finalised.

 

Setup

 

  1. Locate the Clerk Security Group assigned to the Clerk ID used during the Activation process. Once found, ensure the Clerk Group Permissions > Web > Web API > POST CashReconciliation option is selected.
  2. In Cloud Connectivity, select the Location's Cloud Client ID and locate the Permissions menu. Once located
    1. With the 3rd Party  (for example Banktech) option selected in the Select Integrator list, ensure the PostPaymentTypeDeclaration option is selected.
    2. Select Update to save the change.

 

Operation

 

  1. Run the Report configured above (Z Report) at the SwiftPOS Touch Terminal. Note : Ensure the Clerk/Staff Member the runs the Report (Z Report) is used by the 3rd Party.
  2. Wait until the Sales Service has run and processed the Z Report. Once run a Terminal Cash Off entry should appear in Back Office. Note : This entry MUST exist prior to the 3rd Party making the API call. Hence, it is important to ensure the Sales Service is processing sales frequently. SwiftPOS Touch Terminals that have been offline should be brought online and their sales processed in Back Office before a 3rd Party API call.
  3. The 3rd Party makes a MSL Connect API call method with values. This is translated/passed through to the SwiftPOS API at the venue.
    1. Production API Endpoint = https://connect-api.mpowermsl.com/pos/{clientID}/payment_types/declaration
      1. The ClientID will differ from venue to venue. It's the Cloud Client ID generated when a Location is activated in Back Office.
    2. Swagger API Documentation = Swagger UI
    3. Headers =
      1. Content-Type = application/json
      2. Authorization = Legacy
      3. Connect Signature = This is provided to the 3rd Party by MSL when they are onboarded to use the MSL Connect API.
      4. Connect Encrypted Key = This is provided to the 3rd Party by MSL when they are onboarded to use the MSL Connect API.
    4. Body =
      1. {
        "posTerminalId": 1,
        "paymentTypeId": 1,
        "employeeId": 0,
        "declarationId": "Ref5",
        "drawerId": 1,
        "amount": 150.00,
        }
      2. terminalId (the SwiftPOS Terminal ID that the declaration is for).
      3. paymentTypeId (the SwiftPOS Media ID/Type being declared. Will usually be '1' for Cash).
      4. employeeId (the SwiftPOS Clerk ID/Number that performed the Z Read (Reset) at the Touch Terminal).
      5. declarationId (the unique ID for this declaration which gets tagged against the Terminal Cash Off).
      6. drawerId (the Cash Drawer number to match on for situations where multiple drawers are used per terminal. This is optional as the value of '0' will be substituted if not supplied).
      7. amount (the amount/value of the Payment/Media being declared).
  4. SwiftPOS API will use the posTerminalId, employeeId and drawerId and attempt to find the oldest record (based on the Reset From Date) that is NOT finalised and does NOT have an External Trans ID populated. If a record is found, it will build the Terminal Cash Off media lines behind the scenes, it will populate the 'amount' that was supplied by the 3rd Party into the 'Actual' column of the Media ID. E.G. if the paymentTypeId was '1' and amount was '130', then the Cash media line within the Terminal Cash Off record will have an 'Actual' value of 130.00 populated. It will also store the declarationId passed by the 3rd Party as the External Trans ID to ensure it can't be updated again.
    1. SwiftPOS API will calculate the difference between the 'Expected' value based on sales data and the 'Actual' value supplied by the 3rd Party and return this in the API response.
      1. EG if the Expected value was 140.00 and the Actual value passed in by the 3rd Party was 130.00, the Variance in the response body will be '10'.
    2. The response will also contain the declarationId that was passed in by the 3rd Party. This is the 'Trans_id' which MSL Connect API translates to 'declarationId' back to the 3rd Party.
    3. If an error is encountered, the response will also contain 'errorMessage' with information pertaining to why an error was encountered. The types of errors that can be encountered are documented below:
      1. If the SwiftPOS API fails to find a valid Terminal Cash Off record to update based on the values passed in by the 3rd Party, it'll return the message ???Invalid details for an Available Cash Reconciliation Deposit???.
      2. ???Validation of the request failed.??? = poor data passed into the API request.
      3. ???The external transaction id is invalid.??? = no declarationId passed in by the 3rd Party.
      4. ???terminal is invalid.??? = if the terminalId passed in by the 3rd Party is '0'.
      5. ???Cash Drawer is Invalid??? = if the drawerId passed in by the 3rd Party is less than '0'.
  5. Terminal Cash Offs lists all the uncommitted Cash Off entries. A value displayed in the External Trans ID column will indicate it has been been declared by the 3rd Party.
  6. Complete the SwiftPOS Cash Off process in SwiftPOS, which includes but is not limited too:
    1. Optionally Merging Cash Offs. Note : Only one External Trans ID will be stored against the Merged Cash Off entry.
    2. Opening an uncommitted Cash Off record, declaring the other Media(s) that may have also been used. Note :  It is possible to adjust the Backtech Actual value which was used to calculate the variance returned.
    3. Adding any variance comments.
    4. Committing the Cash Off.
    5. This will generate a Cash Off Detailed report with the variances reported.

 

Related Topics

 

  1. Cash Offs

 

Published 28 Mar 2024