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.

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.

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.

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.

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.

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.

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 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 your configured webhook.url 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: <your webhook 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). 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.