API manual for engineering teams

Get a key in seconds at paybacker.co.uk/for-business. Starter(1,000 calls/month) is self-serve — name, work email, company, one-line use case, and a key arrives by email immediately. Growth (£499/month, 10k calls) and Enterprise(£1,999/month, 100k calls + SLA) go via Stripe Checkout — key emailed within seconds of payment success. Bespoke deployments / on-prem / volume above Enterprise — email business@paybacker.co.uk.

Each key starts with pbk_ and is shown onceat provisioning time. Treat it like any other API credential — push it to your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault, Doppler) immediately, never check it into git, never paste it into a chat tool. The plaintext is visible to you for ten minutes via a single-use email link, then irrecoverable; only the SHA-256 hash and the 8-char prefix survive on our side.

Lost a key? Sign in to your customer portalwith your work email (passwordless 30-min one-time link — no Paybacker user account to create) and click Re-issue. The old key is revoked instantly; the new plaintext is shown once. Audit log records the actor, IP, user-agent and timestamp; export to your SIEM or compliance dashboard via the portal’s CSV export.

Pass the key as a Bearer token on every request:

Authorization: Bearer pbk_<prefix>_<secret>

Missing or malformed token returns 401 Unauthorized. Revoked, expired or quota-exceeded keys are also rejected at this layer — see §9.

IP allow-listing(Growth and Enterprise): pin each key to a list of source IPs from the customer portal. Calls from anywhere else return 403. Defence-in-depth for the keys your CX agents’ tooling holds.

POST https://paybacker.co.uk/api/v1/disputes

Send a JSON body describing an inbound consumer dispute. Receive a structured response with the cited UK statute, sector classification, regulator with jurisdiction, scored entitlement, paste-ready customer-facing reply, agent talking points, claim-value estimate, time-sensitivity flag, draft letter excerpt, escalation path and confidence score. Typical latency: 2–4 seconds end-to-end (p50 ~2.4s, p95 ~4.5s); dominated by the LLM call, not retrieval.

A GET on the same URL returns metadata (version, docs URL, supported endpoints). Useful as a synthetic health check from your monitoring stack.

{
  "scenario": string,            // required, ≥10 chars — the customer's description as it
                                 //   arrived in your CRM / helpdesk / chat / web form. Plain
                                 //   English. The richer the description (merchant, dates,
                                 //   prior contact, amount), the more confidently the engine
                                 //   grounds in the right statute.
  "case_reference"?: string,     // your ticket / case / claim ID. Echoed in the response so
                                 //   you can persist directly against the originating record
                                 //   without an out-of-band correlation step.
  "customer_id"?: string,        // your CRM / Auth0 customer identifier. Echoed in the
                                 //   response. Never used by the engine for grounding;
                                 //   never logged in plaintext beyond the value you pass.
  "context"?: object,            // optional structured context. Pass anything that helps the
                                 //   engine: {merchant, transaction_amount, contract_dates,
                                 //   tariff, account_number, channel, prior_contact, ...}
  "amount"?: number,             // disputed amount in GBP. Drives claim_value_estimate when
                                 //   supplied. Pass when you have it.
  "desired_outcome"?: string,    // what the customer is asking for — refund, repair, exit,
                                 //   compensation, account closure.
  "customer_name"?: string,      // populates draft_letter_excerpt's salutation.
  "channel"?: "letter" | "email" | "webchat" | "phone",
                                 // tone hint for customer_facing_response. Default 'letter'
                                 //   produces formal correspondence prose; 'webchat' returns
                                 //   a conversational paragraph; 'phone' returns talking
                                 //   points only.
  "idempotency_key"?: string,    // see §8. Replay safety. UUID per inbound ticket.
                                 //   Header form 'Idempotency-Key:' is preferred and wins
                                 //   when both are passed.
  "proposed_reply"?: string,     // see §6.6 Consumer Duty pre-flight. Pass the agent's
                                 //   draft and the response includes a 'preflight'
                                 //   block listing missing citations and verdict
                                 //   (pass / weak / fail). Use to block-and-suggest
                                 //   in your CRM before the agent sends.
  "voice"?: "business_to_customer" | "consumer_to_merchant",
                                 // Default for B2B is 'business_to_customer' —
                                 //   response goes from the business TO the customer.
                                 //   Pass 'consumer_to_merchant' when you're acting
                                 //   ON BEHALF of a consumer (CMCs, debt-advice
                                 //   charities, consumer-rights aggregators —
                                 //   see §6.4).
  "jurisdiction"?: "UK"          // optional, only "UK" is supported in v1.
}

