What is WAVit?

1. 1
   Animated splashAnimatedSplashActivity (the only launcher) starts Clarity on Android 10+, plays the logo animation and hands over to SplashActivity.
2. 2
   Background servicesWavItApplication.startApp() starts CardBroadcastDisableService — it swallows Clover's card-inserted and card-swiped broadcasts so Clover's own Sale app does not pop up — and schedules the nightly log upload for about 01:30.
3. 3
   Identify the deviceMerchantConnector returns the merchant; MerchantDevicesV2Connector returns the serial number. A serial that does not start with C stops here with "device not found".
4. 4
   Token and settingsPOST api/authenticate with the serial yields the device bearer token; GET api/SqlConfig returns the merchant's Settings. A failure shows a retry dialog.
5. 5
   Integration setupDepending on integrationType: fetch the Fortellis token and advisor list, load the DealerTrack service-writer or parts-counter lists, or prepare the tethered QR and payment connector. Terms & conditions are shown first if forceTermsAcceptance is on.
6. 6
   ReadyThe external-POS listener starts, WAVit Pro is enabled or disabled from the settings, and the terminal sits on an idle full-screen "tap to start" in Clover customer mode.
7. 7
   Tap to startOptional employee-ID prompt (standalone with promptForEmployeeId), optional unlock PIN, then either the amount keypad or — for a dealership — the advisor / employee ID dialog and the repair-order screen.

• Merchant terminal (integrated and terminalType = Merchant): enters the amount and sends it to the paired customerFacingTerminal through PaymentsAgent. It skips tipping.
• Customer terminal (integrated and terminalType = Customer, the default): waits for requests. Its overflow menu needs the unlock PIN.
• Bypass DMS: with bypassIntegration on, a dealership terminal can run as standalone after the bypassPIN is entered.

Split payment, custom split and the partial-payment screen still exist in the source but nothing reaches them — their launch points and manifest entries are commented out. Partial approvals are handled on the Review screen instead (see the flows below).

1. 1
   AmountThe keypad works in cents. Next runs Calculation.calculateTransactionAmount(sale) to get surcharge, tax and total, and assigns a fresh payment UUID. Invoice number and required custom fields are validated first.
2. 2
   TipTiles are gratuityPercent1-3 of the tip base, or flat amounts (gratuityFlat1-3) when dynamic tipping is on and the base reaches tipThresholdAmount. Custom tips are capped at 10× the total.
3. 3
   ReviewThe header shows total + tip. The first enabled tender is pre-selected; with amountDisplay = Buttons every tender button shows its own price.
4. 4
   Pre-transactionPay sends POST api/mitransaction to MiPoint API with the amounts, invoice, advisor, employee and custom fields and TransactionStatus 9. The returned id is kept for the post-transaction update.
5. 5
   Order (carts only)With an inventory cart, POST /api/orders creates the MiPoint order first; the server prices it.
6. 6
   Clover salePaymentConnector.sale() with the total and the tip provided separately. Clover's own signature screen, receipts and printing are turned off, offline payments are refused, and the invoice number travels as externalReferenceId.
7. 7
   SignatureWAVit's own signature pad, unless disableSignature is on. The image is stored with the transaction and printed on the receipt.
8. 8
   Post-transaction chainValidate the payment through Clover REST → PUT api/mitransaction/Clover/{id} with card details and signature → Reynolds only: close the repair order → set the Clover order note to the tender caption → decrement stock per cart line → check for a partial approval.
9. 9
   ReceiptNone, Print, Email or Text, then back to Splash. The final payment record goes to POST api/MiTransaction through the Room outbox.

• A positive balance runs the standard sale with the RO number as the invoice number.
• A negative DealerTrack or Reynolds balance runs a manual refund of the absolute amount (TransactionTypeId 14).
• A zero balance shows "Outstanding balance is 0.00" — except on Fortellis, where $0.00 can be paid.
• The RO number, advisor ID and name travel only in the MiPoint transaction records; any posting back to DealerTrack or CDK happens on the backend.

1. 1
   SessionOn the Review screen the app gets a Fincretive store token and runs an FCL Login. Credentials come from the merchant's settings.
2. 2
   Card readClover readCardData() returns BIN, last four, expiry and the name in LAST/FIRST form. A validation swipe on the paired MagTek tDynamo follows; the flow stops with "Pair your tDynamo in EBT Settings" if it is not connected.
3. 3
   Order and authorisePOST /api/orders returns server-side totals and item snapshots, then FCL Authorize sends the order total including tax, with an eligibility flag per item.
4. 4
   SNAP or HBCAn HBC/OTC processor prints an approval chit when some items were rejected. For SNAP, state-restricted items print a bilingual "Items Not Allowed" chit, then the cashier confirms "Apply $X to SNAP/EBT tender?" — No voids the authorisation.
5. 5
   RemainderOrder total minus the benefit amount. Zero completes the order; anything left is collected by card or cash with no tax, tip or surcharge added. One combined receipt prints.

Worked example: an order of $15.50 plus $0.74 tax is $16.24. SNAP pays item value only, say $10.00, leaving $6.24 for card or cash. An HBC/OTC card covers value plus tax, so nothing is left. Refunds are item-level from Benefit Transactions; voiding from history is disabled on purpose.

