# 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

- **Amount units are not uniform across this API.** Checkout takes MAJOR units
  (`"totalAmount": 49.99`); payouts take minor units (`"amountMinor": 4999`).
  Read the field name every time. Neither surface rejects the wrong one, so a
  guess here is wrong by a factor of a hundred and nothing errors.
- **Idempotency is required on every mutation.** Send an `Idempotency-Key`
  header on every POST, PATCH and DELETE. One key covers a whole
  `/initialize-payment` + `/finalize-payment` 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.
- **`orderData.payeeDistribution` is the only way to split a payment.** There is
  no separate transfer or split endpoint to call afterwards; the split is
  declared on the payment that collects the money.
- **"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 the sandbox for test work.** `https://staging-api.fynex.ai` with the same
  paths. 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.
- **Do not pin an SDK version from memory.** Install the current release.
- **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.
- **Read failure reasons from `failureCode`, never from the message.** The
  description is prose meant for a human and is not a stable contract.

## 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.
- [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.
- [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.
- [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): Complete state-machine reference for GenericPayment and Payout — every status, what triggers it, valid transitions, and which API actions drive the flow.
- [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): Saved-card / merchant-initiated (MIT) charging — not yet available via the public payments API. Contact your Fynex representative if you need recurring billing today.
- [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 using persistent split rules or per-payment inline splits.
- [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, payout, and refund lifecycle events — registration, HMAC-SHA256 signature verification, and replay-protection.