Concepts & Domain Entities

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.

Fynex's data model revolves around a small set of domain entities. Understanding these entities and their relationships is the fastest way to make sense of the REST and GraphQL surfaces.

Entities are grouped by concern. For each one you will find: a definition, where it appears in the API (REST endpoint, GraphQL query/mutation, or internal-only), and the key fields a partner needs.

Account & configuration

These entities define who you are in Fynex and how payments are routed.

SellerAccount

A seller's top-level commercial profile in Fynex. One account owns the API bearer token, one or more wallets, terminals, and split rules.

API surface: GraphQL query sellerAccount(id) / sellerAccounts. Token is rotated via regenerateSellerAccountToken(merchantId: ID!). Not directly accessible via REST — the bearer token implicitly identifies the account on every request.

Key fields: - authorizationToken — the bearer token used on all Authorization: Bearer REST calls - operationalMode — demo or live; governs which provider environment receives payments - id (int) — required for GraphQL mutations that target a specific account

Terminal

A processor-bound acceptance point — for example, a specific upstream-processor MID. Each terminal is tied to one PaymentPartner, a currency, and a set of allowed instruments. The routing engine selects a terminal for each payment.

API surface: GraphQL queries terminal(id) / terminals. Internal-only for configuration; partners do not reference terminals directly in REST requests.

Key fields: - paymentPartner — the upstream PSP this terminal belongs to - currencyCode — currency this terminal accepts - paymentMethods — instrument types (card, google_pay, apple_pay, bank_account)

PaymentPartner

The upstream payment service provider (PSP) routing the request. Partners do not interact with PaymentPartner directly; it surfaces in response fields like providerCode on payment responses.

API surface: GraphQL query (backoffice/internal). The value appears in REST responses as the providerCode string — treat its concrete values as platform-managed; check the actual response for the resolved provider.

PaymentConfiguration

The seller-level allowed payment methods, currencies, and rails. Determines what GET /payment-methods returns. Configuration is managed by Fynex on your behalf during onboarding.

API surface: GraphQL queries paymentConfiguration(id) / paymentConfigurations. The effective values are surfaced via GET /payments-api/v1/payment-methods.

Key fields: - allowedPaymentMethods — instrument types enabled for this seller - allowedCurrencies — supported ISO-4217 currency codes - allowedPaymentRails — card, bank_transfer, apm

Money in

These entities represent inbound payment flows.

GenericPayment

The canonical payment object across all providers. Created by POST /initialize-payment (or internally when a hosted checkout session is submitted). Carries the full payment lifecycle, from pending to captured, refunded, failed or cancelled.

API surface: REST — created via POST /initialize-payment, acted on by POST /capture and POST /refund. GraphQL queries genericPayment(id) / genericPayments(...).

Key fields: - externalOrderRef — your order reference; returned as paymentId in REST responses and used as the path parameter for capture/refund - lifecycleStatus — the status to branch on; status and the deprecated legacyStatus carry the previous values until the switch. See Payment Lifecycle - amount — in major units via REST responses; stored in minor units internally - captureMode — auto or manual; accepted, but capture is decided by autoSettlement (see Captures & refunds) - requiresAction / actionUrl — set when a 3DS redirect is needed (see 3DS Authentication) - failureCode / failureDescription — populated when lifecycleStatus is failed - threeDs — 3DS authentication result object (version, ECI, CAVV, liability shift)

CheckoutSession

