FireBuddy Docs

Everything you need to add a Fire Open Banking payment widget to your website — from first sign-up to live checkout in under 10 minutes.

FireBuddy is a software service provider: every payment settles bank-to-bank into the merchant's own Fire account — money never touches FireBuddy.

Why build on FireBuddy

• Honest payment states. payment.authorised means the payer's bank approved — show it on their screen; payment.completed means the money landed — fulfil on it. The API never blurs the two, because settled-only truth is the house rule everything here is built on.
• Flat, predictable pricing. Merchants pay FireBuddy one monthly price with up to 500 payments included — no per-payment FireBuddy fee, so an integration's volume never changes their bill.
• Webhooks per tool. Register your own endpoint with your own API key; every event is HMAC-signed with your endpoint's secret. Several tools share one merchant without stepping on each other, and pushed events beat polling (see Webhooks).
• Your UI to the bank door. Bank deep links send the payer from your checkout straight into their own bank — no generic picker in your flow.
• No card data, no PCI. Bank payments are pushed bank-to-bank by the payer (no chargebacks). Card, Apple Pay and Google Pay go through Revolut's checkout on checkout_url pages, so no card number ever reaches FireBuddy or your system.
• Safe to retry. Invoice creation is idempotent by invoice_number, payment-request creation is guarded against doubles, and one-call /quick/invoice does the whole invoice-and-send in a single request.

Quickstart

Getting FireBuddy live on your site takes three steps:

1. Get a FireBuddy account — book a 15-minute call and we set it up with you, connected to your Fire or Revolut Business account (see Billing).
2. Create a product in your dashboard — give it a name, price, and description. You'll get a unique Product ID.
3. Paste 2 lines of code onto any webpage. The widget appears automatically, handles the Fire payment, and sends your customer a receipt.

How it works

When a customer clicks "Pay" in your widget, FireBuddy initiates a Fire Open Banking payment request. The customer is shown their bank's interface to authorise the transfer. Once authorised, the money goes directly to your Fire account and FireBuddy records the transaction.

No card details are stored. No payment processor sits in the middle. Just a direct bank-to-bank transfer, initiated via Fire's regulated Open Banking infrastructure.

Instant settlement

SEPA Instant is live on FireBuddy for euro, and Faster Payments for sterling. Funds normally reach the merchant's Fire account within seconds of the customer authorising, not on a settlement cycle. That changes how you should build against this API:

• Build webhook-first. payment.completed typically fires seconds after authorisation. Treat that event as your signal to fulfil the order — releasing goods on a nightly reconciliation job means holding a customer for hours after they've already paid.
• Don't show a multi-day "processing" state. Anything modelled on card settlement (pending → cleared over 2–3 days) will misrepresent what actually happened.
• Poll fast, but don't give up early. If you can't take webhooks, GET /payment-requests/{code} every few seconds catches the common case — a 15-minute loop adds 15 minutes of latency to a payment that already landed. Keep checking well beyond that though: a payer on a bank that hasn't switched instant on yet can arrive hours later, and abandoning the poll doesn't mean the payment failed.
• Payment-request status stops at AUTHORISED. Fire's request object doesn't advance to a "settled" state — authorisation is the point at which an instant payment is on its way. Use FireBuddy's own status field (completed) and the payment.completed webhook as the source of truth for "money has arrived".

Requirements

• An active Fire.com business account (EUR and/or GBP)
• A FireBuddy account on the monthly plan (see Billing)
• A website where you can paste HTML — any CMS or custom site works

Basic Embed

Add the following two lines to any HTML page, inside the <body> tag, wherever you want the payment widget to appear:

<!-- Load the FireBuddy widget script once per page -->
<script src="https://firebuddy.info/widget.js"></script>

<!-- Place this div wherever the widget should render -->
<div
  id="firebuddy"
  data-api-key="YOUR_API_KEY"
  data-product-id="YOUR_PRODUCT_ID"
></div>

Replace YOUR_API_KEY with the API key from your dashboard, and YOUR_PRODUCT_ID with the ID of the product you want to sell.

Attributes

The FireBuddy <div> accepts the following data attributes:

Full example with optional attributes

<div
  id="firebuddy"
  data-api-key="fb_live_abc123xyz"
  data-product-id="uuid-of-your-product"
  data-theme="dark"
  data-button-text="Book my session"
  data-redirect-url="https://yoursite.ie/thank-you"
></div>

Platform-specific instructions

WordPress

Use the Custom HTML block in the Gutenberg editor, or paste directly into a page template via Appearance → Theme Editor. The widget works in any WordPress theme.

Webflow

Add an Embed element to your page and paste the two lines of code. Make sure "Custom Code" is enabled in your Webflow project settings.

Squarespace

Use a Code Block in any section of your page. Squarespace must be on the Business plan or higher to use custom code.

Shopify

Add a Custom HTML section to any page or product template via the theme editor. Ideal for a standalone product or deposit page — not intended to replace the full cart checkout.

