Developers. No surprises.

At a glance.

Everything a developer needs to know in one table. Detail in the sections below.

Quick start.

From signup to first webhook in under five minutes. The complete flow:

1. Apply for sandbox access at fluxapay.co.uk/#start. No card needed for sandbox access. KYB verification happens before you go live, not before you test.
2. Grab a test API key from Developers » API keys. Test keys are prefixed sk_test_; they cannot move real money.
3. Make your first request. The call below creates a checkout session for £19.99 and returns a hosted URL you can redirect a test customer to. Switch language with the tabs:

4. Pay with a test card. Use 4242 4242 4242 4242 for an immediate success, any future expiry, any three-digit CVC. The full set of test cards (decline, 3DS challenge, insufficient funds, fraud-decline) is in the testing docs.
5. Receive a webhook. Add a webhook endpoint in the dashboard, point it at a local URL via a tunnel of your choice, and you will receive the checkout.session.completed event signed with HMAC-SHA256 in the X-Fluxa-Signature header.

That is the entire happy path. There is no waitlist, no application form for the sandbox, no salesperson between you and a test transaction.

The PFaaS model.

Fluxa is a Payment Facilitation as a Service platform. That means we are not a card scheme, not an acquiring bank, and not your merchant of record. We are the technical and operational layer that sits between you and an FCA-authorised payment partner. We onboard you, hold the technical relationship with the schemes through that partner, settle funds to your nominated bank account, and provide the tooling.

Concretely, this affects you in five ways:

• One contract, one integration. You sign one merchant agreement with Fluxa. You do not need a separate acquiring agreement, a separate gateway agreement, and a separate settlement agreement. All three sit behind our single REST API.
• Faster onboarding. Verified Commercial Identity (VCI) handles KYB programmatically. Most merchants are onboarded in hours, not the weeks a direct payment partner would take.
• Transparent rate. 1.8% flat per transaction. No interchange-plus, no payment partner markup buried in a quarterly statement, no surprise fees on commercial cards (corporate-card surcharge is on the page in advance, not after the fact).
• We do not hold your money. Funds settle from the payment partner directly to your nominated bank account. Fluxa is a Referrer under PSR 2017, not an Electronic Money Institution; we are not authorised to safeguard funds and we do not.
• You are the merchant of record. Chargebacks come to you, refunds are issued by you, the customer relationship is yours. We provide the dispute tooling and represent your evidence to the payment partner.

Who handles what

Under PFaaS, four parties have distinct responsibilities. Knowing where Fluxa sits clarifies what your integration is and is not on the hook for. This matrix is the same whether the card payment is £5 or £5,000.

Two lines stand out and are worth restating. We never touch your funds: the payment partner settles directly to your nominated bank account, with a Fluxa settlement reference attached so you can match it against your bank statement. You are the merchant of record: the cardholder relationship is yours, refund policy is yours, chargebacks come to you. We provide the tooling, the data and the integration; the commercial relationship with your customer stays with you.

If you have integrated Stripe, GoCardless, Adyen or Square before, the developer experience will feel familiar: REST resources, signed webhooks, idempotency keys, test mode. The PFaaS model is what differs, and is documented in full so you can decide if it fits your stack and your compliance posture.

API design.

Predictable beats clever. Nine rules apply across every endpoint, every resource and every response. Learn them once and the rest of the API follows.

1. REST, JSON, HTTPS only

   Conventional REST. Resources are nouns, verbs are HTTP methods. JSON request and response bodies, UTF-8 throughout. TLS 1.3 only; plain HTTP is refused at the edge with no redirect.

   GET https://api.fluxapay.co.uk/v1/payments/pay_5f8b2c1e2a4b4d8c
   Authorization: Bearer sk_live_...
   Accept: application/json

2. Prefixed, predictable IDs

   Every object ID carries a short type prefix. Passing the wrong ID to the wrong endpoint surfaces an obvious error instead of a silent miss, and IDs stay readable in your logs.

   pay_   payment           rfd_   refund
   cus_   customer          sub_   subscription
   chk_   checkout session  mer_   merchant
   evt_   webhook event     dsp_   dispute
   req_   request log       err_   error code

3. Money in pence, currency in ISO 4217

   Every monetary field is an integer in the smallest currency unit. Pence for GBP, cents for EUR and USD when those launch. No floats, no rounding decisions on your side, no locale ambiguity. Currency is the three-letter ISO 4217 code.

   {
     "amount": 4999,
     "currency": "GBP",
     "fee": 99,
     "net": 4900
   }