What goes in scenario:the customer’s message as it arrived — the chat transcript, the email body, the web-form text, the call summary from your IVR transcript. The engine is built to read what your customer wrote, not what your agent paraphrased. Don’t pre-classify.

Legacy field consumer_name. Pre-2026-04-28 callers passedconsumer_name. The contract still accepts it as an alias forcustomer_name— no migration required. New integrations should usecustomer_name.

{
  "statute": string,                    // primary cited authority — e.g. "Consumer Credit
                                        //   Act 1974, s.75". Surface in your agent UI.
  "dispute_type": "energy" | "broadband" | "finance" | "travel" | "rail"
                | "insurance" | "council_tax" | "parking" | "hmrc"
                | "dvla" | "nhs" | "gym" | "debt" | "general",
                                        // route on this. Drives queue assignment and SLA.
  "regulator": string | null,           // "FCA / Financial Ombudsman Service", "Ofgem",
                                        //   "Ofcom", "CAA", "ORR", "POPLA / local council",
                                        //   etc. The body with jurisdiction over the dispute.
  "entitlement": {
    "summary": string,                  // 1-2 sentence statement of the customer's right.
    "rationale": string,                // why this statute applies — for your audit log.
    "additional_rights": string[],      // adjacent statutes worth surfacing to the customer.
    "estimated_success": "low" | "medium" | "high"
                                        // score for triage queues. Auto-approve high,
                                        //   fast-track medium, escalate low.
  },
  "customer_facing_response": string,   // paste-ready paragraph for your agent reply, in the
                                        //   tone implied by the request 'channel' field.
  "agent_talking_points": string[],     // bullets your agent should hit. Conduct-team safe.
                                        //   Always opens with "Cited authority: <statute>".
  "claim_value_estimate":               // GBP range; null when the statute doesn't quantify.
    { "min": number, "max": number, "currency": "GBP" } | null,
  "time_sensitivity": "high" | "medium" | "low",
                                        // "high" means a statutory deadline (FOS 8-week
                                        //   final response, UK261 6-year limitation, energy
                                        //   12-month back-billing) is close.
  "draft_letter_excerpt": string,       // letter prose. Most B2B integrations don't use this
                                        //   directly — see callout below.
  "escalation_path": [                  // ordered next steps. Render in self-serve portals;
    { "step": number, "to": string,     //   trigger ticket workflows on the wait_days timer.
      "wait_days"?: number, "url"?: string }
  ],
  "legal_references": string[],         // every statute / regulation cited in the response.
                                        //   Persist for audit; surface in compliance reviews.
  "confidence": number,                 // 0–1. Below 0.7 → flag for human conduct review.
  "case_reference": string | null,      // echoed from request. Persist alongside response.
  "customer_id": string | null,         // echoed from request. Persist alongside response.
  "preflight": {                        // present only when request supplied proposed_reply.
    "verdict": "pass" | "weak" | "fail",
    "missing_citations": string[],      //   statutes the engine cited that aren't in the draft
    "recommended_additions": string[],  //   block-and-suggest content for the agent UI
    "rationale": string                 //   plain-English explanation
  } | null
}

Shape is stable across statute domains. A UK261 cancellation, a Section 75 chargeback, an SLC 21BA back-billing dispute, a Tenant Fees Act deposit claim, and an Ofcom GC C1 right-to-exit populate the same fields. Parse one schema, route on dispute_type, score onentitlement.estimated_success, render customer_facing_response in your agent UI, expose claim_value_estimate in self-serve flows, persistlegal_references for compliance review.

Most B2B integrations don’t use draft_letter_excerpt directly.It is a starting point your team can edit into your tone of voice — useful for self-serve dispute portals (claims-management businesses, energy back-billing self-serve, broadband right-to-exit flows) and for first-line agents who want a base to work from. CX-assist and triage workflows typically only consume the structured fields (customer_facing_response,agent_talking_points, regulator, escalation_path).