Plain HTML

Paste anywhere inside your <body> tag. No build step or framework required.

REST API

The FireBuddy REST API lets you create Fire Open Banking payment requests, read payment status, list payees, and read live balances + transactions from a connected Fire account — all from your own backend.

Base URL

https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api

Authentication

Every request must include your merchant API key in the Authorization header. Generate one from Dashboard → Developer. Keys are scoped to a single merchant and look like fb_live_xxxxxxxxxxxxxxxx.

Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx

Check readiness — GET /me

Call this first. Read one field: ready. When it's false, show the returned message and link action_url — don't re-derive readiness from the individual flags.

{
  "ok": true,
  "ready": false,                     // ← the single source of truth
  "status": "connect_fire",           // "ready" | "connect_fire"
  "message": "This merchant hasn't finished connecting their Fire account…",
  "action_url": "https://firebuddy.info/dashboard.html#firesetup",
  "connected_as": "Core Kids · key \"NEW PORTAL KIDS TEST\"",   // ← show this after a test
  "api_key": { "label": "NEW PORTAL KIDS TEST", "created_at": "2026-08-21T18:10:46Z", "source": "merchant_api_keys" },
  "setup": { "api_key": true, "fire_connected": false, "manual_transfer": false, "webhook": false },
  "merchant": { "business_name": "…", "default_currency": "GBP" }
}

Always display connected_as after a successful connection test. Your settings page can never show a saved API key back to the user, so that one line — business name plus the key's own label — is the only way they can confirm the app is wired to the right business with the right key. Without it, a key pasted in to test one account is indistinguishable from the live one.

ready: true → create payments/invoices. ready: false → the merchant must finish a one-time setup (almost always connecting their own Fire account). A working key (setup.api_key: true) is separate from Fire being connected — both are needed to move money.

Versioning

The API is currently at v1. We will not make breaking changes to v1 endpoints without publishing a new version under a separate path. Additive changes (new fields, new endpoints, new optional parameters) may be made to v1 at any time.

The /functions/v1 segment in the base URL is the Supabase platform version, not the FireBuddy API version.

Create a payment request

POST /payment-requests — creates a Fire Open Banking payment request and returns a hosted URL to send the customer to.

curl -X POST https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/payment-requests \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "EUR",
    "description": "Order #1234",
    "reference": "ORD-1234",
    "email": "customer@example.com",
    "tax_amount": 9.35,
    "tax_rate": 0.23
  }'

Send the customer to checkout_url — FireBuddy's checkout for this exact payment. It offers every way the merchant accepts: Revolut Pay, Apple Pay, Google Pay, card and pay by bank when they have Revolut checkout on, Fire bank payment otherwise. Whichever the customer picks, the same paymentId / code completes, and every webhook carries your reference plus provider (fire or revolut). pay_url is Fire's raw page (bank payment only) for flows that must go straight to the bank. The response also carries picker_url (always Fire's full bank picker — render it as the "Not your bank?" escape), bank_remembered (true when pay_url was deep-linked from the customer's remembered bank) and aspsp_name (that bank's display name).

Repeat customers — "⚡ Pay with their own bank"

GET /payment-methods?email=&currency= — ask before creating a request whether this customer has a remembered bank, so your checkout renders a personalised button instead of a generic one. Returns presentation facts only:

{ "currency": "EUR", "bank_remembered": true, "bank_name": "Bank of Ireland Personal" }

The recipe for an app checkout:

1. GET /payment-methods?email= → bank_remembered: true? Show "⚡ Pay with {bank_name}"; otherwise show "Pay by bank".
2. Either way, POST /payment-requests with the customer's email and open the returned checkout_url (or pay_url to go straight to the bank — deep-linked into their bank for the repeat customer, Fire's picker for the first-timer).
3. The first settled payment writes the preference automatically, so payment #2 gets the fast path with no extra work from you.
4. Always render a "Not your bank?" link using picker_url — people change banks, and business bills get paid from personal accounts.
5. Confirm on your payment.completed webhook (or GET /payments/{id}) — never on redirect params, and never fulfil on authorisation.

{
  "paymentUrl": "https://payments.fire.com/AbCdEf12",
  "code": "AbCdEf12",
  "paymentId": "5e9c…",
  "paymentLinkId": "f12a…"
}

Send customers straight to their own bank

GET /aspsps — the list of banks (ASPSPs) available for open banking, so you can skip Fire's bank-picker entirely. If your checkout already knows which bank the customer uses, asking them again is a step backwards, and every screen between "pay" and their bank costs you conversion.

curl "https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/aspsps?currency=EUR" \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx"

{
  "total": 34,
  "aspsps": [
    {
      "aspspUuid": "c4a7e1b2-9f3d-4a55-8e21-6b0d7f9c1234",
      "alias": "Bank of Ireland",
      "logoUrl": "https://.../boi.svg",
      "country": "IE",
      "currency": "EUR"
    }
  ],
  "pay_url_template": "https://payments.fire.com/{code}/aspsps/{aspspUuid}"
}