The server marks the Clover catalogue up by raisedAmountPercent, so Register shows card prices. When the cashier presses Pay, WAVit Pro shows a Card / Cash overlay; choosing Cash adds one fixed order discount (caption cashPaymentDiscountCaption, default "Cash Payment Discount") so the customer pays the original cash price. Choosing Card removes any such discount.

• Enabling: when settings load with enableWavitPro on, the order receiver is enabled and the foreground WavitProService starts, optionally after a welcome and terms dialog (requireWavitProTermsAcceptance). Acceptance is recorded on the server. A boot receiver restarts the service after a reboot or update.
• Baselines: once per service start, GET api/wavitpro/item-baselines pulls each item's cash price in cents. The terminal never writes inventory prices; the server does.
• Custom items typed into Register are marked up the moment they are added (discountCustomItems). Clover rejects in-place price changes, so the line is re-added at the new price and the original deleted.
• The discount is card total minus cash baseline. With wavitProCashDiscountPostTax it is divided by (1 + tax rate), so the grand total drops by exactly the difference once Clover recomputes tax.
• Idempotent: an existing discount with the same caption is removed before the new one is added.
• The overlay needs Android's draw-over-apps permission. Settings are edited in the Configurator; the on-device WAVit Pro screen is read-only.

surcharge = sale × surchargePercent / 100
if taxRate > 0:
    tax = sale × taxRate / 100
    if surchargePostTax: surcharge = (sale + tax) × surchargePercent / 100
total = sale + surcharge + tax        // summed from unrounded parts
each value is then rounded to 2 dp on its own

• Tax is on the sale only; the surcharge is never taxed. With a tax rate of 0, surchargePostTax has no effect.
• Tip base = sale, plus surcharge if isTipPostSurcharge, plus tax if isTipPostTax. The tip screen's "Subtotal" is sale + surcharge.
• Tender discount = sale × the tender's discount %, or (sale + tax) × % when surchargePostTax is on.
• Amount to pay = total + tip − discount. Clover receives the total and the tip separately.
• There is no separate convenience-fee field: a convenience fee is the surcharge under a different surchargeCaption.

The unit tests pin these rules down as characterisation tests, including a golden case taken from production logs (sale 100, surcharge 3% pre-tax, tax 8% → subtotal 103, total 111). Several of those tests are named *_knownBug and document behaviour that is wrong but relied on — read them before changing any money code.

• TransactionStatus: 9 on a pre-transaction, 1 when a tip is added.
• Tender types: Cash, Card, Debit, Invoice, QRScan (Citcon; the tender's mid holds the store token), ManualRefund.
• MiPoint order status: Pending, Submitted, Authorized, Completed, Voided, Refunded, Failed.
• FCL ResponseCode "1" is success. Seen in the wild: 102 bad track name, 1009 missing void fields, 1012 unknown BIN, 413 refund-sum mismatch.

• Tax and tip are under-reported in the final payment record. BaseViewModel.sendPaymentResponse casts dollars to a long and then divides by 100, so $8.25 tax is recorded as $0.08. Refund records are correct.
• Two integrations are wired to development hosts in production builds: the Fincretive gateway (FincretiveApi, marked TODO(prod)) and the stock-update calls after a cart sale (VerifyTransactionViewModel).
• The Room outbox uses destructive migration. The declared migrations are never registered, so any schema version bump deletes unsent payment records.
• `PostTransactionWorker` drops queued updates on any HTTP response, including 4xx and 5xx, and drains only one item per run. Workers return success before their request finishes, so WorkManager never retries.
• A stale repair order can be paid: after a failed second lookup, the previous RO's card and Next button stay on screen (DealerTrack and Fortellis).
• The cart is cleared before payment, so a cancelled payment loses it.
• Refund amounts are parsed by deleting separators: a typed "12" refunds $0.12.
• Tax may be applied twice to DMS amounts if a dealership merchant has a tax rate configured.
• Citcon QR refunds and voids do nothing — the refund call is never made.
• Terms-and-conditions acceptance is not stored and termsAndConditionsAddress is ignored in favour of a fixed URL.

• APKs are v1 (jar) signed only. Clover requires it; v2 stays off.
• One API call at a time. WebApiCaller cancels the in-flight request whenever a new one starts, which is why every view model chains its calls. MiPoint order create and update are exempt — cancelling them left orders stuck in Pending.
• Clover's Sale app is suppressed. CardBroadcastDisableService aborts the card-inserted and card-swiped broadcasts so presenting a card does not open Clover's own app over WAVit.
• The terminal is read-only for inventory prices. On-device bulk inflation caused a write storm across terminals, so the server owns price writes and the terminal only reads baselines.
• Voiding a benefit order from history is disabled. Refunds are item-level through FCL instead.
• Signatures are WAVit's, not Clover's. Clover's signature screen is turned off so the signature can be stored with the MiCamp transaction and printed on WAVit's receipt.
• Settings are never edited on the device. The Configurator is the single place to change them; the on-device screens only display them.