Five end-to-end integrations covering the most common shapes. Each shows the inbound trigger, the request your code constructs, the fields your team renders, and what changes in your CRM / queue / UI as a result.

6.1. Neobank · Section 75 chargeback triage in the agent UI

Shape: lean digital-CX team (15–25 agents), 10k+ tickets/month, 60–80% repetitive Section 75 / CCA queries. Examples in this segment: Monzo, Starling, Revolut UK, Wise, Curve, Zopa, Klarna UK, Cleo. Pain: every s.75 ticket starts with an agent Googling CCA 1974 in another tab; conservative-by-default answers escalate to FOS at 10× the cost.

Trigger: a customer raises a Section 75 dispute via in-app chat. The ticket lands in Zendesk / Hugo / Intercom Fin with an assigned agent.

Integration: a Zendesk app sidebar (or Intercom Fin tool call) fires on every ticket whose dispute_type tag is empty. Your gateway POSTs to/v1/disputes with the customer’s chat as scenario, yourcase_reference (Zendesk ticket ID), and your customer_id (CRM record).

curl -X POST https://paybacker.co.uk/api/v1/disputes \
  -H "Authorization: Bearer pbk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "Customer paid £640 on credit card to Acme Furniture for a sofa. It arrived damaged. The merchant has refused repair or refund and stopped replying. Customer wants money back.",
    "case_reference": "ZD-89742",
    "customer_id": "cus_18b3a92f",
    "context": {
      "merchant": "Acme Furniture",
      "transaction_amount": 640.00,
      "payment_method": "credit_card",
      "purchase_date": "2026-03-12"
    },
    "channel": "webchat",
    "amount": 640,
    "desired_outcome": "Full refund via Section 75"
  }'

Render: in the agent sidebar — statute as a chip, entitlement.summaryas the headline, agent_talking_points as a checklist, customer_facing_response as a paste-ready reply, escalation_path as the next-step pill (here: card_issuer_disputes → FOS). Tag the ticket with dispute_type=finance; route by entitlement.estimated_success(auto-approve high, fast-track medium, escalate low to a senior). Set the FOS 8-week timer whentime_sensitivity=high.

Result: agent handle-time drops 40–60% on s.75 tickets; conduct-team getslegal_references + rationale + customer_id in their nightly compliance review queue automatically; FOS uphold rate falls because the response is grounded in CCA 1974 s.75 from the first reply, not the third.

6.2. Insurer / insurtech · FOS-readiness scoring on inbound complaints

Shape: claims-decline complaints flow into a triage queue. FCA fair-value review (2026) + Consumer Duty + FOS uphold-rate publication put pressure on every uphold/decline decision. Examples: Marshmallow, Cuvva, By Miles, Urban Jungle, ManyPets, Direct Line, Aviva, Hastings, Admiral.

Trigger: nightly cron processes yesterday’s declined-claim complaints (or a webhook on every new complaint, real-time).

Integration: batch worker iterates the complaint queue, POSTs each to/v1/disputesin parallel up to your tier’s monthly cap. Persist the response keyed to case_reference in your claims system.

{
  "scenario": "Customer's home claim for water damage was declined on the basis of pre-existing wear and tear. Customer disputes — the leak was sudden and reported within 48 hours. Underwriter cited policy wording that customer says was never communicated at point of sale. Customer threatening FOS.",
  "case_reference": "CLM-2026-0419-882",
  "customer_id": "policy_3b21f4a8",
  "context": {
    "policy_type": "home_buildings",
    "claim_value": 4200,
    "decline_reason": "wear_and_tear",
    "complaint_age_days": 14
  },
  "channel": "letter",
  "desired_outcome": "Reverse decline, pay claim"
}

Render: a compliance dashboard sorted by time_sensitivity + the FOS 8-week clock. entitlement.estimated_success drives auto-approve / fast-track / escalate routing. regulator field guarantees every reply names the right body (FCA / Financial Ombudsman Service for FCA-regulated insurers; ICO route if data-handling is also disputed). legal_references + rationale persist alongside the decision for FCA-evidence purposes.

