Documentation contents

Integration guide

POS integration: apply a benefit before payment

Use this flow when your POS applies a discount or spends points before collecting payment. Grant checkouts:write and explicitly authorize financial operations in the cabinet.

Cabinet bindingValue from your system
sourceA stable integration identifier, for example my_pos.
accountIdThe merchant or POS account identifier.
externalLocationIdThe store identifier in your POS.
locationIdThe UUID of the corresponding Mereu location.
eligiblePolicyUse paid_excluding_tips_surcharges.

This binding maps document references; it does not grant Mereu access to a POS provider account. Keep these values unchanged across key rotation.

  1. Calculate the benefit with POST /checkouts/preview. Send amounts and reward.mode: none, points or visit_reward. For points, supply a decimal string such as 10.25.
  2. Read discount and expected_paid_total from the quote. The quote lasts 120 seconds. Do not recalculate these values in your POS.
  3. Reserve the benefit with POST /checkouts, using quote_id and the stable sale reference.
  4. Send POST /checkouts/{id}/payment-started with the reservation’s expected_revision and wait for success.
  5. Only now apply the benefit and collect payment in your own POS or payment system.
  6. After verifying payment, confirm with POST /checkouts/{id}/commit. Use the revision from payment-started, the real amount equal to expected_paid_total, the payment time and its reference. Save transaction_id.

A card can have only one reservation, shared with Casa. A reservation whose payment has not started expires after 10 minutes. Read GET /checkouts/{id} to check its status.

If payment did not occur, cancellation requires the current revision and a reason. Once payment might have started, payment_not_completed:true is an explicit attestation of non-payment, never an assumption after a timeout.