MVP Payments Client API

AJV-strict validation (additionalProperties: false — unknown fields are 400s; localInstrument is not an input: the rail is derived from currency). The pricing snapshot, certMode and the resolved brand's branding are stamped at create; a later rebrand never alters an in-flight journey.

Licence gates (LIVE credentials only). Answered before the body is read, in this order: 403 MVP-4301 (live payments not enabled for the account) → 403 MVP-4307 (the account holds its own licence, so live payments run only under the Client Licence, BYO_CERT, which is not active on it) → 403 MVP-4306 (live payments under the MVP Payments Licence, MVP_CERT, are not available yet). Sandbox credentials never meet MVP-4306 or MVP-4307.

Two-tier response, both 200. Public tier (no/invalid credentials, or another client's payment — indistinguishable): the redacted field set. Full tier (valid credentials AND owner): adds the detail fields. The debtor account is never exposed in full on the public tier.

Allowed from CREATED, BANK_SELECTED, or a retryable FAILED (CANCELLED/TECHNICAL, before expiry, retryCount < 3) — which archives the failed attempt and resets to BANK_SELECTED. Never allowed from PROCESSING, INITIATED, or non-retryable FAILED.

PISP-consent capture is the client's UX obligation on this path (recorded as consent.path: "API_ONLY").

Debtor account, per rail. A bank that mandates the debtor account before initiation is refused with 400 MVP-4007 (DEBTOR_IBAN_REQUIRED) on the IBAN rails — supply debtorIban and retry. On GBP / UK Faster Payments that code is never returned: there is no IBAN to ask a GBP payer for, so such a bank answers 400 MVP-4005 (BANK_NOT_ELIGIBLE) — supply debtorSortCode + debtorAccountNumber (here or as a create-time pre-fill) and retry, or offer another bank. Do not branch a GBP journey on MVP-4007.

Member banks (GP-18). A bank whose branches is not null is paid through one of them: send its branchId. Several offered and none sent → 400 MVP-4014 (BRANCH_REQUIRED); a branch the bank does not offer this payment, or a branchId for a bank without branches → 400 MVP-4015 (UNKNOWN_BRANCH); exactly one offered → implied when omitted. The chosen branch rides the full tier and the webhook as branchId / branchName.

The combined account-selection flow (GP-18). It is a HOSTED-page flow: the payer picks the debtor account on the platform's return page after the bank's consent. On THIS server-to-server route the attempt runs payment-first instead — at a bank whose GET /banks entry says combinedService for the payment's environment, this route still requires the debtor IBAN the entry's requiresDebtorIban names (400 MVP-4007 without it), the bank creates the payment with it as today, and no completionToken is answered here (wave 5(d) review, 2026-10-06: no hosted page exists on this path to make the pick, and a token handed to a server could not reach the payer's browser).

A PSU pre-step (Redsys hub rows, R2). At a bank that logs the payer in before the payment exists, authorisationUrl is the bank's login (its OAuth2 authorize), not the payment's SCA, and the answer carries completionToken. The payer comes back with code and state, which complete through POST /session/{mvpId}/complete-auth with no token: that call creates the payment and answers the payment's own SCA as authorisationUrl. Keep the token to read that redirect again later (X-Mvp-Completion); it is answered to no one else.

Credentials are optional on this route. Send x-api-key, x-mvp-client-id and x-mvp-client-secret together for the authenticated read — the secret's environment decides sandbox or live exactly as on every other route, and an environment sent as well must agree with it — or omit all three and send environment (sandbox | live) for the credential-free read. Either credential header alone is a 401. The credential-free response carries Access-Control-Allow-Origin: * and Cache-Control: public, max-age=60 (errors: no-store). No usage plan applies to this route: calls are not metered against an API key, and every caller — authenticated or not — shares one method throttle (429 when exceeded).

Served from the published registry artefact. Returns only banks enabled for the environment whose connector status passes the gate (SANDBOX_TESTING+ for sandbox, LIVE for live). With currency, only the banks that settle that currency — a bank on the domestic non-euro rail settles its own market's currency only (a Swedish bank for SEK, a Romanian bank for RON), so the list differs per currency even where the derived rail is the same, and a UK bank for GBP. Without currency, every eligible bank for the environment across all currencies, each carrying its rails and currencies. Eligibility and requiresDebtorIban are authoritative only for a currency-specific call: re-query with currency before building a bank picker. Bank-level per-payment caps are applied on the hosted picker and at bank selection; /v1/banks lists every eligible bank.

include=listed adds the banks the platform lists as connected but that are not enabled for payments in the environment — a bank whose production connection is documented and awaits a go-live, for example. A listed bank cannot be paid with yet: it is in no hosted picker, and selecting it is refused. The answer without include is the payable set, so read both to tell the two apart. Sandbox-only banks are never added.

Each entry carries statusCeiling — the highest status that bank reports on the success path in the environment. Read it before deciding how long to wait on a payment. health and testJourney describe the sandbox: health is reported for the sandbox environment only; null for live — and testJourney is null for live too.

Institutions and branches. The answer stays an array of rows (one row per connection), and every row carries its institution — what the payer recognises. Several rows can belong to one institution (a banking group's brands, a bank's markets) and every row of one institution carries the same institution object: group rows by institution.institutionId to show institutions first. A row that is its own institution carries its own name and logo there. A row whose branches is not null reaches several member banks over one connection and is selected with a branchId at bank selection (and may be pre-selected at create with bankId + branchId). Its branches summary counts the branches offered for the call's currency (every rail of the row without one); the list is inline (items) up to 50 branches, and above 50 searchFirst is true and items is null — GET /banks/{bankId}/branches pages and searches it.

The branches a bank offers, a page at a time — for a bank whose branches on GET /banks is not null: one connection that reaches several member banks (the savings banks of a group, the tenants of a hub). A list longer than 50 is not inlined on the bank (searchFirst: true); this call pages it and searches it by what a payer knows about their own bank: its name, its bank code or its BIC.

Credentials are optional, exactly as on GET /banks: send the three credential headers and let the secret decide the environment, or send none and name environment. The same caching and CORS apply, and the route has a method throttle of its own, equal to GET /banks (50 rps, burst 100), shared by every caller of it. A next cursor is good for the search that produced it.

The bank must be one GET /banks would answer for the environment with include=listed — payable there, or named on the public list. Any other id, and a bank with no branches, is a 404.

items is in name order. count is the number of offered branches the search matches, not the size of the page. next is the after value of the following page, and null on the last one. A branch is offered only where it serves a country the bank serves on a rail in scope: with currency, on that currency's rail.

Forwarded synchronously to the bank; never persisted, queued, or logged (request bodies are excluded from logging at the logger level). A wrong attempt returns 200 with attemptFailed: true and a decremented attemptsRemaining; at the cap the SCA fails and the payment finalises FAILED/REJECTED.

FINALISED flows into the normal poller/webhook finality convergence. Wrong OTPs decrement attempts and fail at the cap.

The public tier. A payment at a bank that runs the combined account-selection flow (GP-18, Commerzbank first) carries more keys while its attempt is open: - completion: PENDING — the bank holds a consent and no payment yet, so the return page POSTs complete-auth even on a plain ?mvpid= return; accountChoices is the pick, while one is outstanding. - completion: REDIRECT — the payment exists and waits for its own SCA; authorisationUrl is where the payer approves it (offer it again when the payer comes back WITHOUT mvpleg=payment on the return URL — the second redirect was never followed). - failureDetail: NO_ELIGIBLE_ACCOUNT — the attempt failed (CANCELLED) because the bank listed no account this payment can be paid from; offer another bank. A payment at a bank that runs a PSU pre-step (Redsys hub rows, R2: the payer logs in at the bank before the payment exists) carries completion: LOGIN until then: the login is the first redirect, and the payment is created when the page forwards the login's code to complete-auth. After a forward that failed (a 502, or the gateway's 504 while the server's leg runs on) the page may re-post the same code — on a LOGIN payment only — and stops on a 4xx. LOGIN carries no other key, with or without the header. Once complete-auth created the payment it carries completion: REDIRECT and authorisationUrl the same way as above — never PENDING. accountChoices and authorisationUrl are the payer's: they are answered only with the X-Mvp-Completion header carrying the completionToken of the attempt's bank selection. Without it, completion alone says what state the attempt is in. Every one of these keys is absent for every other payment, and on a read from the www origin.

The banks the hosted picker offers for this payment, in curated rank order — a bare array of rows. Every row carries its institution; rows of one institution carry the same object, so the picker groups rows by institution.institutionId (institution first, then its rows where it has more than one). A row whose branches is not null is paid through one of its member banks and is selected with a branchId at select-bank. Its branches summary counts only the branches offered for this payment's rail and currency (a row with none offered is not listed); the list is inline up to 50 branches, and above 50 it is search-first (searchFirst: true, items: null). A bank the platform knows will fail is not offered: one in maintenance (either environment), and — for a sandbox payment — one whose health is DOWN. GET /banks still lists both, with their health.

The twin of GET /banks/{bankId}/branches in the payment's own scope (GP-18): one page of the branches the bank offers THIS payment (its rail, currency and amount, and the country in scope), in name order, searched by name, bank code or BIC — the hosted picker's search over a list too long to inline, and its way to resolve a remembered or pre-selected branch with branchId. The bank must be one GET /session/{mvpId}/banks lists for the payment; anything else is one indistinguishable 404. Same paging as the public call: limit 1–50, after the next of the previous page of the same search.

Records PSD2 PISP consent (text version, timestamp, server-derived IP), consumer telemetry and device→bank memory. Same status guards and retry semantics as the server flavour.

Debtor account, per rail. 400 MVP-4007 (DEBTOR_IBAN_REQUIRED) is the hosted page's "ask the payer for an IBAN" signal and is returned on the IBAN rails only. On GBP / UK Faster Payments it is never returned: a UK-rail bank that mandates the debtor account answers 400 MVP-4005 (BANK_NOT_ELIGIBLE) instead, so the page offers another bank rather than opening an IBAN field that MVP-4011 would then refuse.

Member banks (GP-18). A bank whose branches is not null is paid through one of them: send its branchId. Several offered and none sent → 400 MVP-4014 (BRANCH_REQUIRED); a branch the bank does not offer this payment, or a branchId for a bank without branches → 400 MVP-4015 (UNKNOWN_BRANCH); exactly one offered → implied when omitted. The chosen branch rides the full tier and the webhook as branchId / branchName.

The combined account-selection flow (GP-18). At a bank whose picker entry says combinedService: true no IBAN is asked for: the bank creates a consent, and the answer carries completionToken. Keep it for this payment across the bank redirect and send it as the X-Mvp-Completion header on complete-auth and on the session bootstrap — the pick and the second redirect are answered to no one else.

A PSU pre-step (Redsys hub rows, R2). At a bank that logs the payer in first, authorisationUrl is the bank's login and the answer carries completionToken as above. The return's code completes through complete-auth without it, and that answer carries the payment's own SCA; the token lets the page read that redirect again on a revisit (complete-auth or the session bootstrap).

OAuth2-code standards (Revolut now, UK OB future): the bank redirects the consumer back with code+state; the return page forwards those parameters here, verbatim. The server exchanges the code and — on consent-first standards — creates the bank-side payment resource, idempotently under conditional writes. The page itself never executes the payment, and finality still converges through the normal poller/webhook path (design 04 §2, invocation path 4).

The combined account-selection flow (GP-18). The bank first asks the payer to approve a consent to read their accounts. The page posts { "params": {} } on the plain return, while the session says completion: PENDING. Every call on such a payment needs the X-Mvp-Completion header carrying the completionToken its bank selection answered — without it, or with another, 403 MVP-4308 (a settled payment's replay excepted). - When the payer must choose (several eligible accounts, or the IBAN supplied at selection is not among them), the answer carries completion: PENDING and accountChoices. The payer picks one, and the page posts { "params": { "accountRef": <the chosen ref> } }. The same {} again answers the same list, from the platform, with no new bank call. - A ref that is not one of the accounts offered is 400 MVP-4000. - Once the payment exists, the answer carries authorisationUrl: the second redirect, to the payment's own SCA — on every later call, {} included. The payment's own return URL carries mvpleg=payment: a return WITH it is the payer back from that SCA (finalise); a return without it never reached it (offer the URL). - The same pick posted again answers the same stored URL, and creates nothing; another pick once one is made is 409 MVP-4091. - A pick the bank's create fails on (502) is undone: the next {} offers the list again.

A PSU pre-step (Redsys hub rows, R2). The select answer's authorisationUrl sent the payer to log in at the bank; the bank returns code and state (the mvpId), forwarded here as above. That code creates the bank-side payment, and the answer carries authorisationUrl: the payment's own SCA, where the payer approves it — follow it. No X-Mvp-Completion is needed (the bank's single-use code is the payer's proof). Once the payment exists, a later call answers that URL again only with the header carrying the selection's completionToken; without it, the status snapshot alone. The session says completion: LOGIN for such a payment until the code created it — never completion: PENDING. - A return the server refuses — a wrong state, a wrong or stale code, no login in flight, a payment already created from another code — is 409 MVP-4091: stop re-posting. - Any other failure is 502, as is a forward that arrived while the payment's own earlier forward is still running: the same code may be re-posted (as after the gateway's 504), and is answered from the platform once that forward has landed — never exchanged twice. Every other payment's bank-side failures are 502, as before.

The first caller gets {redirectUrl} — the client's callbackUrl (or the select-bank returnUrl that overrode it) with mvpid={mvpId} appended, existing query and fragment preserved byte for byte, a client-set mvpid left untouched — and flips the one-shot gate; every repeat gets the calm "session finished" landing on www.mvp-payments.com, which carries the same ?mvpid=.

First-party device id (localStorage UUID). Clients validate the bank against the payment's rail before display.

Allowlisted event names only; heavily throttled; 202 always.

Called by banks, not clients — no API key. The connector family named by {connectorId} verifies the notification's signature and parses it; verification is fail-closed (design 00 §9 rule 10): an unknown connector, a missing/invalid signature or an unparseable event is a 401, never a write. Verified events correlate to a payment via bankPaymentId (or consentId on consent-notifying standards) and converge through the same conditional finality writers as the poller — first writer wins, pollingSource records the winner. A verified event that matches no payment is acknowledged with 202 so the bank does not retry it forever.

POSTed to the endpoint you configured for the payment's environment (your Sandbox or Live endpoint, set in your dashboard) when a payment reaches INITIATED or FAILED. Signed with your per-client RSA-2048 key: x-mvp-signature is an RS256 JWT whose claims are this payload plus iss: "mvp-payments.com", aud: <that endpoint's URL>, sub: <mvpId>, iat, exp (+5 minutes) and a unique jti (replay protection — cache accepted jtis and reject repeats). The public key is published in your dashboard and rotatable.

Acknowledge with any 2xx within 8 seconds. Failures retry 5 attempts total, spaced 30/60/120/240 s; every attempt is recorded and visible in your dashboard's delivery history. Delivery is at-least-once — process idempotently on (mvpId, x-mvp-event, status). Test events sent from your dashboard add test: true to the payload and claims and an x-mvp-test: true header — never present on a real delivery — and always carry isSandbox: true and a TEST-prefixed mvpId. Verification guide (Node/PHP/Python samples): docs "Verifying MVP Payments webhooks".

Optional per-client opt-in: the same signed delivery contract as payment.finality, sent on every public status transition (CREATED, BANK_SELECTED, PROCESSING). The payload is the payment's current snapshot at delivery time — it always agrees with GET /payments/{mvpId}. Finality itself is never duplicated through this event.