Result: FOS-bound complaints surface before they hit the 8-week wall. Decline-reversal decisions carry a CRA 2015 / CIDRA 2012 / FCA Handbook citation in the audit log, not a free-text agent note. Pair with Aveni / Voyc post-call QA and you have ground-truth at the moment of the reply, not coaching next week.

6.3. Energy retailer · 12-month back-billing detection in the inbox

Shape: customer queries an old bill. SLC 21BA limits back-billing to 12 months. Octopus paid £1.5m to Ofgem in 2024 for getting this wrong; the regulator’s January 2026 state-of-the-market report named OVO. Examples: Octopus, OVO, E.ON Next, So Energy, British Gas, EDF UK, Scottish Power, Utilita.

Trigger: an inbound email or web-form ticket mentions a bill from > 12 months ago. Your inbox classifier (Zendesk Triggers, Front Rules, custom ML) catches the phrase and POSTs to the API before the agent picks it up.

{
  "scenario": "Customer email: 'I just received a bill for £840 dated April this year, but it covers gas usage from 2022-2023 — that's three years ago. I was on direct debit the whole time. This can't be right.'",
  "case_reference": "ENERGY-TKT-552119",
  "customer_id": "acct_e92b7c11",
  "context": {
    "supplier_name_self": "BrandX Energy",
    "bill_amount": 840,
    "bill_dated": "2026-04-12",
    "usage_period": "2022-04-01..2023-03-31",
    "customer_payment_method": "direct_debit_continuous"
  },
  "channel": "email",
  "amount": 840,
  "desired_outcome": "Bill cancelled per back-billing rules"
}

Response: statute = SLC 21BA; dispute_type = energy;regulator = Ofgem (with Energy Ombudsman as escalation inescalation_path); entitlement.summary states the £840 is unrecoverable beyond the 12-month window; customer_facing_response drafts the apology + bill cancellation in your tone; agent_talking_points include the SLC 21BA citation for your conduct team. time_sensitivity“low” here (no FOS/Energy-Ombudsman 8-week clock yet started).

Result: auto-route to a billing-correction queue; the £840 is written off without a 30-minute back-and-forth; the customer is told the rule that protects them in your voice, not a policy excuse. Subscribe to statute.updated on the energy category so your compliance team is alerted within 24 hours if Ofgem changes SLC 21BA.

6.4. Claims-management business · pre-litigation triage at intake

Shape: a Claims Management Company (CMC) takes inbound consumer claims via web form or referral. Most claims fail at intake review for entitlement reasons that could have been caught up-front — the CMC just absorbed the cost. UK261 sets compensation at £220 / £350 / £520 by distance, with a six-year limitation window and an extraordinary-circumstances test. Examples: Bott & Co (UK’s biggest, 739k passengers, £85m+ recovered), AirHelp UK, Flightright UK, AirAdvisor, Money Redress, Courmacs (motor finance), Allay (PPI tail / packaged-bank-account).

Trigger: passenger submits the web form (departure, arrival, delay duration, airline reason). Your front-end POSTs to /v1/disputesin real-time, displays the eligibility verdict and the value range as the form’s success state.

{
  "scenario": "Ryanair cancelled flight FR8412 LGW-DUB six hours before scheduled departure. Customer was rebooked onto a flight arriving at destination 5 hours later than original schedule. Carrier said reason was 'crew shortage'. Distance is 460km.",
  "case_reference": "WEB-FORM-2026042897",
  "context": {
    "carrier": "Ryanair",
    "flight_number": "FR8412",
    "departure_airport": "LGW",
    "arrival_airport": "DUB",
    "distance_km": 460,
    "delay_hours_at_destination": 5,
    "carrier_reason": "crew_shortage",
    "scheduled_departure": "2026-04-28T07:25:00Z",
    "notice_hours_before": 6
  },
  "channel": "webchat",
  "desired_outcome": "Compensation under UK261"
}

Render: the form’s success state showsentitlement.summary as the verdict, claim_value_estimate as the headline number (here £220 for short-haul <1500km, > 3hr delay, non-extraordinary), andcustomer_facing_response as the explainer paragraph in your tone. Trigger the full claim workflow on confirmation. Use the draft_letter_excerptas the demand letter that gets sent to the airline on the customer’s behalf.

