API manual for engineering teams

Get a key in seconds at paybacker.co.uk/for-business. Free tier (1,000 calls/month) is self-serve. Growth (£499/month, 10k calls) and Enterprise (£1,999/month, 100k calls) go via Stripe Checkout — your key is emailed within seconds of payment success.

Each key starts with pbk_ and is shown once at provisioning time. Treat it like any other API credential — push it to your secret manager (1Password, AWS Secrets Manager, Vault, Doppler) immediately and never check it into git.

Lost a key? Sign in to your customer portal with your work email and click Re-issue — this revokes the old key and shows the new plaintext once.

Pass the key as a Bearer token on every request:

Authorization: Bearer pbk_<prefix>_<secret>

Anything else returns 401 Unauthorized. Revoked, expired or rate-limited keys are also rejected at this layer — see §7.

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

Send a JSON body describing a UK consumer dispute. Receive a structured response with the cited statute, entitlement, draft letter excerpt, escalation path, and a confidence score. Typical latency: 2–4 seconds end-to-end.

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

{
  "scenario": string,            // required, ≥10 chars — describe the dispute in plain English
  "context"?: object,            // optional — pass {merchant, dates, refs, ...}
  "jurisdiction"?: "UK",         // optional, only "UK" is supported in v1
  "desired_outcome"?: string,    // optional — what the consumer wants
  "amount"?: number,             // optional — disputed amount in GBP
  "consumer_name"?: string       // optional — populates the draft letter
}

The richer the scenario, the better the citation. Name the merchant, the product, the date, what went wrong, and any prior contact.

{
  "statute": string,                    // primary cited authority
  "dispute_type": "energy" | "broadband" | "finance" | "travel" | "rail"
                | "insurance" | "council_tax" | "parking" | "hmrc"
                | "dvla" | "nhs" | "gym" | "debt" | "general",
  "regulator": string | null,           // e.g. "Ofgem", "FCA / FOS"
  "entitlement": {
    "summary": string,
    "rationale": string,
    "additional_rights": string[],
    "estimated_success": "low" | "medium" | "high"
  },
  "customer_facing_response": string,   // paste-ready paragraph for your agent
  "agent_talking_points": string[],     // bullets your agent should hit
  "claim_value_estimate": { "min": number, "max": number, "currency": "GBP" } | null,
  "time_sensitivity": "high" | "medium" | "low",
  "draft_letter_excerpt": string,
  "escalation_path": [
    { "step": number, "to": string, "wait_days"?: number, "url"?: string }
  ],
  "legal_references": string[],
  "confidence": number
}

Shape is stable across statute domains — a UK261 cancellation and a Section 75 chargeback populate the same fields. Parse one schema, route on dispute_type, score on entitlement.estimated_success, render customer_facing_response verbatim in your agent UI, expose claim_value_estimate in self-serve flows.

Most B2B integrations don’t use draft_letter_excerpt.It’s a starting point your team can edit into your tone of voice — useful for self-serve dispute portals and for first-line agents who want a base to work from. CX-assist and triage workflows typically only consume the structured fields.

Flight cancellation (UK261)

curl -X POST https://paybacker.co.uk/api/v1/disputes \
  -H "Authorization: Bearer pbk_xxx_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "Ryanair cancelled my flight LGW-DUB six hours before departure with no replacement and is refusing compensation. The flight was 1,500km.",
    "amount": 350,
    "desired_outcome": "EU261 compensation plus full refund"
  }'

Returns: statute = "Regulation (EC) No 261/2004", draft letter to Ryanair Customer Relations, escalation → carrier → CAA → ADR.

Section 75 chargeback (CCA 1974)

{
  "scenario": "Customer paid £600 for a sofa on credit card via Acme Furniture, sofa arrived damaged, merchant refuses repair or refund.",
  "amount": 600,
  "desired_outcome": "Full refund via Section 75 claim"
}

Broadband (Ofcom General Conditions)

{
  "scenario": "Sky broadband speeds 60% below the minimum guaranteed in the contract for 3 weeks despite multiple support tickets.",
  "desired_outcome": "Penalty-free exit + service credit"
}

Energy (Ofgem SLC)

{
  "scenario": "British Gas back-billed customer £840 for usage 3 years ago in clear breach of the 12-month back-billing limit.",
  "amount": 840,
  "desired_outcome": "Bill cancelled per back-billing rules"
}

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.

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. Surface customer_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%.

Self-serve dispute portal

Embed in your authenticated customer area. User describes the issue, your front-end POSTs to /v1/disputes, you render entitlement.summary + claim_value_estimate + escalation_path. Offer the draft_letter_excerpt as a download.

Refund / claims triage queue

Score every inbound ticket on entitlement.estimated_success. Auto-approve high, fast-track medium, escalate low for human judgement. Cuts ops backlog without touching customer-facing copy.

Statute-grounded chatbot

Wrap your LLM in this API. Inject legal_references + entitlement.rationale as grounding context for every consumer-rights question. Eliminates hallucinated UK statute citations regardless of base model.

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. Latency is LLM-bound — parallelise aggressively up to your tier’s cap.

• Request bodies are not stored. We log endpoint, status, latency and (optionally) a coarse scenario_kind for debugging — never the scenario text or PII.
• Citations are pulled 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.
• The draft letter is a starting point. It is not legal advice and should be reviewed by your team or counsel before sending. Paybacker is not a regulated legal service.
• Jurisdiction in v1 is UK only. Calls with jurisdiction set to anything else return 400.

Email hello@paybacker.co.uk with your key prefix (the 8 hex chars after pbk_) and a request ID. Founder-level response within one working day while the API is in pilot.