4. Idempotency by default

   Every POST accepts an Idempotency-Key header. The same key returns the same response for 24 hours, even if the network failed on your first attempt. Retries are safe, expected, and never charged twice.

   POST /v1/payments
   Authorization: Bearer sk_live_...
   Idempotency-Key: 8d8fcb1d-7b8a-4d6c-9a13-1f7c8e9b8c5d
   Content-Type: application/json

5. Versioning by date

   Pin a version per request with Fluxa-Version. Old versions stay live for at least six months after a successor is released, with a 30-day sunset notice on the changelog before any URL retires. No silent breaking changes, ever.

   Fluxa-Version: 2026-05-19

6. Cursor pagination, never offset

   List endpoints return has_more and next_cursor. Pass limit (up to 100) and after on subsequent calls. No skipped or duplicated records when items are inserted mid-iteration, no slow OFFSET on large tables.

   GET /v1/payments?limit=50
   
   {
     "data": [...],
     "has_more": true,
     "next_cursor": "pay_5f8b2c1e2a4b4d8c"
   }

7. Expandable resources

   Inline related objects with expand[] instead of making N+1 follow-up requests. Up to three levels deep. Costs nothing extra at our end and saves a round trip at yours.

   GET /v1/payments/pay_5f8b...?expand[]=customer&expand[]=settlement
   
   {
     "id": "pay_5f8b...",
     "customer": { "id": "cus_...", "email": "..." },
     "settlement": { "id": "stl_...", "settled_at": "..." }
   }

8. HTTP status means what it should

   2xx for success, 4xx for client errors with a machine-readable code and request_id, 5xx for our problems (safe to retry with exponential backoff). Status codes are never 200 with a hidden error in the body.

   200  OK              Request succeeded
   201  Created         Resource created
   400  Bad Request     Validation failure, see error.code
   401  Unauthorised    Missing or invalid bearer token
   404  Not Found       Resource ID unknown
   409  Conflict        Idempotency-Key reused with different body
   429  Too Many        Rate limit hit, see Retry-After
   5xx  Server Error    Our fault, retry with backoff

9. Metadata on every object

   Every Fluxa resource accepts a customer-controlled metadata key-value bag, up to 50 keys, 40-character key names, 500-character values. Useful for linking Fluxa objects to your internal IDs without us needing to know your data model.

   POST /v1/payments
   {
     "amount": 4999,
     "currency": "GBP",
     "customer": "cus_3f7a91d8c2b04a6f",
     "metadata": {
       "order_id": "ord_8421",
       "campaign": "spring-2026",
       "fulfilment_centre": "london-01"
     }
   }

The payment object

Here is a complete payment object showing every field a settled card payment carries. The same shape comes back from POST /v1/payments, GET /v1/payments/{id} and the payment.* webhook events.

{
  "id": "pay_5f8b2c1e2a4b4d8c",
  "object": "payment",
  "amount": 4999,
  "currency": "GBP",
  "fee": 99,
  "net": 4900,
  "state": "SETTLED",
  "ledger_state": "SETTLED",
  "livemode": true,

  "created_at":   "2026-05-19T10:23:14.572Z",
  "captured_at":  "2026-05-19T10:23:15.103Z",
  "settling_at":  "2026-05-20T07:00:00.000Z",
  "settled_at":   "2026-05-21T07:14:32.001Z",
  "settlement_reference": "STL-2026-05-21-FX-04812",
  "settlement_method":    "bacs_credit",

  "payment_method": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year":  2028,
      "country":   "GB",
      "funding":   "credit"
    }
  },

  "three_d_secure": {
    "version": "2.2.0",
    "method":  "frictionless",
    "result":  "authenticated"
  },

  "customer":         "cus_3f7a91d8c2b04a6f",
  "checkout_session": "chk_8c9b2a14e0f74e90",

  "metadata": {
    "order_id":   "ord_8421",
    "campaign":   "spring-2026"
  },

  "url": "https://api.fluxapay.co.uk/v1/payments/pay_5f8b2c1e2a4b4d8c"
}

Refund objects, checkout sessions, customers, subscriptions and disputes follow the same shape: a typed id, an object field that names the resource, a livemode boolean, a created_at timestamp, a metadata bag and resource-specific fields. Once you have read one, you can read them all.

Authentication.

Every request to the Fluxa API authenticates with a Bearer token in the Authorization header. There are three kinds of key, scoped to where they should live:

Keys can be rotated at any time from the dashboard. Old keys remain valid for a configurable grace period (1 hour to 30 days) to allow rolling deploys. Compromised keys can be revoked instantly, with the dashboard showing every request the revoked key has made in the prior 30 days for audit.