The database row created when you call POST /checkout to start a hosted checkout. It is backed by a pending GenericPayment (previous status value draft). The session carries the sessionId (UUID) used in all subsequent browser-side checkout routes (/checkout/{session_id}/*).

API surface: REST — created via POST /payments-api/v1/checkout; subsequent browser-side routes (/checkout/{session_id}/initialize, /checkout/{session_id}/finalize, /checkout/{session_id}/poll, /checkout/{session_id}/events) are consumed by the hosted page, not directly by partners. Not exposed via GraphQL queries.

Key fields: - sessionId — UUID returned on checkout creation; embed in the checkoutUrl - checkoutUrl — the URL to redirect the customer to - returnUrls.success / returnUrls.failure — where the hosted page redirects after completion

Note

CheckoutSession is internal-only on the GraphQL surface. Use the REST response from POST /checkout to obtain the sessionId and checkoutUrl.

BillingDetails

The customer-side billing identity attached to a payment — name, email, phone, and address. Passed as billingDetails in POST /initialize-payment and stored on GenericPayment.

API surface: Nested field in REST request and response bodies; also surfaced as a sub-type in GraphQL GenericPayment.

Key fields: - firstName, lastName, email, phone - addressLine1, city, postalCode, countryCode - Aliases accepted on input: street = addressLine1, zip = postalCode, country = countryCode - postalCode (or zip) is at most 10 characters after trimming; a longer value is rejected with 400 naming the field that was sent: billingDetails.postalCode must be at most 10 characters, or billingDetails.zip must be at most 10 characters when only zip was sent. Not checked on paymentType: apm requests, which never send a postcode

SavedCard

A card stored on Fynex, linked to a SellerCustomer, that the Billing API's off-session collection charges against. Created only by the hosted checkout flow when the buyer ticks save card and gives an e-mail, on a successful payment with a billing address.

API surface: Internal — no public endpoint lists or charges it. There is no "charge saved card by reference" call on this API: the subscription block on /initialize-payment only flags the processor-side stored-credential relationship and does not create a SavedCard. Off-session charging happens through Billing invoices — see Recurring payments.

SellerCustomer

A repeat customer under a specific seller, shared with the Billing API: its id is the sellerCustomerId that Billing contracts, subscriptions and invoices refer to. Matched by e-mail; carries the seller's own merchantCustomerId as a reference and owns the customer's SavedCards.

API surface: Created by the hosted checkout flow on the same event as a SavedCard — the buyer ticks save card, gives an e-mail, and the payment succeeds — or by POST /billing-api/v1/customers (resolve-or-create by e-mail). Referenced on /initialize-payment via the merchantCustomerId field.

Key fields: - sellerCustomerRef — the merchantCustomerId you passed on /initialize-payment - sellerAccountId — the owning seller

Money out

These entities represent outbound payment flows to payees.

Payout

A wallet-to-payee transfer requested by the seller. Sent via the banking provider. Each payout debits a specific wallet and credits a specific PayoutMethod.

API surface: REST — POST /payments-api/v1/payouts (create), GET /payouts (list), GET /payouts/{id} (get), POST /payouts/{id}/cancel, and POST /payees/{payee_id}/payouts to pay a payee directly. GraphQL queries payout(id) / payouts(...).

Key fields: - amount — decimal string in major units ("49.99"), preferred; amountMinor (4999) is a deprecated fallback that amount overrides. Responses carry both. - currencyCode - walletId — source wallet - payoutMethodId — destination bank account - description — the text the beneficiary sees on their bank statement (1–140 SEPA-safe characters); optional today, will become required - idempotencyKey — in the request body; the Idempotency-Key header is an optional fallback used only when the body field is empty - status — pending, dispatching, processing, completed, failed, cancelled, plus manual_reconciliation when an operator has to resolve the row; approvalStatus (awaiting_approval / approved / rejected / compliance_review) is separate and set when the seller's approval threshold applies — compliance_review means the payout is waiting on a screening verdict, not on a human approver

PayoutMethod

A registered bank-account destination for a payee — IBAN, sort code/account number, or other bank-transfer credentials. A payee can have multiple payout methods.

API surface: REST — GET/POST /payments-api/v1/payees/{payee_id}/payout-methods, PATCH/DELETE …/payout-methods/{method_id}, and the seller's own methods at /payments-api/v1/payout-methods. GraphQL queries payoutMethod(id) / payoutMethods(payeeId, ...) and mutations createPayoutMethod, updatePayoutMethod, deletePayoutMethod remain for dashboard sessions.

Key fields: - payeeId — the owning payee - currency — supported currency for this method - status — active or inactive; only active methods appear in REST listing

Payee

A counterparty under a seller — a sub-merchant, marketplace seller, or any recipient of split funds or payouts. Each payee has a role and can have multiple PayoutMethod records.

API surface: REST — GET/POST /payments-api/v1/payees, GET/PATCH/DELETE /payees/{payee_id}, and POST /payees/setup to create a payee, payout method and wallet in one call. GraphQL queries payee(id) / payees and mutations createPayee, updatePayee, deletePayee remain for dashboard sessions.

Key fields: - displayName — human-readable label - role — Itself (the seller itself), Contractor, Tax, or fynex_platform - status — Active or Disabled

VirtualAccount

A customer pay-in IBAN issued via the virtual-account provider. Customers can be given a dedicated IBAN to send funds directly into the seller's account without a card payment.

API surface: GraphQL queries virtualAccount(id) / virtualAccounts(first, after, type).

Key fields: - iban — the virtual IBAN assigned to this account - currency — account currency - type — virtual account type

Balances

These entities represent the seller's internal ledger.

Wallet

A per-seller, per-currency balance ledger. Settlement of card payments credits the relevant wallet. Payouts debit from it.

API surface: REST — GET/POST /payments-api/v1/wallets, GET /wallets/{wallet_id}, GET /wallets/{wallet_id}/transactions, POST /wallets/{wallet_id}/fund. GraphQL queries wallet(id) / wallets(...) and mutations createWallet, updateWallet remain for dashboard sessions.

Key fields: - currencyCode — one wallet per currency - balance — current available balance - sellerAccountId

Wallet balance, credit balance and customer balance. A wallet balance is money a seller owns and is paid out from (wallets). A credit balance is stored value a buyer holds and spends instead of cash; it lives in the credit ledger, anchored either on a billing contract (the merchant's customer) or on a platform consumer (the coupon wallet). A customer balance is that credit balance for one consumer. The two stored-value systems never hold the same money: credit becomes wallet money only when an order it funded settles to the seller.

WalletEntry

An append-only ledger entry on a wallet — every credit or debit is recorded as an immutable entry. Used for reconciliation.

API surface: GraphQL (nested within Wallet).

Key fields: - amount — signed; positive = credit, negative = debit - type — entry type (settlement, payout, fee, etc.) - referenceId — links back to the originating GenericPayment or Payout

WalletTransfer

An inter-wallet movement — for example, when a split execution moves funds from the seller wallet to a payee wallet.

API surface: GraphQL (nested within Wallet).

Key fields: - fromWalletId / toWalletId - amount - referenceType — indicates the source (split execution, manual transfer, etc.)

Splits

These entities distribute payment proceeds across multiple payees. What a split does with the money — rounding, fees, over-allocation, the remainder, holds, refunds and chargebacks — is described in one place: Split Rules, section How Fynex splits money.

SplitRule

A per-seller rule that distributes a settled payment's proceeds across one or more payees. Each rule has one or more SplitRuleLine entries.

API surface: REST — GET/POST /payments-api/v1/split-rules, GET /split-rules/active, POST /split-rules/calculate (see Splits). GraphQL queries splitRule(id) / splitRules(...) and mutations createSplitRule, updateSplitRule, deleteSplitRule remain for dashboard sessions.

Key fields: - name — descriptive name for this rule - sellerAccountId - lines — list of SplitRuleLine

SplitRuleLine

One line within a SplitRule — specifies a payee and their share (by amount or percentage).

API surface: Nested within SplitRule in GraphQL.

Key fields: - payeeId — recipient - amount or percentage — the payee's share - currencyCode

SplitExecution

A historical record of a split rule being applied to a specific settled payment. Created automatically when a payment's settlementStatus reaches deposit_confirmed and a matching split rule exists.

API surface: REST — GET /payments-api/v1/payments/{payment_id}/split and GET /payments/{paymentId}/split-decisions. GraphQL query splitExecutions(dateFrom, dateTo, sellerAccountId) remains for dashboard sessions.

Key fields: - splitRuleId — the rule that was applied - genericPaymentId — the payment that triggered the execution - executedAt - lines — actual amounts distributed per payee

See also

• Quickstart — Take your first payment in 5 minutes.
• Payment Lifecycle — All GenericPayment and Payout statuses and transitions.
• Payouts — Create and track wallet-to-payee payouts.
• Hosted Checkout — Use the hosted checkout page to accept payments without handling card data.