Create the payment request as normal, then build the deep link from the code it returns and the aspspUuid of the customer's bank:

https://payments.fire.com/AbCdEf12/aspsps/c4a7e1b2-9f3d-4a55-8e21-6b0d7f9c1234

Confirming a payment on your own return page

If you send customers to your own page after paying — either with returnUrl above or the Redirect URL in Fire Setup — do not treat arriving on that page as proof of payment. A customer whose bank blocks them (an Irish AIB card-reader prompt, say) can hit Cancel and still be redirected to you having paid nothing.

FireBuddy appends ?fb=<payment id> to your redirect URL. That id is an unguessable uuid for this one payment. Look it up before you show a receipt, fulfil an order, or mark anything paid:

curl "https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/payment-status?id=$FB_ID"

{
  "state": "paid",           // "paid" | "failed" | "pending"
  "source": "fire",          // "fire" = confirmed against Fire just now
  "amount": 1.23,
  "currency": "EUR",
  "reference": "ORD-1785496659222",
  "description": "Order ORD-1785496659222",
  "business_name": "Devlin Investments Ltd",
  "paid_at": "2026-07-31T11:09:05Z"
}

Get a payment by Fire code

GET /payment-requests/{code} — looks up the payment record for a given Fire payment code. Useful for polling status if you don't want to wait for the webhook. Payments settle in seconds, so poll every few seconds for the first minute rather than on a long interval — see Instant settlement.

curl https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/payment-requests/AbCdEf12 \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx"

{
  "id": "5e9c…",
  "status": "completed",
  "amount": 49.99,
  "currency": "EUR",
  "customer_email": "customer@example.com",
  "fire_payment_code": "AbCdEf12",
  "fire_ref": "ORD-1234",
  "authorised_at": "2026-04-07T12:35:02.000Z",
  "funds_confirmed_at": null,
  "in_flight": false,
  "settled": true,
  "created_at": "2026-04-07T12:34:56.000Z",
  "updated_at": "2026-04-07T12:35:14.000Z"
}

Get a payment by FireBuddy ID

GET /payments/{id} — same as the previous endpoint but keyed on the FireBuddy paymentId returned from POST /payment-requests. Returns extra fee + settlement fields, plus the same in_flight / settled pair.

Manual bank-transfer details

GET /bank-details — returns the merchant's own receiving account so you can show a "pay by bank transfer instead" fallback on your page: manual_transfer_enabled, account_holder, iban, bic (EUR) or sort_code, account_number (GBP). Only render the fallback when manual_transfer_enabled is true and the fields are present. (GET /accounts returns Fire balances — ICAN, not the payable IBAN/BIC — so use this endpoint for the transfer account.)

Invoices

Create and manage invoices via the API. You can have FireBuddy mint a Fire pay link, email the invoice for you, or just record one you send yourself.

POST /invoices — create an invoice with line items. Idempotent by invoice_number: posting the same number again returns the existing invoice with already: true instead of creating a duplicate — retries and re-run syncs are safe. Use PATCH /invoices/{id} to change one. Order-flow expiry: an invoice that mints a pay link with no due_date auto-cancels after 14 days unpaid (an abandoned checkout, not a receivable) — tune it with expires_after_days (1–365, or 0 to opt out), or set a due_date: invoices with a due date are never auto-cancelled. A customer who pays late anyway still marks it paid — settlement always wins. VAT: tax_rate is a decimal fraction (0.23 for 23%; 1 or more returns 400). Omit it and the invoice uses the client's own VAT rate if the merchant set one on the client's record, otherwise 0.

curl -X POST https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/invoices \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-1001",
    "client_name": "Jane Doe",
    "client_email": "jane@example.com",
    "currency": "EUR",
    "due_date": "2026-07-15",
    "items": [{ "description": "Consultation", "quantity": 1, "unit_price": 100 }],
    "create_payment_link": true,
    "send": true
  }'

The response includes the invoice id, invoice_url, payment_url and payment_reference. Share invoice_url (also returned as checkout_url) — the branded hosted invoice page (line items, VAT, your logo) with every way to pay the merchant accepts (Revolut Pay, Apple/Google Pay, card and pay by bank when Revolut checkout is on). payment_url is the raw Fire checkout, for embedding in your own flow. Whichever way the customer pays, invoice.paid fires; if you poll the original payment, invoice_paid: true + paid_by_payment_id tell you it was paid another way.