For additional defence in depth, secret and restricted keys support optional IP allowlisting. Specify CIDR ranges in the dashboard; requests from outside the allowlist are rejected with HTTP 403 and a clear error code, never silently dropped.

Six payment states.

Most payment APIs collapse the payment lifecycle into a single status field with values like processing or pending. That hides every step between the customer’s card being charged and the money landing in your bank account. Fluxa shows all six states explicitly, every transition is timestamped, and every transition fires a webhook.

The happy path is PAYMENT_RECEIVED → CAPTURED → SETTLING → SETTLED. FAILED and REFUNDED are terminal and can be reached from earlier states. A payment object never lies about where it is: if it shows SETTLED, the funds are in your bank account with a settlement reference you can match against your bank statement.

Every payment object also carries a ledger_state field with three coarser values (CAPTURED, SETTLING, SETTLED) intended for double-entry bookkeeping integrations where the intermediate transitions are less interesting than the accounting outcome.

Webhooks.

Webhooks are the canonical way to keep your system in sync with Fluxa. Every state transition above fires one, signed and replay-protected. Polling the API is supported but webhooks are strictly preferred.

Signing

Every webhook request includes an X-Fluxa-Signature header containing a timestamp and an HMAC-SHA256 signature of the request body, separated by a comma:

X-Fluxa-Signature: t=1716135600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

To verify: concatenate the timestamp, a full stop, and the raw request body. Compute HMAC-SHA256 over that string using your webhook signing secret (visible once in the dashboard when you create the endpoint). Compare to v1 using a constant-time comparison. Reject the request if the timestamp is more than 5 minutes old; this prevents replay attacks even if a valid signature is captured.

Retries

If your endpoint returns anything other than a 2xx response within 30 seconds, Fluxa retries with exponential backoff: 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, 12 hours, 24 hours, 48 hours, 72 hours. After the final retry the event is marked as failed and surfaces in the dashboard with the full request history. Retried events carry the same id, so deduplicate on that on your side.

Event ordering

Events are not guaranteed to arrive in order. A payment.captured may arrive after a payment.settled for the same payment if a retry succeeds late. Always trust the payment object’s current state, not the event you received; events are notifications, not the source of truth.

Testing

The dashboard has a webhook replay tool: pick any past event, re-send it to any endpoint, and inspect the request and response live. Useful for debugging signature verification without waiting for a real payment.

Event catalog

Every event Fluxa fires. Names are resource.verb and stable across versions; we add new event types without breaking existing ones.

Subscribe to specific events per endpoint in the dashboard, or pass a comma-separated list to the events parameter when creating an endpoint via API. Endpoints with no filter receive every event for the account.

Reconciling settlements to your bank statement

Under PFaaS, funds settle from the payment partner directly to your bank account. There is no Fluxa settlement report to reconcile against, because Fluxa does not hold the money in the first place. You reconcile against the bank statement line itself, using the settlement_reference field that Fluxa attaches to every SETTLED payment.

A typical bank statement line for a Fluxa-acquired settlement looks like:

21/05/2026  STL-2026-05-21-FX-04812  BACS CR  4,237.45  CR
                                       Settlement, 7 transactions, FX payment partner

The reference STL-2026-05-21-FX-04812 matches the settlement_reference on every payment object in that batch. A practical reconciliation loop:

// On payment.settled webhook, save (settlement_reference, payment_id, net)
// Nightly, pull the day's bank statement and group by reference
// For each reference, sum payments → expect bank credit amount

const payments = await fluxa.payments.list({
  state: 'SETTLED',
  settled_at: { gte: yesterday },
  expand: ['settlement']
});

const byRef = groupBy(payments.data, 'settlement_reference');

for (const [ref, batch] of Object.entries(byRef)) {
  const expected = batch.reduce((sum, p) => sum + p.net, 0);
  const bankLine = await bank.findCredit({ reference: ref });
  assert(bankLine.amount === expected, `Mismatch on ${ref}`);
}

Every SETTLED payment also carries settlement_method (bacs_credit for standard UK settlement, faster_payment for accelerated batches, same_day for premium accounts). The reference itself is namespaced: STL-YYYY-MM-DD-FX-NNNNN, with FX denoting the payment partner code, the date being the settlement date (not the transaction date), and NNNNN a daily counter starting at 00001.

Worth flagging: under Stripe, GoCardless or Adyen, funds land in their account first, then transfer to yours on a schedule. Their reconciliation tools match payments to those provider-controlled settlements. Under Fluxa, that intermediate step does not exist. Your reconciliation matches payments directly to the bank statement line. This is a small architectural shift but a meaningful one for treasury and finance teams.

