# Fynex Payments API > Accept money and pay it out. Hosted checkout, server-to-server card payments, > Apple Pay and Google Pay, split payments to marketplace payees, payouts, > wallets. Every route lives under `/payments-api/v1` and authenticates with a > seller secret key. ## Instructions for coding agents - **Call `/payments-api/v1/…`, even though these docs live under `/payments-api/v2/`.** There is one contract. `/v2` serves only the documentation; an operation requested under `/v2` answers 404. - **Request amounts are MAJOR units on this API** — checkout `"totalAmount": 49.99`, payouts `"amount": "49.99"` (a decimal STRING). `amountMinor` on payouts is a deprecated fallback that `amount` overrides. Response fields ending `Minor` are integers. The one request exception is a split share: `orderData.payeeDistribution[].amountMinor` is integer minor units. Read the field name every time: a payment amount in the wrong unit is not rejected, so a guess is wrong by a factor of a hundred. - **Idempotency is required on the payment operations, not on every mutation.** `Idempotency-Key` (a UUID) is required on `/checkout`, `/initialize-payment`, `/finalize-payment`, `/capture`, `/refund` and refund cancellation. One key covers a whole initialize + finalize pair — reuse it across the two calls rather than minting a second. A new key is refused while a refund on the same payment is still pending. `/payouts` takes `idempotencyKey` in the body (the header is a fallback); the create routes for payees, payee setup, payout methods, webhooks and split rules accept it optionally — send one, because a retried setup without a key creates a second payee and bank account. Wallet and vendor routes do not read the header. - **A split is declared on the payment, never transferred afterwards.** Put `orderData.payeeDistribution` on the create request — but it only takes effect when the seller has an active split rule (`GET /split-rules/active`); with none, the payment settles unsplit. An `absolute`-mode rule draws the shares from its own lines and ignores the distribution. There is no transfer endpoint, and a refund does not unwind the split by itself — see the Splits guide, *How Fynex splits money*. - **Lost track of your payments? `GET /payments` lists them**, newest first, filterable by `status` and a `createdFrom`/`createdTo` range — you do not need to hold the ids. - **"Payee" and "seller" mean different things.** The seller is the Fynex account making the call — you. A payee is somebody that account pays out to. A marketplace operator is usually both. - **Use a test-mode key for test work.** What decides whether money is real is the ACCOUNT's mode, not the host: an `sk_test_` key is test mode wherever it is sent. `GET /account` returns the account a key acts for and its `operationalMode` (`Demo` or `Live`). - **Do not pin an SDK version from memory.** Install the current release. - **A Demo checkout can be paid without a browser.** `POST /test/checkout/{sessionId}/complete` pays the session as its buyer would, with a sandbox test card Fynex picks, so no card details pass through your code. - **A Demo payment does not settle by itself.** After it completes, call `POST /test/payments/{paymentId}/settle` — then the split runs and wallets are credited. - **The key comes from the dashboard, Integration → API keys.** `/keys` says so in one page, including what the `sk_test_` and `sk_live_` prefixes mean. You do not need to contact Fynex to get one. - **An MCP endpoint (`/mcp`) is in preview and is not enabled on every host**; where it is, it takes the `sk_test_` key of a Demo account (live keys are refused, `sandbox_only`) and one JSON-RPC message per request. Each tool is a REST route with the same arguments, body and errors; no tool takes card details. - **No webhook endpoint? Read `GET /events`.** Every event is recorded on the account, in the webhook envelope, whether or not a URL is registered. It is oldest first; store `nextCursor` and pass it back as `cursor` to get only what is new. - **Read failure reasons from `failureCode`, never from the message.** The description is prose meant for a human and is not a stable contract. - **Every error body is JSON `{"error", "code"}`, authentication failures included — branch on `code`.** A 401 is `missing_api_key` (no key sent) or `invalid_api_key` (unknown key, or a key from the other host's environment). ## Reference - [OpenAPI 3.1 document](/payments-api/v2/openapi.json) — operations, schemas and the webhook catalog; generate a client from this - [Complete reference (markdown)](/payments-api/v2/docs.md) — every guide and every endpoint in one file - [Rendered documentation](/payments-api/v2/docs) - [Agent skills](/.well-known/skills/index.json) — task-shaped entry points for splitting a payment, onboarding sellers, paying out and migrating off Stripe Connect Every guide below is also served as HTML at the same URL without the `.md` extension, and answers `Accept: text/markdown` there with this same markdown. ## Guides - [3DS Authentication](/payments-api/v2/docs/3ds.md): How to handle 3DS challenges in the server-to-server card flow — the redirect lifecycle, localStorage bridge, and finalize call. - [Apple Pay](/payments-api/v2/docs/apple-pay.md): Accept Apple Pay either server-to-server via /payments-api/v1/initialize-payment, or through the legacy hosted-checkout surface (/api/v1/checkout/apple-pay-*). - [Authentication & Tokens](/payments-api/v2/docs/authentication.md): How to obtain, use, and rotate seller bearer tokens for the Fynex Payments API. - [Captures & refunds](/payments-api/v2/docs/captures-refunds.md): Capture authorized payments and issue full or partial refunds — verified against the live codebase. - [Fynex API Changelog](/payments-api/v2/docs/changelog.md): What changed in Fynex public APIs, by month — breaking changes, new capabilities, and fixes. - [Embeddable checkout widget](/payments-api/v2/docs/checkout-widget.md): Embed the Fynex checkout form as an inline component or popup overlay for test/demo-mode checkout sessions. - [Concepts & Domain Entities](/payments-api/v2/docs/concepts.md): A glossary of the 18 core domain entities in Fynex — what each one is, where it appears in the API, and the key fields a partner needs to know. - [Disputes & chargebacks](/payments-api/v2/docs/disputes.md): Dispute and chargeback workflow — coming soon. Today, contact your Fynex representative for dispute investigation and resolution. - [Errors](/payments-api/v2/docs/errors.md): Status codes, error shapes, and how to recover from each kind of failure. - [Flow externalId](/payments-api/v2/docs/flow-external-id.md): Seller-scoped Flow externalId identity, collision, immutability, and runtime boundary contract. - [Getting started](/payments-api/v2/docs/getting-started.md): First steps with the Fynex Payments API — get your token from the dashboard, verify it, take a first test payment with either integration style, and prepare for production. - [Going live](/payments-api/v2/docs/going-live.md): Production-readiness checklist — token management, endpoint switch-over, status verification, idempotency, monitoring, PCI scope, and cutover plan. - [Google Pay](/payments-api/v2/docs/google-pay.md): Accept Google Pay through Fynex via hosted checkout, or by submitting the signed token from Google's JS SDK to /initialize-payment (Fynex decrypts) — or, if you operate your own DIRECT-mode keys, by sending the already-decrypted payload. - [GraphQL Authentication](/payments-api/v2/docs/graphql-auth.md): How to obtain a dashboard session cookie and call the /dashboard/graphql endpoint for payee CRUD, wallet queries, and token rotation. - [Request Headers](/payments-api/v2/docs/headers.md): Reference for all HTTP request headers used by the Fynex Payments API — required, conditional, and optional. - [Hosted checkout](/payments-api/v2/docs/hosted-checkout.md): Accept payments by redirecting customers to a Fynex-hosted page — the lowest-PCI path to going live. - [Idempotency & retries](/payments-api/v2/docs/idempotency.md): Safely retry mutating Fynex API calls without creating duplicates. - [Alternative payment methods (APM)](/payments-api/v2/docs/local-payment-methods.md): Accept local payment methods (Bancontact, Multibanco, MB WAY, Wero, Swish) either server-to-server via /payments-api/v1/initialize-payment with paymentType "apm", or through Fynex-hosted checkout. Most methods redirect; Multibanco can also return entity/reference instructions for inline display. - [Account setup & onboarding](/payments-api/v2/docs/onboarding.md): Walk through sign-up, company creation, and KYB so your seller account reaches operational mode live and can accept real payments. - [overview](/payments-api/v2/docs/overview.md) - [Payees](/payments-api/v2/docs/payees.md): Register and manage payees — sub-merchants, marketplace sellers, and payout recipients — via the REST CRUD endpoints and the GraphQL CRUD surface. - [Payment Lifecycle](/payments-api/v2/docs/payment-lifecycle.md): The authoritative payment-status reference — the lifecycle enum, every transition, what each status allows next, capture, cancellation, refunds, failures and webhooks. - [Payment methods & capabilities](/payments-api/v2/docs/payment-methods.md): Query which payment instruments, currencies, and rails are enabled on your seller account before building your checkout UI. - [Payout Methods](/payments-api/v2/docs/payout-methods.md): Register bank accounts and IBANs as payout destinations for your payees, then use them as targets when requesting a payout. - [Payouts](/payments-api/v2/docs/payouts.md): Send money out from a seller wallet to a registered payee's payout method. - [Polling & SSE](/payments-api/v2/docs/polling-sse.md): Track payment, payout, and refund status using polling or Server-Sent Events — a reliable way to know "what just happened", complementing the outbound PaymentCompleted webhook. - [Quickstart](/payments-api/v2/docs/quickstart.md): Take your first test payment with Fynex in 5 minutes using hosted checkout. - [Reconciliation](/payments-api/v2/docs/reconciliation.md): Verify Fynex settlement records against your own books using the GraphQL reconciliation queries. - [Recurring payments](/payments-api/v2/docs/recurring.md): How stored-credential (MIT) payments on this API relate to recurring billing — subscriptions, invoices and off-session collection — which lives on the Billing API. - [Server-to-server payments](/payments-api/v2/docs/server-to-server.md): Take full control of the payment flow when you collect card data on your own infrastructure. - [Split Rules](/payments-api/v2/docs/splits.md): Distribute incoming payment funds across multiple payees automatically with a persistent split rule, fed per payment by orderData.payeeDistribution when the rule is in weight mode. - [Test cards & sandbox](/payments-api/v2/docs/test-cards.md): Test card numbers, APM sandbox links, how to control 3DS, and how the Fynex sandbox behaves. - [Troubleshooting & FAQ](/payments-api/v2/docs/troubleshooting.md): Common errors, gotchas, and frequently asked questions for Fynex API integrators — organized by topic for quick scanning. - [Vendors](/payments-api/v2/docs/vendors.md): Onboard sub-merchants (vendors) under a platform account — create, screen, and pay marketplace vendors through the REST API. - [Verification patterns](/payments-api/v2/docs/verification-patterns.md): How to choose between polling, SSE, and webhooks for verifying payment and payout status. - [Virtual Accounts](/payments-api/v2/docs/virtual-accounts.md): Inspect dashboard virtual accounts and understand the separate virtual-account issuance preview. - [Wallets](/payments-api/v2/docs/wallets.md): Query per-currency seller balances, ledger entries, and inter-wallet transfers using the Fynex GraphQL API. - [Webhooks](/payments-api/v2/docs/webhooks.md): Outbound webhooks for payment, refund, payout, payment-link, subscription and verification lifecycle events — registration, HMAC-SHA256 signature verification, and replay-protection.