Payouts

Send money out from a seller wallet to a registered payee's payout method.

A payout moves money from one of your seller wallets to a payee's registered bank account. Payouts settle asynchronously through the banking provider using the route selected from the payout currency and destination identifiers.

Important

Supported routes are EUR IBAN → SEPA, GBP UK local account → Faster Payments, and GBP/USD IBAN → cross-border transfer. UK local methods must use currency: GBP, bankAccountType: uk_local, bankCountry: GB, an 8-digit account number, and a 6-digit sort code. US-local and SWIFT payout methods can be registered but are rejected before funds are held.

Note

Amount: decimal preferred. Send the decimal amount as a string (e.g. "19.99") — the same convention as the rest of the API. The legacy integer amountMinor (e.g. 1999) is still accepted as a fallback for older integrations; when both are sent, amount wins. Exactly one is required.

Note

Idempotency precedence: body over header. POST /payouts reads idempotencyKey from the request body; the Idempotency-Key HTTP header is used as a fallback when the body field is empty. When both are set, the body value wins.

Quick path: onboard and pay a new payee

Starting from scratch? The convenience endpoints collapse the full flow into a short, self-contained sequence using a dedicated cashout_balance wallet — funded directly from your balance, isolated from split earnings. The same supported bank routes and Bearer auth apply as for the primitive payout flow.

Important

This flow provisions a cashout_balance wallet, so on a Live account it is gated per seller by walletCreationEnabled (off by default). If it is not enabled for your account, POST /payees/setup returns 403 wallet creation is not enabled for this account; contact support. Contact support to enable it. A Demo account needs no switch: wallet creation is always on there. GET /account reports the effective value as features.walletCreation.

1. Create the payee, its payout method, and a cashout wallet — POST /payees/setup (one atomic call):

curl -sS -X POST "$FYNEX_API/payees/setup" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Supplies Ltd",
    "role": "contractor",
    "payoutMethod": { "currency": "EUR", "iban": "DE89370400440532013000" }
  }'

Response (201 Created) returns all three records — keep payee.id, payoutMethod.id, and cashoutWallet.id:

{
  "payee": { "id": 101, "role": "Contractor" },
  "payoutMethod": { "id": 501, "status": "active" },
  "cashoutWallet": { "id": 139, "type": "cashout_balance", "currency": "EUR", "status": "active" }
}

2. Fund the cashout wallet from your main balance — POST /wallets/{cashout_wallet_id}/fund (internal, same-currency):

curl -sS -X POST "$FYNEX_API/wallets/139/fund" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "12.50", "idempotencyKey": "'$(uuidgen)'" }'

Moves funds from your seller main wallet (same currency) into the payee's cashout wallet. Your main wallet must hold sufficient EUR.

Note

This step is optional for sellers enabled for payee payout auto-funding. On POST /payees/{payee_id}/payouts, Fynex atomically moves only the cashout wallet's shortfall from the seller's same-currency main wallet and then holds the payout amount. If either operation fails, neither movement is committed. On a Live account auto-funding is off by default and must be enabled by Fynex; on a Demo account it is always on. It does not apply to the primitive POST /payouts endpoint. If the payout is definitively rejected or cancelled, the auto-funded shortfall is returned to the seller's main wallet in the same transaction as the payout hold release. An ambiguous provider outcome stays held until it is reconciled, so the platform never returns funds that the provider may still settle. When both payeePayoutAutoFundingEnabled and walletCreationEnabled are enabled for the seller (both are always on for a Demo account) and the payee has no cashout_balance wallet in the payout method's currency, this endpoint first provisions one automatically and then auto-funds it. This also applies when the payee already has an ordinary other or tax wallet, because those split-destination wallets are intentionally not debited by auto-funding. The seller's own Itself payee is excluded: its payouts keep using the existing seller main wallet and never trigger cashout provisioning. Provisioning is idempotent and remains separate from the money-movement transaction, so a payout failure may leave the empty wallet available for a safe retry but cannot leave a partial ledger movement.