3D Secure and SCA.

Strong Customer Authentication has applied to UK card payments since the PSD2 SCA enforcement ramp completed in March 2022. Most online card payments require the cardholder to authenticate with two of three factors: knowledge (password, PIN), possession (phone, token) or inherence (fingerprint, face). For card payments, that authentication runs over 3D Secure.

As a PFaaS layer, Fluxa orchestrates 3DS but does not perform the authentication itself. The payment partner is the 3DS Server; the cardholder’s bank (the issuer) runs the challenge. Fluxa carries the outcome on every payment object and signals state changes via webhooks.

What Fluxa handles, what the payment partner and issuer handle

Card details are collected at the hosted (or embedded) checkout, which is served from our payment partner’s PCI-Level-1 environment. Card data never touches your servers and never touches ours. When the checkout submits a payment, the payment partner initiates the 3DS flow with the issuer; the issuer decides whether to challenge or authenticate frictionlessly. If a challenge is required, it appears inside the same checkout iframe; the cardholder never leaves.

Fluxa sits above this. We expose the result to you as a three_d_secure object on the payment, advance the state machine and fire the webhook. You never write 3DS integration code yourself.

3DS v1 and 3DS v2

Both versions are supported. The payment partner prefers 3DS v2.x (faster, more frictionless approvals, in-app challenges) and falls back to v1 for the small number of issuers that have not migrated. Soft-decline retries on v1-only issuers are automatic; you do not have to handle them.

Frictionless and challenge flows

Roughly three quarters of authentications complete frictionlessly: the issuer authenticates the cardholder from the data the payment partner passes (device fingerprint, transaction history, risk signals) without showing any prompt. The cardholder sees the checkout submit and the payment succeed.

The rest require a challenge: a one-time passcode by SMS, a banking-app push notification, or biometric approval. The challenge is shown inside the checkout iframe. When the cardholder completes it, the payment continues without a page reload.

SCA exemptions

The issuer decides whether to apply an exemption, with the payment partner signalling preferences. You do not request exemptions yourself; we pass the right indicators based on the transaction context. The five exemptions in scope under PSR 2017 Article 100 are:

• Low value. Transactions under £25 may skip SCA. A running counter at the issuer triggers SCA after five consecutive low-value exemptions or a cumulative £85.
• Transaction Risk Analysis (TRA). Low-risk transactions, judged against the payment partner’s and issuer’s fraud rate thresholds, may be exempted. Threshold tiers: under £500 if payment partner fraud rate <0.13%; under £250 if <0.06%; under £100 if <0.01%.
• Trusted beneficiary. If the cardholder has whitelisted the merchant with their issuer (a one-time SCA), subsequent payments to the same merchant can skip SCA.
• Recurring transactions. Merchant-Initiated Transactions in a subscription series are exempt after the first payment (which is fully SCA-authenticated and creates a stored credential).
• Corporate cards. Lodged commercial cards and Secure Corporate Payment (SCRT) transactions on dedicated B2B rails are out of scope.

The three_d_secure object

Every card payment object carries a three_d_secure sub-object describing the authentication outcome:

"three_d_secure": {
  "version":      "2.2.0",
  "method":       "frictionless",
  "result":       "authenticated",
  "exemption":    null,
  "eci":          "05",
  "cavv":         "AAACAWQ9...",
  "ds_trans_id":  "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
}

Possible values for method: frictionless, challenge, not_required (when an exemption applies). Possible values for result: authenticated, attempted (issuer not enrolled), not_required, failed, rejected. The exemption field names which of the five exemptions applied, or is null if a full authentication ran. The cryptogram fields (cavv, eci, ds_trans_id) are surfaced for your records; we already pass them to the payment partner with the authorisation request.

Failed authentication

If the cardholder fails the challenge or the issuer rejects the request, the payment transitions to FAILED. The payment object carries failure_code: three_d_secure_failed and failure_message with the human-readable reason. A payment.failed webhook fires. You can retry the same checkout session with a different card; failed 3DS does not count against your VAMP or dispute thresholds.

Testing

The sandbox card 4000 0000 0000 3220 always triggers a 3DS challenge, then succeeds. 4000 0000 0000 3238 triggers a challenge and fails it. 4000 0000 0000 1091 exercises a v1-only issuer fallback. Other 3DS scenarios are listed in the testing reference at docs.fluxapay.co.uk/testing/3ds.

Sandbox and testing.