• POST /invoices/{id}/send — FireBuddy emails the invoice (Pay Now + QR). Optional body: to, subject, message. Defaults to to the linked client's email.
• GET /invoices — list invoices (?status&from&to&limit&offset). GET /invoices/{id} — one invoice with line items.
• PATCH /invoices/{id} — update a draft/sent invoice (status, due_date, notes).
• POST /invoices/{id}/mark-paid — record an out-of-band payment. With confirmed:true it flips the invoice to paid and fires the payment.completed + invoice.paid webhooks.
• POST /invoices/chase — re-send the reminder email for every sent-but-unpaid invoice that is overdue (or older than older_than_days). Defaults to a preview (dry_run:true) listing who would be chased; pass dry_run:false to send. Clients with no email are returned under skipped_no_email. Invoices the client has queried are never chased — they come back under needs_your_reply for you to answer. Uses the same email path as the dashboard's Send button.
• GET /receivables — risk-ranked list of everything you are owed, worst first, with the reasons attached. See below.

Who to chase first — GET /receivables

Ranking overdue invoices by age alone is wrong: a €80 invoice a week late from a reliable client is not the problem, and a €4,000 invoice from someone who has been late four times running is. GET /receivables scores every open invoice 0–100 and returns them worst first, with a plain-English reason for every point that landed.

curl https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/receivables \
  -H 'Authorization: Bearer fb_live_xxxxx'

Score components: lateness (max 40) · that client's own payment record (25) · size relative to your median invoice (20) · reminders already ignored (15). Bands: critical ≥70, high ≥50, medium ≥30, low ≥15, watch below.

Read suggested_action, not just the score. It overrides the ranking wherever a reminder would be the wrong instrument:

• verify_payment — the customer says they already paid. Chasing is paused and the invoice goes to the top of the list. Check Fire. FireBuddy will never settle an invoice on a customer's say-so — only Fire's word about that exact payment does that.
• stop_chasing — the customer asked not to be contacted, or told us we have the wrong person. Reminders stop until you say otherwise.
• on_hold — the customer promised a date. Chasing pauses until hold_until, then resumes by itself.
• needs_reply — the client raised a query. Never chased. Answer the question; replying resets the invoice and chasing resumes on its own.
• handle_personally — a client who has always paid on time is unusually late, or the amount is well above your normal. Ring them; a form email is the wrong instrument.
• human_review — the reminder budget is spent, there is no email on file, the client cancelled, or they raised difficulty paying. A person decides.
• at_risk — not late yet, but this client usually is. Fires only with at least two settled invoices of history (one late payment is an anecdote) and only inside 14 days, when a nudge is still cheap. A warning two months out is noise.
• chase — safe to send the standard reminder. paused — you silenced this invoice. wait — not due yet.

Each invoice also carries client_history (their paid count, late count and average days to pay) so the ranking can be checked rather than trusted.

Reading the replies

When a customer replies on the invoice page, FireBuddy reads it and adjusts the chase. Plain-language patterns are matched directly; anything freer is classified by Claude (your own key from Settings → Integrations, if you have added one). The result appears on the invoice as reply_intent:

And it drafts the answer

Stopping is safe but half a job. For the two intents with an obvious next move, FireBuddy writes the reply for you and leaves it in Getting paid to approve:

• They say they paid → a note asking for the date, amount and reference — the three things that let you find the lodgement in Fire. Asking for the reference is the opposite of assuming the payment happened.
• They queried it → an answer written from the invoice's own line items. Where the arithmetic is unambiguous (“billed 3, only 2 arrived”) it names the credit and the revised total.

Via the API: GET /receivables returns drafted_reply and draft_proposal; POST /invoices/{id}/reply sends it. There is no “send the draft as-is” shortcut — the caller must pass the message text, which means somebody read it.

A proposed credit is advice, not an action. FireBuddy never edits the invoice, issues a credit note, or changes what is owed. If you agree with the figure, you send a corrected invoice yourself.

The boundary: every one of those outcomes either stops the chase or flags it for a human. The classifier cannot send a message, and it cannot mark an invoice paid — “the customer says they paid” is a claim, and only money landing in your Fire account settles it. Every classification is written to your audit log with the reason and the confidence, so “why did chasing stop on that invoice?” always has an answer.

Omit invoice_number on create and FireBuddy assigns the next number in your own sequence.

Quick invoice — one call, no questions