3. Pay the payee — POST /payees/{payee_id}/payouts (wallet auto-resolved):

curl -sS -X POST "$FYNEX_API/payees/101/payouts" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payoutMethodId": 501,
    "amount": "12.50",
    "description": "Invoice 2026-091 September commission",
    "idempotencyKey": "'$(uuidgen)'"
  }'

You don't pass a walletId — the payout draws from the payee's cashout_balance wallet (resolution prefers it). Response is the same 201 Created payout body as POST /payouts (status pending). Poll GET /payouts/{id} for the final status (see step 3 of the primitive flow below).

Note

payoutMethodId is required — there is no implicit default. The convenience layer auto-resolves the walletId; holds, idempotency, and banking-provider settlement use the same payout engine as POST /payouts. Unless the seller account is enabled for payee payout auto-funding, a payout before the cashout wallet is funded returns 409 insufficient balance.

The four primitive endpoints below still work unchanged when you need finer control (an existing payee, a specific source wallet, multiple payout methods, or the split-funded other wallet).

Prerequisites

• A seller wallet with sufficient balance in the target currency.
• A registered payee — create one with POST /payments-api/v1/payees (see Payees) if you don't have one yet.
• That payee must have at least one active payout method (bank account). Create one with POST /payments-api/v1/payees/{payee_id}/payout-methods (see Payout Methods), then use GET /payees/{payee_id}/payout-methods to look up the available methods and their ids.

Note

The step-by-step below assumes the payee and payout method already exist. If you are starting from scratch, use the quick path above, or follow the full order: create payee → create payout method → request payout.

Step-by-step

1. Find the payee's payout methods

payee_id is the numeric payee ID from GET /payees.

curl -sS "$FYNEX_API/payees/42/payout-methods" \
  -H "Authorization: Bearer $FYNEX_TOKEN" | jq

The response lists bank accounts with their id, currency, bankAccountType, and destination identifiers. Note the payoutMethodId you want to pay to, and the walletId you want to debit (confirm it has enough balance).

1. Create the payout

curl -sS -X POST "$FYNEX_API/payouts" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": 15,
    "payoutMethodId": 501,
    "amount": "1999.00",
    "currencyCode": "EUR",
    "description": "Invoice 2026-091 September commission",
    "idempotencyKey": "'$(uuidgen)'"
  }'

Response (201 Created):

   {
     "id": 9001,
     "status": "processing",
     "amountMinor": 199900,
     "currencyCode": "EUR",
     "providerReference": "ref_9f2c1a4b",
     "bankAccountType": "uk_local",
     "description": "Invoice 2026-091 September commission"
   }

Save the id — you will need it to poll status.

1. Poll for the final status

Poll GET /payouts/\{id\} until status reaches a terminal value, or subscribe a webhook endpoint to the opt-in PayoutCompleted and PayoutFailed events (see Webhooks).

curl -sS "$FYNEX_API/payouts/9001" \
  -H "Authorization: Bearer $FYNEX_TOKEN" | jq .status

Poll every 30–60 seconds until status is completed, failed, or cancelled.

Request body fields

* Exactly one of amount or amountMinor is required.

Note

The Idempotency-Key HTTP header is read as a fallback when the body's idempotencyKey is empty. When both are set, the body wins.

SEPA payouts — mandatory parameters

EUR payouts are sent as SEPA credit transfers through the banking provider (payment scheme SEPA, charge bearer SHA). The required parameters span two calls — registering the destination payout method and creating the payout itself.

1. Payout method (destination) — POST /payees/{id}/payout-methods (or via the dashboard):

The payout method type is bank_account — the only supported value.

2. Payout request — POST /payouts:

Note

The banking provider's payment scheme (SEPA), payment reference, requested execution date, charge bearer (SHA), creditor country, and the unstructured remittance line are all set by Fynex — you do not send them.