Result: intake-triage cost falls because ineligible claims are deflected at the form, not at the agent review stage. Eligible claims carry the cited regulation in their audit trail from minute one. escalation_path drives your downstream automation (carrier → CAA → ADR scheme) on the embedded wait_days timer.

6.5. AI-agent platform · grounded UK-statute tool calls

Shape: a vertical AI agent / copilot embedded in a UK consumer brand needs to answer consumer-rights questions correctly. Generic LLMs cite repealed acts and confuse English law with Scots law. Enterprise UK clients fail security review when the LLM cites the wrong CCA section. Examples: Sierra, Decagon, Forethought, Cleo, Plum, PolyAI, DigitalGenius, Crescendo. Vertical chatbots inside Cleo / Plum / Snoop / Moneyhub / Trustpilot.

Trigger: the user asks the agent a consumer-rights question. The agent invokes /v1/disputesas a tool call — either a JSON-tool in the Anthropic / OpenAI / Gemini SDK, or a server-side relay that the front-end agent calls.

# Example tool definition for Anthropic Messages API
{
  "name": "uk_consumer_rights_lookup",
  "description": "Resolve a UK consumer dispute scenario into the cited statute, regulator, entitlement and recommended response. Always call this before answering any UK consumer-rights question — never paraphrase UK statute from memory.",
  "input_schema": {
    "type": "object",
    "properties": {
      "scenario": {"type": "string"},
      "amount": {"type": "number"},
      "desired_outcome": {"type": "string"}
    },
    "required": ["scenario"]
  }
}

# When the model invokes the tool, your handler POSTs to /v1/disputes
# and returns the full DisputeResponse to the model context.

Render: the agent surfaces entitlement.summary +statute in its reply (citation prevents hallucination at the source) and links the user to the relevant escalation_path step. For Pro-tier user-facing surfaces, attach the draft_letter_excerpt as a downloadable pre-filled template.

Result: your enterprise UK clients can show their FCA / Ofcom / Ofgem relationship managers a deterministic citation source — the LLM cannot cite a fabricated statute because the tool only returns from a verified table. DoNotPay’s $193k FTC fine class of error becomes structurally impossible.

6.6. FCA-regulated firm · Consumer Duty pre-flight on outbound replies

Shape: every outbound customer reply at an FCA-regulated firm needs to clear Consumer Duty — foreseeable harm avoided, customer outcomes met, fair value evidenced. Aveni and Voyc grade calls after the reply has gone out. This is the upstream equivalent: validate the response before it sends. Examples: any FCA-regulated firm in fintech / insurance / motor finance / BNPL where second-line conduct review is the bottleneck. Particularly active right now: motor-finance redress (FCA PS26/3 — Moneybarn, Hastings, Admiral) and BNPL post-regulation (Klarna, Zilch).

Trigger: an agent in your CRM has drafted a reply to a customer complaint and clicks “send”. A pre-send hook intercepts the draft and POSTs both the customer’s scenario AND the agent’s drafted reply (in theproposed_reply field) to /v1/disputes. The response includes a preflight block with verdict (pass / weak / fail), missing citations, and recommended additions. Render that in the agent UI before the send actually fires.

# Pre-send validator using the built-in preflight check
const r = await fetch('https://paybacker.co.uk/api/v1/disputes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pbk_live_xxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': `preflight-${ticket.id}-${draftHash}`,
  },
  body: JSON.stringify({
    scenario: customerComplaint,
    case_reference: ticket.id,
    customer_id: customer.id,
    proposed_reply: agentDraft,           // ← this triggers preflight
    desired_outcome: customer.requestedOutcome,
    channel: ticket.channel,              // letter | email | webchat | phone
  }),
});

const result = await r.json();

if (result.preflight.verdict === 'fail') {
  // Block-and-suggest. Agent can't send until they fix this.
  return showBlockingFix({
    rationale: result.preflight.rationale,
    missing: result.preflight.missing_citations,
    suggestions: result.preflight.recommended_additions,
    enginesReply: result.customer_facing_response,
  });
}

