Payments API & AI access

Connect your own tools, scripts, and AI assistants to BayWise Payments. The API lets external systems — your DMS/GMS, accounting software, or custom workflows — record financial activity and read it back, and lets AI assistants answer questions about your payments.

What the Payments API is — and when to use it

BayWise Payments is the cash-conversion layer between your operations and your accounting. Your DMS records that a job happened; your accounting software records money after it arrives. Payments tracks the bit in between: what was collected and paid, against which job, and whether the money has actually landed.

The real problem: one vehicle, many systems, many moments

The money for a single repair almost never lives in one place. The same vehicle shows up at different stages, in different systems — and sometimes across different locations — and each system describes the money in its own words, keyed its own way, updated at its own time:

Each system holds only a fragment, keyed differently (roNumber here, paymentIntent there, claimRef elsewhere), and they change at different times. No single one can answer “how much of this repair have we actually collected, and what’s still owed?” — let alone roll that up across every vehicle, every event, and every location in a group.

How the API turns the fragments into one picture

You send each fragment to the API as it happens, all against one engagement (the repair). The API resolves identity — by roNumber, vin, or your own external key — so every fragment lands on the same vehicle, and records each money movement with a direction (inflow = a collection, outflow = a payment):

1. Ingest the engagement — RO-4821 for VIN MA3…7K, invoiced 1500 (customer 500 / insurer 1000).
2. Collection in — customer pays the 500 excess by card → inflow, settled immediately.
3. Payment out — you pay the 300 sublet vendor → outflow.
4. Collection in (later) — the insurer settles by bank transfer six weeks on → inflow, settled on arrival.

Because the same money is reported by more than one system, they sometimes disagree — the processor says paid but the DMS hasn’t caught up; the insurer pays 950 against an approved 1000. When that happens the API records a reconciliation exception for a human to resolve, instead of silently picking a winner. That deliberate reconciliation is what lets the fragments be trusted as one truth.

What that gives you back

Once the fragments are recorded and reconciled, the data answers the questions no single source could:

• Vehicle ledger — read an engagement and its transactions and you have the whole money story of that repair: invoiced 1500, collected 1500 (500 customer + 1000 insurer), paid out 300, outstanding 0.
• Business ledger — the same movements rolled up across all vehicles plus non-vehicle activity (rent, salaries, vendor bills), grouped by category and period — per location, or across the whole group.
• Cashflow — the time view: 500 in today, 300 out next week, 1000 in expected in ~6 weeks — the gap between earning the money and actually being paid.

Today you assemble the vehicle ledger from an engagement plus its transactions, and the business ledger / cashflow by reading transactions across engagements (the BayWise app also presents these as built-in views). Dedicated ledger and cashflow read endpoints are on the roadmap so you won’t have to aggregate them yourself.

Use the API to:

• Mirror your jobs from your DMS so every fragment ties to the right vehicle.
• Record collections (money in) and payments (money out), with tax calculated for you.
• Collect remotely with hosted payment links — recorded automatically when the customer pays.
• Reconcile the inevitable disagreements between systems, deliberately, with a human in the loop.
• Read it back as the vehicle ledger, business ledger, and cashflow — to drive dashboards or feed accounting.
• Ask an AI assistant (Claude, Cursor, and others) about your payments — read-only.

If you only need one sentence: use this API to pull the scattered money facts about each vehicle into one place, reconcile the disagreements, and read them back as a vehicle ledger, a business ledger, and cashflow — per location or across the group.

Core concepts

Five ideas explain almost everything. (For the business background, see the in-product concept guides on Entities & transactions and the Vehicle Ledger.)

Getting a key

1. In BayWise Payments, open Settings → Developer.
2. Choose the permissions the key should have (you can only grant what your own role allows).
3. Optionally scope the key to a single location and set an expiry.
4. Click Create API key. The full key is shown once — copy and store it safely.

Who can do this: Account Owners and Org Admins (anyone with developer access). On the free plan, API access is an upgrade.

Using the API

Send your key as a bearer token (Authorization: Bearer …) to the BayWise API base URL. The full request/response details, every field, and a “try it” console are in the Payments API reference ; a ready-to-import Postman collection is linked from the Developer tab.

A few rules worth knowing up front:

• Money is exact. Amounts are whole numbers in the currency’s smallest unit (e.g. cents) with an explicit currency code — never a rounded decimal. When you record a transaction, send the amount excluding tax; tax is calculated and frozen for you.
• Retries are safe. Send an idempotency key when recording — repeating the same key never double-records.
• Sensitive actions are two-step. Voiding a transaction (or resolving a reconciliation exception) uses confirm-then-commit: a first “prepare” call returns a one-time grant plus a summary of what will happen; the real call carries that grant. Nothing changes by accident.
• Lists are paginated. Each page returns a cursor; pass it back to get the next page.
• Every response has a request id you can quote to support.

A typical flow

1. Ingest the job — record an engagement for the repair order (using your own external key, so re-sending is safe).
2. Record a collection — when the customer pays at the desk, record a transaction with direction: inflow, the amount excluding tax, and the method (cash/card/…).
3. Or send a link — create a collection link and share it; when the customer pays online, the settled collection is recorded automatically.
4. Read it back — list transactions for the engagement to show what’s collected vs outstanding.
5. Watch reconciliation — keep an eye on the reconciliation summary; if it shows open exceptions, list and resolve them.

Voiding a transaction (confirm-then-commit)

Voiding is a two-step process designed to prevent accidents. The pattern is the same for resolving a reconciliation exception.

Step 1 — Prepare (no state change, returns a one-time grant):

POST /v1/payments/transactions/{id}/void:prepare
Authorization: Bearer bw_live_…

Response — a short-lived grant:

{
  "grantId": "a1b2c3d4-…",
  "token": "eyJ…",
  "expiresAt": "2026-06-28T10:05:00Z",
  "impact": "Transaction AED 500.00 (cash, 2026-06-27) will be reversed. A new reversing entry will be recorded — the original is never deleted.",
  "requiresHeader": "X-Confirmation-Grant"
}

Step 2 — Commit (carries the grant from step 1):

POST /v1/payments/transactions/{id}/void
Authorization: Bearer bw_live_…
X-Confirmation-Grant: eyJ…          ← the token from step 1
Content-Type: application/json

{
  "grantId": "a1b2c3d4-…",          ← the grantId from step 1
  "reason": "Customer overpaid — credit note issued instead."
}

The commit requires both the X-Confirmation-Grant header (the token) and grantId in the body. The grant is single-use and short-lived — prepare and commit in one flow; don’t cache it.

Webhooks

The Payments API does not currently emit outbound webhook events. To monitor payments in real time, poll GET /v1/payments/engagements/{id} or the transaction list for an engagement. Payment-specific webhook events are on the roadmap.

For Scheduler events (job created/updated/delivered, step changes) see Webhooks.

Connecting an AI assistant (MCP)

From Settings → Developer → Connect via MCP, generate a token and copy the config into your AI client (for example, Claude Desktop → Settings → Developer → Edit Config). The assistant then acts as you and can only do what your role permits — in this version, AI access is read-only (it can answer questions about your payments, not change them).

What the AI can read via MCP:

The AI cannot record transactions, create links, or resolve exceptions — write actions require a human using the app or the REST API.

Need help?

Quote the request id from any response when contacting support. Keys can be revoked any time from the Developer tab — a revoked key stops working immediately.