The payout transitions through pending → processing → completed once the banking provider confirms the SEPA settlement.

GBP Faster Payments — mandatory parameters

GBP payouts to a UK local account are sent through the banking provider's Faster Payments rail. The client supplies domestic bank identifiers; Fynex normalizes them and applies the banking provider's national-clearing-code representation at dispatch.

1. Payout method (destination) — POST /payees/{id}/payout-methods (or via the dashboard):

2. Payout request — provide a GBP walletId, the UK-local payoutMethodId, the amount, and currencyCode: GBP. Bank identifiers stay on the payout method and are not repeated in the payout request.

Note

The banking provider's payment scheme and the SC national-clearing-code prefix are set by Fynex. Clients send the six sort-code digits only.

Caution

Card payouts (push-to-card) are not supported. Payouts settle only to bank accounts through the banking provider. There is no card-out / OCT endpoint.

Response fields

POST /payouts (201 Created)

The create response is intentionally minimal:

GET /payouts/{id} (200 OK)

The detail response adds timing fields:

Note

Branch on failureCode, display failureMessage. The message is the fixed catalogue text for the code — never raw bank or operator notes — so it is stable enough to show to a seller but not meant to be parsed.

Status values

Approval

Payouts above your account's auto-approve limit — or held by another control on your account — wait for review by Fynex before they are processed. Such a payout is returned with status: "pending" and approvalStatus: "awaiting_approval"; approvalStatus is a separate field, not a status value, and it is present on every new payout. Unless Fynex has set an auto-approve limit for your account, the limit is 0, so every payout on a Live account starts awaiting approval.

On a Demo account every payout is approved automatically, whatever its amount and wherever it was created, so a test payout runs to completion with nobody at Fynex involved. A payout to a marketplace vendor can still be held by the vendor limit.

The same holds for payout methods: on a Demo account a bank account you add is approved at creation, so you can pay out to it at once. On a Live account a new or re-routed payout method starts pending unless Fynex has enabled auto-approval for your account. When a Demo account goes Live, every payout method nobody at Fynex reviewed returns to pending and must be approved before it pays out.

Listing payouts

curl -sS "$FYNEX_API/payouts?limit=20&offset=0" \
  -H "Authorization: Bearer $FYNEX_TOKEN" | jq

Returns payouts ordered by requestedAt descending. Query params limit (1–100, default 20) and offset (default 0).

Insufficient balance

If the wallet's withdrawable balance does not cover amountMinor, the request returns 409 Conflict:

{ "error": "insufficient balance" }

The check is against withdrawableBalanceMinor, not availableBalanceMinor. Settled funds stay inside a T+N maturity hold (the seller's payoutHoldDays, 3 business days by default) before a payout can take them, so this 409 often means the money is in the wallet but has not matured yet — common for a marketplace paying out shortly after a split. A Demo account has no hold: its settled funds are withdrawable at once. Check the wallet first (see Wallets):

• maturingBalanceMinor covers the shortfall → wait until those funds mature, then retry with the same idempotencyKey. A top-up is not held and would also unblock it, but it is unnecessary.
• Otherwise the wallet really is short → top it up via incoming payments or a treasury transfer, then retry with the same key.

For an auto-funded payee payout (POST /payees/{id}/payouts), the check covers the cashout wallet plus your main wallet's withdrawable balance, so check the main wallet's maturingBalanceMinor too. A separate 409 merchant balance cannot cover the payout fee means the payout fits but its fee does not.

Replaying a successful create with the same idempotencyKey returns the original payout — it does not create a second one and does not return 409.

Common errors

See also

• Polling & SSE — Poll payout status or subscribe to status events.
• Idempotency & retries — Safe retry patterns for payout creation.
• Split rules — Splitting incoming funds across multiple payees? Use Split rules.
• Virtual accounts — Need a dedicated bank account for incoming payments? See Virtual accounts.