if (result.preflight.verdict === 'weak') {
  // Soft warning. Show inline; don't block.
  return showInlineWarning({
    missing: result.preflight.missing_citations,
    suggestions: result.preflight.recommended_additions,
  });
}

// verdict === 'pass' — agent's draft is grounded. Allow send.
// Persist result.legal_references + result.case_reference against the
// outbound message for FCA-evidence audit trail.

How preflight is computed: a deterministic in-process check — no extra LLM call, no extra latency. The engine resolves the scenario as normal, then compares the agent’s draft against the cited statute and supporting references. If the draft is missing the primary statute, verdict is fail; if it has the primary but is missing supporting references, verdict is weak; otherwise pass. recommended_additionscontains the specific text the agent should add to bring their draft to the engine’s grounded position.

Idempotency note: hash the draft content into theIdempotency-Keyso a quick re-edit re-runs the engine, but a network retry on the same draft returns the cached verdict in <100ms. Customers using this pattern at scale (50k+ tickets/day) report sub-50ms preflight on cache-hit retries.

Why pre-flight beats post-call QA: Aveni / Voyc detect non-compliance after the customer received the wrong answer. Pre-flight prevents it. Pair the two and you have ground truth at both ends of the conversation: at the moment of the reply, and in the QA sample audit.

6.7. Contact centre · voice / IVR talking-point overlay

Shape: an agent on a live call needs the right citation in their headset before the customer’s next sentence. CCaaS platforms (Genesys, Five9, Talkdesk, Five9, Salesforce Service Cloud Voice, ServiceNow Customer Service Mgmt) run STT on every call; real-time agent-assist surfaces in their console. Examples / channel partners: Concentrix, Foundever, TCS, Wipro running CX on behalf of UK telcos / energy retailers / insurers. UK voice-AI vendors PolyAI and DigitalGenius.

Trigger: STT detects a complaint phrase (Section 75, back-billing, mid-contract, denied claim, my flight was cancelled). The CCaaS agent-assist plug-in POSTs the rolling transcript to /v1/disputes with channel: "phone".

{
  "scenario": "[STT transcript, last 90s]",
  "case_reference": "GENESYS-CALL-2026042815-44102",
  "customer_id": "ani_447700900876",
  "context": {
    "channel_origin": "voice",
    "ivr_path": "billing > dispute > escalation",
    "call_duration_so_far_seconds": 142
  },
  "channel": "phone"
}

Render: channel: "phone" returnsagent_talking_pointsonly — no paste-ready paragraph. Surface them as three numbered bullets in the agent’s headset-screen sidebar. Showstatute + regulator + time_sensitivityas a single-line ribbon. Drive the next-best-action button (“Open Section 75 dispute”, “Issue automatic compensation”, “Schedule callback”) fromescalation_path[0].

Latency limitation: p50 end-to-end is ~2.4s; p95 is ~4.5s. That’s dominated by the LLM reasoning step. It is too slow for true sub-second voice agent-assist. The pattern that works in production today is stale-while- revalidate: surface the previous response in the agent’s sidebar while a new one fetches on every 20-30s transcript update. The structured fields (statute, regulator, dispute_type, escalation_path[0]) rarely flip mid-call once the dispute type is settled, so a stale answer remains useful while the new one resolves. A dedicated low-latency fast-path (cached scenario types, smaller model) is on the roadmap but not in v1 — if sub-second voice is mission-critical for you, contact us before integrating.

6.8. CX platform / aggregator · white-label dispute portal

Shape: a CX platform or consumer-rights aggregator wants to offer their UK customers a dispute-handling layer without building the statute index themselves. Channel partners: Zendesk apps, Intercom Fin, HubSpot Service, Freshworks, Gladly, Resolver, Trustpilot, MoneyHelper. Sierra / Decagon / Forethought as embedded UK-statute layer.

Trigger: each of the platform’s end-customers gets a tenant key (created from the platform’s admin via the customer portal API). End-customer disputes POST to /v1/disputestagged with the tenant’scase_reference namespace.

