Deliverect

Overview

This document explains how to set up the Deliverect integration feature enhancements new to 5.17.

Prerequisites

  • Registers must be on POS 5.17 or later
  • Chrome is installed on the registers

Disposition Payout Integration

Same-day payout of driver mileage and credit card tips. PAR decides how each driver is paid (PayCard, Payroll or Cash) and owns the payment provider connections. PAR handles accumulating the amounts, calling a new service, and showing the result.

How it works

  1. The driver checks in on the Deliverect terminal.

    • A new integration sends a new service the mileage and employee ID.
    • The check-in also marks the employee as eligible for a payout that business date.
  2. The service converts meters to miles, applies the per-location rate, and accumulates mileage per employee, location and business date.

  3. When the driver clocks out, the service totals all pre and post-adjustment credit card tips from the register’s order state. This covers every order the employee owned that shift, not just deliveries. Cash tips are never included.

  4. The service calls the Payroll API once per shift POST /payroll/webhook/pizza/paycard with the mileage, tips, payroll ID, location ID and business date.

  5. PAR returns the total amount and the disposition. Any total over $1,000 comes back as Cash. If the pay card integration fails, PAR POS returns Cash, and if it is unreachable after retries, it falls back to Payroll.

  6. A manager presses a register button, which opens a browser that shows the Driver Compensation report listing amount and disposition for all clocked-out drivers.

    • If the disposition is Cash, the manager can optionally record a petty-account cash out to reconcile the drawer.

Required Setup

The registers MUST have Google Chrome installed for the report to open. Before using the report script, also complete the Install Google Chrome Script setup under Scripts Needed for Deliverect at the bottom of this document, even if Chrome is already installed. That script entry defines the ResolveChromePath and FindChromeExe functions required by the report script.

  1. Payroll ID: The PAR call needs the employee’s PayrollID, not the employee ID.

    • The PayrollID can be found in the Staff.json file (need to download the Par POS settings)
    • Once downloaded search for "PayrollId"
      • Can press ctrl + f to do a search
      • Include the quotes in the search
  2. Register button: A button is configured that launches the browser report. It uses a VBScript ExecuteScript behavior, and should be permission-gated to manager and above.

Add the Script to Script Functions:

  1. Log into Settings Editor
  2. Click Script Functions
  3. Click Add New Script Function
  4. In the Name field enter RetrieveDriverCompensationReport
  5. In the text box enter the script listed in the Scripts Needed for Deliverect section of this document titled RetrieveDriverCompensationReport.vbs. Also register the ResolveChromePath and FindChromeExe helper functions shown in the Install Google Chrome Script section. Both helpers are required even when Google Chrome is already installed.
  6. Click OK
  7. Save and Publish

Add the Script Button to Layout:

  1. Log into Settings Editor

  2. Click Layout

  3. Select the desired panel

  4. Click the Add New Control Button

  5. Click the drop down next to Behavior

  6. Select Execute Script

  7. Click the Configure button

  8. Add the following:

    • RetrieveDriverCompensationReport Functions2.GetBusinessDate(), Functions2.GetLocationId(), Functions2.GetFrontendServiceSecurityToken()
  9. Make any desired changes to the position and the appearance of the button

  10. Set Permission to a permission granted only to managers and above.

  11. Save and Publish

  12. Tip adjustment tokens: the customer must deploy payment tokens for card-not-present tip adjustment.

  13. Optional petty account: Create one per driver, or use the description field to record the driver name.

    1. Log into Settings Editor
    2. Click Petty Accounts
    3. Click Add New Petty Account
    4. Enter the desired name in the Name field
    5. Account Type needs to be set to Cash Out
    6. Click the box to the left of Require Description to require a description when the Cash Out is performed on the register.
    7. Save and Publish

Workflow

  1. The driver clocks out on the register as usual. Nothing new is shown to them, and the register isn’t locked while PAR processes the payout.

  2. A manager (or above) presses the new register button. It’s permission-gated because it shows pay information for all employees.

  3. The button opens a view only browser report (Chrome)shows the driver's mileage and credit card tip compensation report for the business date, so the store can settle with drivers.

  4. If a driver isn’t listed yet, or the data looks incomplete, the last-updated timestamp tells you whether it is still pending. Close the report and reopen it shortly after.

  5. Pay the driver according to the disposition.

    • PayCard or Payroll: Nothing more to do at the register.
    • Cash: Pay the driver from the drawer. It is recommended that (but doesn’t require) recording a Petty Account cash out, so the drawer balances. The chit prints for the driver’s signature. The cash out is drawer-scoped and won’t appear on the driver’s own checkout. To attribute it, use a Petty Account per driver or put the driver name in the description field.
  6. Close the report with its exit control, so Chrome windows don’t pile up.

NOTE: The driver doesn’t see their amounts on their own checkout report. They have to ask the manager. A tip adjusted after clock-out isn’t included in the same-day payout and goes through normal payroll.

(BNZ-1849, PDOC-4433)

Driver Pay Rate Attribution

Used when customers pay drivers a lower rate while they’re on the road. POS can’t switch jobs mid-shift, so on-road time is paid at the clocked-in rate. This feature reports on-road minutes to PAR POS so it can apply the right rate.