POST /quick/invoice — the fast path. Send only what a person would say: to (a client name or email — optional), amount (what the customer pays, major units) and for (what it's for). FireBuddy resolves everything else from the merchant's account: matches the client (email exact, name fuzzy — most-recently-invoiced wins a tie), picks the next invoice number, applies the client's own VAT rate if one is set on their record, else the merchant's usual rate (explicit tax_rate wins; vat:false forces none), backs the net out so the total lands on the number given, mints the pay link, and emails it when the client has an address (send:false to stop that). Returns the created invoice plus a resolved block saying exactly what it chose.

POST /quick/invoice
{ "to": "John Devlin", "amount": 250, "for": "Brake job" }

→ { …invoice, "invoice_url": "https://firebuddy.info/invoice?r=hiebhryi",
    "resolved": { "client": "John Devlin", "client_matched": true,
                  "invoice_number": "INV-2026-0113",
                  "tax_rate": 0.23, "tax_rate_source": "your usual rate",   // or "this client's rate" / "given" / "none"
                  "emailed": true } }

Offers — one-page landing pages with a Pay button

POST /offers — creates a hosted offer page (title, headline, bullets, price, optional photo) and its payment link; returns offer_url. Requires the offer_pages feature on the account (a 403 names the flag, not a bad key). Fields: title, price (VAT-inclusive total unless price_includes_vat:false), currency, tax_rate, headline, description, bullets[], image_url (https), expires_in_days, and two availability controls:

• max_orders — order limit. The page shows “Only 3 of 10 left” and then Sold out; the checkout refuses the next buyer. Counted from Fire-confirmed sales only. 1 = one buyer, full stop.
• countdown:true — stream mode: a live countdown to the expiry on the page (server time, so a fast phone can't end it early). At zero the page says “ended” and the checkout refuses, in the same second.

Expiry, pause and limits are all enforced where the money moves, not just where the button is drawn — the page and the checkout share one answer.

Offer feed — your shop window, for machines

PUT /feed with {"slug":"devlins-garage"} publishes a public, key-less, machine-readable list of every active, purchasable offer at https://firebuddy.info/feed/<slug>: price, what's included, how many left, when it ends, the buy URL — plus a schema.org OfferCatalog/Offer JSON-LD twin so any AI assistant or search engine can read it without knowing FireBuddy. Sold-out, expired and paused offers drop off automatically; nothing appears that the checkout would refuse. Opt-in: until you set a slug the feed is 404. DELETE /feed unpublishes.

List saved payees

GET /payees — returns the merchant's saved payout destinations (IBAN/BIC for EUR, sort code/account number for GBP).

[
  {
    "id": "a9b1…",
    "name": "Acme Supplies Ltd",
    "iban": "IE12BOFI…",
    "bic": "BOFIIE2D",
    "currency": "EUR",
    "created_at": "2026-03-12T09:12:00.000Z"
  }
]

Each payee also has is_approved (approved in the merchant's Fire app — only approved payees can be paid through the API) and masked_account (last four digits, e.g. •••• 4821), so your app can show which account without holding the number.

Refunds — back to the payer's card or Revolut account

POST /payments/{id}/refund with {"amount":25.00,"reason":"Week cancelled","idempotency_key":"your-unique-id"} refunds a payment made through Revolut checkout (Revolut Pay or card) back to the payer's original method, from the merchant's own Revolut balance. {id} is the payment id or the payment-request code. Leave out amount to refund everything left. It returns 201 with refunded_amount and status (refunded once refunded in full). The same idempotency_key never refunds twice.

POST /refunds with {"idempotency_key":"…","reason":"Club cancelled","payments":[{"payment_id":"…"},{"payment_id":"…","amount":20}]} refunds up to 200 payments at once and returns a result per payment. A payment made by bank transfer can't be pulled back: it comes back not_revolut so you can refund it from the bank. Needs the account's refunds switch, which FireBuddy turns on.

Payouts — pay an approved payee

POST /payouts with {"payee_id":"…","amount":182.50,"reference":"Commission Oct","idempotency_key":"your-unique-id","metadata":{…}} creates a Fire bank-transfer batch to that payee and submits it. It returns 202 with "status":"awaiting_bank_approval": the money moves only after the merchant approves the batch in their Fire app. A key alone can never move money.

• Off by default. The key needs payouts:write, which FireBuddy switches on per key; the merchant's per-payout and daily limits must be set. Otherwise 403 with code payouts_not_enabled or caps_not_set.
• Approved payees only (409 payee_not_approved). Add the payee in FireBuddy, approve it in the Fire app, then Sync.
• idempotency_key is required. A repeat returns the original payout (200, "duplicate":true), never a second one. If Fire refuses, nothing is kept and the same key can be retried.
• Limits: 422 over_payout_cap / over_daily_cap (per key, per UTC day, per currency). 422 insufficient_funds if the Fire account is short.

GET /payouts/{id} returns awaiting_bank_approval → sent | failed (with failure_reason). sent means Fire reports the batch COMPLETE, nothing else. When that happens FireBuddy sends payout.completed or payout.failed to your webhook endpoints (payout_id, amount, currency, reference, idempotency_key, metadata, sent_at/failure_reason), signed like every other event. Webhooks are not retried — poll GET /payouts/{id} for anything still open as a backstop.

{
  "id": "5c0e…",
  "status": "awaiting_bank_approval",
  "amount": 182.5,
  "currency": "GBP",
  "payee_id": "9b2f…",
  "reference": "Commission Oct",
  "idempotency_key": "your-unique-id",
  "metadata": { "partner": "emma" },
  "created_at": "2026-11-05T10:02:11.000Z",
  "sent_at": null,
  "failure_reason": null
}

Revolut payout runs — pay many people with one draft

For merchants who pay out of Revolut Business (e.g. a monthly wages run). FireBuddy creates one Revolut payment draft holding every payment. Nothing is paid until the merchant opens Transfers → Drafts in the Revolut Business app and presses Send. FireBuddy only ever holds Revolut's READ and WRITE scopes (WRITE = payees and payment drafts) — never PAY.

GET /revolut/payees — the merchant's live Revolut payees, one entry per account: [{"id","name","masked_account","currency","account_id"}]. masked_account is the last four digits only; full account numbers are never returned. Payees are added in the Revolut Business app.

POST /payout-runs with {"title":"CK wages Oct","currency":"GBP","idempotency_key":"hq-wages-2026-10","payments":[{"counterparty_id":"…","amount":412.50,"reference":"CK wages Oct","metadata":{…}}]} (1–200 payments) returns 202 with "status":"awaiting_bank_approval", the Revolut draft_id, the total and one item per payment.

• Off by default. The key needs payouts:write, FireBuddy must switch Revolut payouts on for the merchant, Revolut must be connected with "prepare payouts", and a daily limit must be set (payouts_not_enabled, revolut_payouts_not_enabled, revolut_not_connected, revolut_read_only, caps_not_set).
• idempotency_key is required. A repeat returns the original run (200, "duplicate":true), never a second draft.
• Every payee must exist in Revolut with an account in that currency (404 counterparty_not_found, 409 counterparty_currency_mismatch, with index). Per-payment limit (when set) and daily limit across this key's runs (422 over_payout_cap / over_daily_cap); 422 insufficient_funds if the Revolut account is short.
• Each payment gets a unique reference of at most 18 characters: your text shortened to 12, a space, and a 5-character token (e.g. CK wages Oct K7Q2M). Keep it — it is what appears on the coach's statement.
• If Revolut refuses the draft: 502 revolut_refused, the run is kept as failed; retry with a new key. 502 revolut_uncertain: Revolut did not answer and a draft may exist — check Revolut first.

GET /payout-runs/{id} checks Revolut first (at most every 30 seconds; a background sweep every 10 minutes for 14 days) and returns the run with each item's status, sent_at and failure_reason. Run status: awaiting_bank_approval → sent | part_sent | failed. Each payment sends payout.completed or payout.failed once (payout_id = item id, run_id, amount, currency, reference, metadata), signed like every other event.

Live Fire balances

GET /accounts — proxies the merchant's Fire /business/v1/accounts call server-side and returns simplified balances. Amounts are in major units (the Fire response is in cents).

{
  "accounts": [
    {
      "ican": 1234567,
      "name": "Main EUR account",
      "currency": "EUR",
      "balance": 18420.55,
      "availableBalance": 18420.55,
      "status": "LIVE"
    }
  ]
}

Recent transactions

GET /transactions?ican=1234567&limit=100 — recent transactions for a given Fire account. ican defaults to the merchant's primary EUR/GBP account if omitted. limit caps at 200.

{
  "ican": 1234567,
  "transactions": [
    {
      "txnId": "fire-txn-7788",
      "date": "2026-04-07T11:02:00.000Z",
      "amount": 49.99,
      "currency": "EUR",
      "direction": "IN",
      "reference": "ORD-1234",
      "description": "Open Banking payment",
      "balance": 18420.55
    }
  ]
}

CSV exports

Three CSV endpoints stream a UTF-8 file (with BOM, so Excel opens it correctly) containing every row in the requested range. Filter with optional from and to query parameters (ISO-8601 timestamps, both inclusive, applied to created_at).

• GET /exports/payments.csv — every payment, including fee and net columns.
• GET /exports/payouts.csv — every payout with payee IBAN/BIC.
• GET /exports/invoices.csv — every invoice with subtotal, tax rate, tax amount and total.

curl -L -o payments.csv \
  "https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/exports/payments.csv?from=2026-01-01&to=2026-03-31" \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx"

VAT summary

GET /exports/vat-summary?from=…&to=… — both sides of the VAT return on the invoice basis: sales (output VAT, T1) from issued invoices and purchases (input VAT, T2) from approved supplier bills, each broken down by currency × rate, plus vat_position_by_currency (T1 − T2 per currency; positive = payable, negative = reclaim). Sales tax_rate is a fraction (0.23); purchases vat_rate_percent is a percentage (23.0). Draft and cancelled/void documents are excluded on both sides; to includes the whole of that day. On the FireBuddy company account, output VAT also includes VAT on FireBuddy credit top-ups received (credit_topups_breakdown, already in the totals). All figures are estimates from FireBuddy records — confirm with an accountant before filing.

{
  "from": "2026-01-01",
  "to": "2026-03-31",
  "breakdown": [
    { "currency": "EUR", "tax_rate": 0.23, "invoice_count": 12, "net": 4810.00, "vat": 1106.30, "gross": 5916.30 },
    { "currency": "EUR", "tax_rate": 0.13, "invoice_count": 4,  "net": 920.00,  "vat": 119.60,  "gross": 1039.60 }
  ],
  "totals_by_currency": [
    { "currency": "EUR", "net": 5730.00, "vat": 1225.90, "gross": 6955.90 }
  ]
}

Compliance bundle

GET /exports/compliance-bundle?from=…&to=… — returns a single JSON document containing every payment, payout and invoice in the requested range, ready to hand to an external auditor or archive for compliance.

{
  "generated_at": "2026-04-07T12:00:00.000Z",
  "range": { "from": "2026-01-01", "to": "2026-03-31" },
  "counts": { "payments": 142, "payouts": 18, "invoices": 16 },
  "payments": [ /* … */ ],
  "payouts":  [ /* … */ ],
  "invoices": [ /* … */ ]
}

Audit log

GET /audit-log?from=…&to=…&limit=200 — returns recent merchant-side audit log entries. Mutating API calls (creating a payment request, generating a GDPR export, etc.) write here automatically. Use GET /exports/audit-log.csv for the CSV equivalent suitable for handing to an auditor.

{
  "entries": [
    {
      "id": "9e1b…",
      "action": "payment_request.created",
      "resource_type": "payment",
      "resource_id": "be7a…",
      "actor": "api",
      "actor_ip": "203.0.113.42",
      "metadata": { "amount": 49.99, "currency": "EUR", "fire_code": "AbCdEf12" },
      "created_at": "2026-04-07T11:02:00.000Z"
    }
  ]
}

GDPR data export

GET /exports/me.json — returns a single JSON document containing every record FireBuddy holds for the authenticated merchant: settings, API key metadata (no secret material), payments, payouts, invoices, payees and the full audit log. Generating an export is itself recorded as a gdpr_export.generated audit entry.

Errors

All errors return JSON of the shape { "error": "human-readable message" } with the HTTP status below.

Webhooks

FireBuddy forwards payment events to your backend in near real-time — with instant settlement, payment.completed normally lands within seconds of the customer authorising, so this is the event to build fulfilment on (see Instant settlement). Exact timing depends on the merchant's Fire setup: where Fire notifies FireBuddy directly the event is near-instant; otherwise FireBuddy detects the settlement on a 60-second check, so allow up to ~a minute. Either way the event fires only on Fire's own confirmation of that exact payment — never on a guess. A merchant account can have multiple webhook endpoints — register one per tool. Every event is delivered to all active endpoints, each HMAC-SHA256 signed with that endpoint's own secret, so several apps can share one FireBuddy account without stepping on each other.

Register an endpoint either in Dashboard → API Keys → Webhook endpoints, or self-register from your app with its API key:

curl -X POST https://srjrxyobhfegimgqfpor.supabase.co/functions/v1/firebuddy-api/webhooks \
  -H "Authorization: Bearer fb_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.com/webhooks/firebuddy", "label": "My tool" }'

The response includes the endpoint's secret once — store it and use it to verify deliveries (you can also supply your own secret in the request, min 16 chars). Manage endpoints with GET /webhooks, PATCH /webhooks/{id} (is_active) and DELETE /webhooks/{id}.

Verifying the signature

Every webhook request includes an x-firebuddy-signature header containing a hex-encoded HMAC-SHA256 of the raw request body, computed with your merchant signing secret. Reject any request whose signature does not match.

import crypto from "node:crypto";

export function verifyFireBuddySignature(rawBody, headerSig, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  // constant-time compare to avoid timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(headerSig, "hex")
  );
}

Events & schema

Each delivery is a POST with two headers — x-firebuddy-event (the event name) and x-firebuddy-signature (the HMAC) — and a flat JSON body of the shape { event, ...data, timestamp }:

{
  "event": "invoice.paid",
  "invoice_id": "5e9c…",
  "invoice_number": "INV-1001",
  "payment_id": "a1b2…",
  "amount": 100.00,
  "currency": "EUR",
  "timestamp": "2026-07-03T12:35:14.000Z"
}

Acknowledge with 2xx within 10 seconds. Make your endpoint idempotent (key on payment_id / invoice_id) — retries can occur.

Claude connector

FireBuddy connects to Claude (claude.ai) as a connector, so you can take payments by talking: “Invoice John €250 for the brake job and send him the pay link” — Claude creates the invoice on your account, emails it with a Pay Now button, and can tell you the moment the money lands.

Connect it

1. In Claude: Settings → Connectors → Add custom connector
2. Name it FireBuddy and use the URL https://firebuddy.info/mcp — leave the OAuth fields empty
3. Click Connect — you’ll be sent to FireBuddy to log in and approve. Approving creates an API key labelled “Claude connector” on your account (Dashboard → API Keys). Revoking that key disconnects Claude instantly.

What Claude can do

The fast path: “invoice John €250 for the brake job” — one call, no questions; FireBuddy resolves the client, the invoice number, your usual VAT and whether to email it. Also: payment links · full multi-line invoices · offer pages (with order limits and a live countdown) · chase everyone who owes you (preview first, send on your say-so) · publish your offer feed · check whether a payment has landed · list invoices and transactions · live Fire balances · VAT summaries for your accountant. Claude asks your approval before money-touching actions by default — keep it that way.

Slash command: install the /firebuddy skill (ask us for the file, or find it in the FireBuddy repo under skills/) and type /firebuddy invoice John 250 for the brake job — or say it into the mic.

Try saying

• “Create a €50 payment link for a deposit on the blue BMW and give me the URL.”
• “Invoice Jane Doe €120 + VAT for a service call, due Friday, and email it to her with a pay button.”
• “Did invoice INV-2026-0112 get paid yet?”
• “What’s my EUR balance, and what were the last five payments in?”
• “Give me a VAT summary for July and August.”

Honesty rules built in

The connector carries the same guarantees as everything else here: a payment is only ever reported paid when Fire has confirmed that exact payment landed in your account — never guessed. Money settles to your own Fire account; FireBuddy never holds it. VAT figures are estimates to confirm with your accountant before filing.

Data handling

Claude’s requests are forwarded to the same REST API documented above under your own revocable key. FireBuddy stores what the API already stores — your payments, invoices and account metadata — and nothing extra for Claude. OAuth codes and tokens are held only as hashes. See the privacy policy.

WhatsApp — run FireBuddy by message

Message FireBuddy's WhatsApp number from a linked phone and get the link back in seconds. Same fast path as the Claude connector; the door merchants already have open all day.

• invoice John 250 brake job — invoice created (client matched, next number, your usual VAT, emailed if John has an address), branded link back.
• link 500 deposit on the BMW — a pay link.
• offer valet 60 first 5 ends 2 days — an offer page with an order limit and a live countdown.
• paid? INV-2026-0113 — the honest status. balance — your Fire balances.

Link a phone

The easy way: Dashboard → Settings → Integrations → WhatsApp → Add a phone. Programmatically: POST /whatsapp/link with {"phone":"+353871234567"} (or ask Claude: “link my WhatsApp +353…”) returns a 6-digit code. WhatsApp that code to FireBuddy's number from the phone being linked within 15 minutes; the number is then bound and gets its own API key labelled WhatsApp · +353… on your API Keys page — revoke it there to unlink, or DELETE /whatsapp/link. GET /whatsapp/links lists bound and pending numbers plus display_number (the number to message).

Creating Products

Each product represents something you're selling — a service, session, product, or booking slot. You can have as many products as you like.

1. Go to Products & Widgets in your dashboard
2. Click New Product and fill in the name, description, price, and icon
3. Click Embed next to any product to get the ready-to-paste code snippet

API Keys

Your API key identifies your account when the widget loads or you call the REST API. You have one active key at a time.

• Find your key on the API Keys tab (or the Overview "Connect FireBuddy" card) in your dashboard
• If you suspect your key has been leaked, regenerate it from the API Keys tab
• On the monthly plan there is no credit to run out. On an older pay-as-you-go account, running out of credit never deactivates your key — it only pauses creating new payment requests (HTTP 402) until they top up; everything else keeps working

Billing — one monthly plan

FireBuddy is a done-for-you service: €500 one-off setup, then €149 a month (plus VAT; UK businesses are quoted in sterling). Everything is included, with up to 500 payments a month and no per-payment FireBuddy fee. Billed monthly by invoice; no long contract.

• No credit, no top-ups — creating payment requests and pay links is never paused for billing reasons on the monthly plan.
• Fire and Revolut fees are theirs — each charges its own fee for a payment on the merchant's account, deducted by them. See the merchant's agreement with Fire or Revolut for those rates.

Older pay-as-you-go accounts

Some accounts opened before October 2026 are still on pay-as-you-go: a flat €0.30/£0.30 per payment, drawn from prepaid FireBuddy Credits (minimum top-up €100/£100, credit never expires). On those accounts only, when credit runs out, creating new payment requests and pay links pauses (the API returns 402 credit_exhausted); existing links keep working and settling as normal. Integrations should handle 402 by telling the merchant to top up.

FAQ

Does FireBuddy work outside Ireland?

FireBuddy uses Fire Open Banking, which is available in Ireland and the UK. Your customers must have a bank that supports Open Banking (most major Irish and UK banks do).

How much does FireBuddy cost?

€500 one-off setup, then €149 a month (plus VAT) with everything included and up to 500 payments a month — no per-payment FireBuddy fee (see Billing). Fire and Revolut charge their own fees on the merchant's account.

Can I have multiple widgets on one page?

Yes. Give each widget div a unique id attribute and a different data-product-id. The widget script handles multiple instances on the same page.

What happens if a customer's payment fails?

Open Banking payments are authorised at the bank level — the customer sees a failure message in their banking app. The widget displays an error state and the customer can try again.

Can I customise the widget's appearance?

Basic theming is available via data-theme="dark". More advanced styling options (custom colours, fonts) are on the roadmap for a future release.

I lost my API key — what do I do?

Your key is always visible in the dashboard Overview tab. If you think it's been compromised, contact hello@firebuddy.info to rotate it.