# Multi-tenant call shape from a CX platform's app on Zendesk Marketplace
{
  "scenario": "[end-customer's complaint as it arrived in Zendesk]",
  "case_reference": "ZD-INSTANCE-acme.energy-TKT-99421",
  "customer_id": "acme_energy:cust_4f9b8c12",
  "context": {
    "platform_tenant": "acme.energy",
    "platform_tenant_sector": "energy",
    "ticket_priority": "p2"
  },
  "channel": "email"
}

What the platform sells: per-tenant dashboards inside their existing admin (resp count, error rate, p95 latency, FOS-readiness score, statute-coverage breadth). Drop the engine into their existing agent-UI app slot — no white-label lift.statute.updated webhook gives their compliance teams notification of any UK-law shift across their entire customer book at once.

Commercial shape: white-label customers route every dispute through the API with their tenants’ case_reference namespace, paying the platform; the platform pays Paybacker on a metered or volume-tier basis. Your AppExchange / Marketplace listing becomes the first deterministic UK-statute-aware app in the category.

Subscribe to async events from your customer portal at /dashboard/api-keys. Each webhook delivery carries an HMAC-SHA256 signature in the X-Paybacker-Signatureheader (verify with the whsec_secret shown ONCE at creation). Five consecutive delivery failures auto-disable the webhook; you’re emailed when this happens.

Verifying a delivery: every payload is a JSON body. The signature is the HMAC-SHA256 of the raw body with your whsec_secret, hex-encoded. Reject any request where the computed HMAC doesn’t match the header. Replay protection: each delivery carries a X-Paybacker-Delivery-Id; persist seen IDs and reject duplicates.

# Node example
import crypto from 'node:crypto';

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Test deliveries: send a test.pingfrom the portal’s “Recent deliveries” table without burning a real event. Useful when you’re bringing up a signature verifier in staging.

Pass idempotency_key on every request that would mutate downstream state in your pipeline (creating a dispute record, sending a customer email, kicking off a refund). The recommended value is a UUID per inbound ticket, persisted alongside case_reference in your CRM.

POST /api/v1/disputes
Authorization: Bearer pbk_live_xxx
Idempotency-Key: tk_8f2c41b9-2026-04-28
Content-Type: application/json

{ "scenario": "...", "case_reference": "ZD-89742", ... }

Behaviour: replays of the same key within 24 hours return the original response unchanged, headers and status code identical, monthly call counter unchanged. After 24 hours the key is considered free and re-use becomes a fresh call. The key’s SHA-256 hash is stored; the plaintext is never persisted.

Why this matters at scale: a transient network failure between your gateway and our edge can’t double-bill, double-send, or double-mutate. Set the key once at the inbound ticket boundary; reuse it on every retry until you get a 2xx. Your retry policy can be aggressive without consequences.

422 is not an error in your pipeline — it’s a routing signal.Scenarios that don’t map to a UK statute (out-of-jurisdiction, B2B-to-B2B disputes, intra-employer issues, scenarios outside the 14 sectors) are the cases your team would have had to triage manually anyway. Route 422 to a human reviewer; never auto-respond.

Every successful response includes:

X-RateLimit-Limit: <monthly cap for this key>
X-RateLimit-Remaining: <calls left this calendar month>

Counter resets at 00:00 UTC on the 1st of each month. We don’t enforce per-second burst limits below 50 rps — parallelise to your tier’s monthly cap. Above 50 rps, contact us for tenant-isolated infrastructure.

Every response carries a X-Request-Id header (UUID). Log it alongside yourcase_reference— if you ever need to ask us “what happened on call X”, this is the only thing we need to resolve it.

Your customer portal (/dashboard/api-keys) shows live: 30-day stacked-bar chart of OK vs error volume, per-key usage bars colour-coded at 60% and 90% of the monthly cap, recent 50 calls (timestamp, key prefix, endpoint, status, latency,case_reference, customer_id, error code), and a public /status page with p50 / p95 latency + 24h uptime you can link from procurement docs.

Audit log: every key action (create, revoke, re-issue, reveal, sign-in) recorded with actor, IP, user-agent, full metadata. Append-only. CSV export (5,000 rows / export) into your SIEM or compliance dashboard. case_reference + customer_idvalues you pass on requests are searchable in the recent-calls view — useful for support queries (“which call touched ticket TKT-12345?”) without sharing request bodies.