How it works

  1. Customer sends driver checkout and checkin events to Par POS. Par POS then forwards them to a queue, using the agreed transport.

  2. Events are grouped by tripId, giving one segment per trip.

    • For example, runs of 30 and 20 minutes become two segments, because the service needs the times to compute overtime.
  3. Each segment is assigned to the shift whose start and end time bracket it.

  4. PAR POS pulls the data once after end of day, one call per location per business date.

  5. The response is keyed by shiftId, with override jobId reported once per employee and the segments listed under each shift.

    • Override minutes are a subset of the shift’s minutes.
  6. PAR POS looks up the rate from the jobId, and handles overtime.

Set up required

  1. Driver On Road job:

    • Employee Setup Requirement: It must be assigned to each employee, including managers and shift leads who take runs. Without it, no override is produced and all their minutes are paid at their clocked-in rate.
    • Job naming: The job name must contain On Road, the customer must keep it consistent across locations.
    1. Log into the Admin Portal
    2. Click Staff
    3. Click Jobs
    4. Click Add New Job
    5. In the Name field enter On Road
    6. In the delivery section click the box next to Delivery Driver
    7. Set up the rest of the page as desired
    8. Click Save
  2. Add On Road Job to All Delivery Driver Employees

    1. Click Staff
    2. Click Employees
    3. Click on desired employee
    4. Click Add Job
    5. Click the drop down under the Job field
    6. Select the On Road job created above
    7. Select desired Security Level
    8. Enter desired Pay Rate
    9. Click Save
    10. Repeat steps 2-9 for all delivery employees who will use this feature
  3. PAR provisions the queue and provides cross-account write access.

  4. PAR POS registers the check-out event type, adds a tripId field, and adds a new service.

Workflow

  1. Drivers clock in once under one job, and the on-road time comes from the check-out and check-in events.

(BNZ-1896, PDOC-4433)

Scripts Needed for Deliverect

RetrieveDriverCompensationReport.vbs

  • Script that will open the Driver Compensation report:
Sub RetrieveDriverCompensationReport(businessDate, locationId, token)
    Dim objFSO, objHTTP, shell, stream
    Dim tempRoot, reportDir, reportPath, fileUrl, chromeExePath, targetUrl

    Const BASE_URL = "https://prod.api.partech.io/pj/mileage/v1/CompensationReport"

    targetUrl = BASE_URL & "?businessDate=" & businessDate & "&locationId=" & locationId

    Set objFSO = CreateObject("Scripting.FileSystemObject")
    Set shell = CreateObject("WScript.Shell")

    ' One fixed file in %TEMP%\CompReports, overwritten every run.
    ' Falls back to %TEMP% if the subfolder can't be made.
    tempRoot = objFSO.GetSpecialFolder(2).Path
    reportDir = objFSO.BuildPath(tempRoot, "CompReports")
    If Not objFSO.FolderExists(reportDir) Then
        On Error Resume Next
        objFSO.CreateFolder reportDir
        On Error GoTo 0
        If Not objFSO.FolderExists(reportDir) Then reportDir = tempRoot
    End If
    reportPath = objFSO.BuildPath(reportDir, "compreport.html")

    Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP.6.0")

    On Error Resume Next
    Err.Clear
    objHTTP.Open "GET", targetUrl, False
    objHTTP.SetRequestHeader "Authorization", "Bearer " & token
    objHTTP.Send
    If Err.Number <> 0 Then
        Functions2.ShowMessage "HTTP Request Failed: " & Err.Description
        On Error GoTo 0
        Exit Sub
    End If
    On Error GoTo 0

    If LenB(objHTTP.responseBody) = 0 Then
        Functions2.ShowMessage "Service returned HTTP " & objHTTP.Status & " " & objHTTP.StatusText
        Exit Sub
    End If

    On Error Resume Next
    Err.Clear
    Set stream = CreateObject("ADODB.Stream")
    stream.Type = 1 ' adTypeBinary
    stream.Open
    stream.Write objHTTP.responseBody
    stream.SaveToFile reportPath, 2 ' adSaveCreateOverWrite
    stream.Close
    If Err.Number <> 0 Then
        Functions2.ShowMessage "Could not write report file: " & Err.Description
        On Error GoTo 0
        Exit Sub
    End If
    On Error GoTo 0

    chromeExePath = ResolveChromePath(objFSO)
    If chromeExePath = "" Then
        Functions2.ShowMessage "Error: Google Chrome could not be found or installed."
        Exit Sub
    End If

    fileUrl = "file:///" & Replace(reportPath, "\", "/")
    shell.Run """" & chromeExePath & """ --app=""" & fileUrl & _
              """ --start-maximized --no-default-browser-check", 1, False
End Sub

Install Google Chrome Script:

  1. Log into Settings Editor
  2. Click Script Functions
  3. Click Add New Script Function
  4. In the Name field enter InstallGoogleChrome
  5. In the text box enter the following:
Function ResolveChromePath(objFSO)
    Dim waitUntil

    ResolveChromePath = FindChromeExe(objFSO)
    If ResolveChromePath <> "" Then Exit Function

    InstallGoogleChrome
    waitUntil = DateAdd("s", 10, Now())
    Do Until Now() > waitUntil
    Loop

    ResolveChromePath = FindChromeExe(objFSO)
End Function

Function FindChromeExe(objFSO)
    Dim paths, i

    paths = Array( _
        "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe", _
        "C:\Program Files\Google\Chrome\Application\chrome.exe")

    FindChromeExe = ""
    For i = 0 To UBound(paths)
        If objFSO.FileExists(paths(i)) Then
            FindChromeExe = paths(i)
            Exit Function
        End If
    Next
End Function