# Concepts & Domain Entities 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(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` --- ## 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 `draft` through to `settled` or `failed`. **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 - `status` — see [Payment Lifecycle](https://api.fynex.ai/payments-api/v2/docs#tag/payment-lifecycle) for all values - `amount` — in major units via REST responses; stored in minor units internally - `captureMode` — `auto` or `manual` - `requiresAction` / `actionUrl` — set when a 3DS redirect is needed (see [3DS Authentication](https://api.fynex.ai/payments-api/v2/docs#tag/3ds)) - `failureCode` / `failureDescription` — populated when status 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 `draft` `GenericPayment`. 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` --- ### SavedCard A tokenized card, optionally linked to a `SellerCustomer`, for use in merchant-initiated (MIT) or recurring payments. Created automatically by the hosted checkout flow when the customer opts in to saving their card. **API surface:** Internal — referenced in recurring payment flows. The token itself is held by the upstream card processor; Fynex stores only an opaque reference. Partners trigger saved-card payments by passing a `merchantCustomerId` on `/initialize-payment` with `subscription.enabled: true`. --- ### SellerCustomer A repeat customer under a specific seller, used for recurring billing. Linked to a `SavedCard` and identified by the seller's own `merchantCustomerId`. **API surface:** Internal — created automatically when a hosted checkout saves a card. Referenced on `/initialize-payment` via `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). GraphQL queries `payout(id)` / `payouts(...)`. **Key fields:** - `amountMinor` — amount in minor units (e.g. `4999` for £49.99); note this differs from payment endpoints which use major units - `currencyCode` - `walletId` — source wallet - `payoutMethodId` — destination bank account - `idempotencyKey` — passed in the **request body** (not the `Idempotency-Key` header; the header is still required) - `status` — `pending`, `processing`, `completed`, `failed`, `cancelled` --- ### 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 /payments-api/v1/payees/{payee_id}/payout-methods`. GraphQL queries `payoutMethod(id)` / `payoutMethods(payeeId, ...)` and mutations `createPayoutMethod`, `updatePayoutMethod`, `deletePayoutMethod`. **Key fields:** - `payeeId` — the owning payee - `currency` — supported currency for this method - `status` — `Active` or `Disabled`; 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 /payments-api/v1/payees` (list). GraphQL queries `payee(id)` / `payees` and mutations `createPayee`, `updatePayee`, `deletePayee`. **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:** GraphQL queries `wallet(id)` / `wallets(...)` and mutations `createWallet`, `updateWallet`. **Key fields:** - `currencyCode` — one wallet per currency - `balance` — current available balance - `sellerAccountId` --- ### 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. ### 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:** GraphQL queries `splitRule(id)` / `splitRules(...)` and mutations `createSplitRule`, `updateSplitRule`, `deleteSplitRule`. **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 reaches `settled` and a matching split rule exists. **API surface:** GraphQL query `splitExecutions(dateFrom, dateTo, sellerAccountId)`. **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](https://api.fynex.ai/payments-api/v2/docs#tag/quickstart)** — Take your first payment in 5 minutes. - **[Payment Lifecycle](https://api.fynex.ai/payments-api/v2/docs#tag/payment-lifecycle)** — All GenericPayment and Payout statuses and transitions. - **[Payouts](https://api.fynex.ai/payments-api/v2/docs#tag/payouts)** — Create and track wallet-to-payee payouts. - **[Hosted Checkout](https://api.fynex.ai/payments-api/v2/docs#tag/hosted-checkout)** — Use the hosted checkout page to accept payments without handling card data.