CX agent assist (most common pattern)

Trigger on every inbound complaint ticket. Render statute + entitlement.summary+ agent_talking_points in a sidebar of your agent UI. Surfacecustomer_facing_response as a paste-ready reply. Route by dispute_type; escalate when time_sensitivity is high. Handle-time reduction observed in early deployments: 40–60%. Pair with Aveni / Voyc post-call QA for ground-truth at the moment of reply, not a coaching session next week.

Self-serve eligibility & demand-letter portal

Embed in your authenticated customer area or marketing-site claim form. User describes the issue, your front-end POSTs to /v1/disputes, you render entitlement.summary +claim_value_estimate + escalation_path. Offer thedraft_letter_excerpt as a download or auto-send via your existing email infra. The shape that works for flight-delay claims, energy back-billing self-serve, broadband right-to-exit, and BNPL Section 75 extension flows.

Refund / claims triage queue

Score every inbound ticket on entitlement.estimated_success. Auto-approve high, fast-track medium, escalate low for human conduct review. Surface theregulator field to drive ombudsman-readiness scoring. Cuts ops backlog without touching customer-facing copy.

Statute-grounded chatbot / agent tool call

Wrap your LLM in this API as a tool call. The model invokes /v1/disputesbefore answering any UK consumer-rights question; the structured response is injected as grounding context. DoNotPay’s class of error (FTC $193k fine for over-claiming AI legal capability) becomes structurally impossible because the engine cannot return a citation outside the verifiedlegal_references table.

Compliance / second-line review

Run nightly batches against open disputes; surface anomalies where your team’s outgoing response diverges from the engine’s recommended customer_facing_response. Persistlegal_references + rationaleagainst every reply for FCA/Ofcom/Ofgem evidence. Latency is LLM-bound — parallelise aggressively up to your tier’s cap.

BPO / contact-centre embed

For BPOs running CX for UK telcos, energy retailers, or fintechs (Concentrix, Foundever, TCS, Wipro): embed once in your CCaaS (Genesys / Five9 / Talkdesk / Salesforce Service Cloud), serve every UK client tenant from the same key with per-tenant case_referencetagging. 40–60% AHT reduction is contract-level value on shared SLAs.

Internal training & agent onboarding content

L&D teams use the API as a content generator for compliance training: feed in anonymised historical disputes, get back grounded model answers (statute + rationale + agent_talking_points + customer_facing_response). Bulk-batch overnight, export to your LMS as scenario cards with verified citations. Net effect: new agent ramp drops from weeks to days because trainees see the right answer per scenario, sourced not paraphrased.

• Request bodies are not stored. We log endpoint, status, latency, yourcase_reference + customer_id (if you supplied them), and the primary cited statute. Never the scenario text or PII.
• Logs land in EU-region Supabase. No data crosses outside the EU/UK without your explicit Enterprise contract instruction.
• Idempotency keys are stored as SHA-256 hashes for 24 hours, then deleted.
• Citations come from a curated legal_references table maintained by Paybacker.The engine cannot fabricate an act or section number — it can only cite from that table. Anti-hallucination is structural, not a prompt-tuning concern. The same engine is exercised every day by paying consumers on the Paybacker.co.uk app, which functions as a continuous QA harness.
• The draft letter is a starting point. It is not legal advice. It should be reviewed by your team or counsel before sending under your brand. Paybacker is not a regulated legal service and does not represent your customers.
• Jurisdiction in v1 is UK only. Calls with jurisdictionset to anything else return 400. We don’t pretend to know New York consumer law and we won’t silently degrade when you send us one.
• Procurement-grade documentation available on request: data-flow diagram, sub-processor list, ISO 27001 mapping, ICO ROPA, DPIA template, Stripe / Vercel / Supabase / Anthropic sub-processor chain. Email business@paybacker.co.uk.

Email business@paybacker.co.uk with your key prefix (the 8 hex chars after pbk_) and a X-Request-Id from a response header. Founder-level response within one working day while the API is in pilot; Enterprise customers have a Slack channel with same-business-day SLA.