The sandbox is identical to live in every API contract: same endpoints, same schemas, same webhook events, same error codes. The only difference is that no real money moves and the payment partner is in sandbox mode.

Switch by changing the key prefix. sk_test_ hits the sandbox; sk_live_ hits production. Same code, no environment flag to flip in your application.

Test cards

For any test card: use any future expiry date, any three-digit CVC, any postcode. Cardholder name is ignored in sandbox.

Simulated settlement timing

Sandbox runs at accelerated time so you can test the full state machine without waiting two days for settlement. By default, SETTLING arrives 30 seconds after CAPTURED and SETTLED arrives 30 seconds after that. You can force any delay (or skip directly to SETTLED) using the X-Fluxa-Sandbox-Timing header described in the testing docs.

Errors and rate limits.

Errors are JSON, structured, and stable. Every error has an HTTP status (meaning what it should), a machine-readable code, a human-readable message, and a request_id you can quote when contacting support.

{
  "error": {
    "type": "invalid_request",
    "code": "amount_too_small",
    "message": "Amount must be at least 30 pence for GBP transactions.",
    "param": "amount",
    "doc_url": "https://docs.fluxapay.co.uk/amount_too_small",
    "request_id": "req_5f8b2c1e2a4b4d8c"
  }
}

The complete error code list is in the errors reference. Each code has its own page with cause, example request, and the right way to handle it.

Retry strategy

4xx errors are client errors and should not be retried without changing the request. 5xx errors and network errors are safe to retry; use exponential backoff with jitter, give up after a sensible number of attempts (we suggest 5), and re-use the same Idempotency-Key so the retry is not charged twice.

Rate limits

Standard limits are 100 requests per second per secret key, with a burst allowance of 200. Webhook endpoints we send to are limited to 1 request per second per endpoint, sustained, to avoid overwhelming your infrastructure during incident replay.

Rate limit headers are included on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1716135660

When you exceed the limit, you get an HTTP 429 with code: rate_limit_exceeded and a Retry-After header in seconds. If your workload genuinely needs higher limits, email support@fluxapay.co.uk and we will lift them with no commercial uplift.

SDKs and tools.

Honest about what exists and what is on the roadmap. We will not claim a tool exists until you can npm install it.

Available now

On the roadmap

The roadmap above is published on the changelog, with dates that get firmer as we approach them.

Status, support, security.

Status

Live platform health is at /live: current state, recent incidents, scheduled maintenance, and historical uptime. Subscribe via SMS, Slack, email or webhook to get incident notifications the moment we detect them, not after they affect your transactions.

The status page covers four services independently: the public API, the merchant dashboard, the hosted checkout, and webhooks delivery. Each has its own uptime history. The target SLA for the public API is 99.99% monthly uptime, measured against a synthetic transaction running every 15 seconds.

Developer support

Three routes, in increasing order of how much detail you should send:

• Tom (in-dashboard AI chat) for quick questions while you are logged in. Tom is signed as AI in every message and hands off to a human in the support inbox when the question needs one.
• Email support@fluxapay.co.uk with the request_id from any error response. Same-day reply during UK working hours, within one working day otherwise. Tag URGENT: in the subject for incidents.
• Email support@fluxapay.co.uk for deep technical or architectural conversations. The Fluxa team routes these to the right person.

The full set of contact routes, including out-of-hours emergency, is on the contact page.

Security and compliance

The full security story is on the security page. The developer-relevant highlights:

• PCI DSS SAQ-A scope through hosted checkout. Card numbers never touch your servers; the hosted payment fields are served from our payment partner’s PCI-Level-1 environment, embedded in the checkout iframe. Your scope is SAQ-A, the simplest tier.
• TLS 1.3 only. Older TLS versions and plain HTTP are refused at the edge. HSTS is enforced with a 12-month max-age and preload.
• AES-256 at rest for every persistent store. Keys managed in a dedicated KMS, rotated automatically every 90 days.
• Encrypted webhook payloads available on request: in addition to HMAC signing, payloads can be encrypted with your public key (RSA-OAEP) so even our infrastructure cannot read them in transit.
• Vulnerability disclosure via security@fluxapay.co.uk with PGP available. Acknowledged within one working day. Bounty programme in scoping; coordinated disclosure timelines on the security page.

Fluxa is operated by Fluxa Ltd, a UK company registered in England and Wales (Companies House number 17028144). Fluxa is a UK registered trademark. Fluxa is a Referrer under the Payment Services Regulations 2017; payments are acquired by an FCA-authorised payment partner. Full regulatory and corporate detail is on the about page and the contact page.