Payout Methods

Register bank accounts and IBANs as payout destinations for your payees, then use them as targets when requesting a payout.

A payout method is a bank account or virtual IBAN registered as a destination for a specific payee. When you request a payout, you target a payout method — it tells Fynex where to send the money.

Note

Payout methods are bank accounts only (type: bank_account). Card destinations are not supported. IBAN methods in EUR, GBP, and USD are executable through the current banking-provider mapping. GBP uk_local methods are executable through Faster Payments. US-local and SWIFT formats can be onboarded and approved, but execution is blocked before funds are held until their mappings are enabled.

Payout methods have two API surfaces:

Note

Integrators with a Bearer token have full REST CRUD over payout methods. update and delete operate on a single method at …/payout-methods/{method_id}; the method must belong to the payee in the path and to your seller account.

Prerequisite ordering

1. Create a payee — a payout method must be attached to an existing payee. See Payees.

2. Create a payout method on that payee — supply the bank account details documented below.

3. Request a payout — POST /payments-api/v1/payees/{payee_id}/payouts with the payoutMethodId, or POST /payments-api/v1/payouts with walletId + payoutMethodId for your own account. See Payouts.

Note

payee_id in the REST path is the numeric integer ID returned by createPayee or from the payee list — not a UUID or string.

Payout method fields (from schema.graphql)

type PayoutMethod

REST — List payout methods for a payee

Auth: Bearer token (Authorization: Bearer <token>)

GET /payments-api/v1/payees/{payee_id}/payout-methods

Returns a list of active payout methods for the specified payee. Use this before creating a payout to confirm that a method exists and to retrieve its id.

curl -sS "https://api.fynex.ai/payments-api/v1/payees/7/payout-methods" \
  -H "Authorization: Bearer $FYNEX_TOKEN"

REST — Create a payout method for a payee

Auth: Bearer token (Authorization: Bearer <token>)

POST /payments-api/v1/payees/{payee_id}/payout-methods

Registers a new payout destination for the payee. The owning payee is taken from the path and pinned to your seller account, so payeeId is not accepted in the body. Only bank_account methods are supported. bankAccountType describes the supplied account identifiers; Fynex selects the rail. IBAN destinations can be used for EUR, GBP, and USD payouts. GBP uk_local destinations use Faster Payments. US-local and SWIFT formats can be saved and reviewed but payout execution is rejected before funds are held until their provider mappings are enabled.

Returns 201 Created with the payout method. A payee that does not exist, or belongs to another seller, returns 404.

Request body fields

curl -sS -X POST "https://api.fynex.ai/payments-api/v1/payees/7/payout-methods" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "bankAccountType": "iban",
    "iban": "DE89370400440532013000",
    "bic": "DEUTDEFF",
    "accountName": "Acme Supplies Ltd"
  }'

REST — Update a payout method

Auth: Bearer token (Authorization: Bearer <token>)

PATCH /payments-api/v1/payees/{payee_id}/payout-methods/{method_id}

Updates only the fields present in the body; omitted fields are left unchanged. currency cannot be changed (it is fixed at creation). The method must belong to the payee in the path and to your seller account, otherwise 404. Set status to inactive to retire a method (it is then excluded from the list and can no longer be used for new payouts) or active to restore it.

Request body fields (all optional)

curl -sS -X PATCH "https://api.fynex.ai/payments-api/v1/payees/7/payout-methods/501" \
  -H "Authorization: Bearer $FYNEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accountName": "Acme Supplies Ltd" }'

REST — Delete a payout method

Auth: Bearer token (Authorization: Bearer <token>)

DELETE /payments-api/v1/payees/{payee_id}/payout-methods/{method_id}

Deletes a payout method your seller account owns. The method must belong to the payee in the path, otherwise 404. Returns { "deleted": true }.

curl -sS -X DELETE "https://api.fynex.ai/payments-api/v1/payees/7/payout-methods/501" \
  -H "Authorization: Bearer $FYNEX_TOKEN"

GraphQL — Full CRUD

Auth: dashboard_session cookie — see GraphQL Authentication for the login flow.

CreatePayoutMethodInput fields

UpdatePayoutMethodInput fields

All fields are optional. Supply only the fields you want to change.

Create a payout method — code samples

# Step 1 — login and save the cookie
curl -sc cookies.txt \
  -X POST https://api.fynex.ai/api/v1/login/dashboard \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

# Step 2 — create the payout method (IBAN example)
curl -b cookies.txt \
  -X POST https://api.fynex.ai/dashboard/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreatePayoutMethod($input: CreatePayoutMethodInput!) { createPayoutMethod(input: $input) { id payeeId currency iban isDefault status } }",
    "variables": {
      "input": {
        "payeeId": 7,
        "currency": "EUR",
        "type": "bank_account",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bankName": "Commerzbank AG",
        "accountName": "Acme Supplies Limited"
      }
    }
  }'

JavaScript

const BASE = 'https://api.fynex.ai';

// Assumes login was already called and the dashboard_session cookie is present
async function createPayoutMethod(input) {
  const res = await fetch(`${BASE}/dashboard/graphql`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `
        mutation CreatePayoutMethod($input: CreatePayoutMethodInput!) {
          createPayoutMethod(input: $input) {
            id
            payeeId
            currency
            iban
            isDefault
            status
          }
        }
      `,
      variables: { input },
    }),
  });
  const { data, errors } = await res.json();
  if (errors?.length) throw new Error(errors[0].message);
  return data.createPayoutMethod;
}

const method = await createPayoutMethod({
  payeeId: 7,
  currency: 'EUR',
  type: 'bank_account',
  iban: 'DE89370400440532013000',
  bic: 'COBADEFFXXX',
  bankName: 'Commerzbank AG',
  accountName: 'Acme Supplies Limited',
});
console.log(method);
// { id: 3, payeeId: 7, currency: 'EUR', iban: 'DE89370400440532013000', isDefault: true, status: 'active' }

Python

import requests

BASE = "https://api.fynex.ai"
session = requests.Session()

# Login first
session.post(
    f"{BASE}/api/v1/login/dashboard",
    json={"email": "you@example.com", "password": "your_password"},
).raise_for_status()

mutation = """
  mutation CreatePayoutMethod($input: CreatePayoutMethodInput!) {
    createPayoutMethod(input: $input) {
      id
      payeeId
      currency
      iban
      isDefault
      status
    }
  }
"""
variables = {
    "input": {
        "payeeId": 7,
        "currency": "EUR",
        "type": "bank_account",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bankName": "Commerzbank AG",
        "accountName": "Acme Supplies Limited",
    }
}
resp = session.post(
    f"{BASE}/dashboard/graphql",
    json={"query": mutation, "variables": variables},
)
resp.raise_for_status()
body = resp.json()
if "errors" in body:
    raise RuntimeError(body["errors"][0]["message"])
print(body["data"]["createPayoutMethod"])

Other operations

Update a payout method

mutation UpdatePayoutMethod($id: Int!, $input: UpdatePayoutMethodInput!) {
  updatePayoutMethod(id: $id, input: $input) {
    id
    iban
    bic
    isDefault
    status
    updatedAt
  }
}

Delete a payout method

mutation DeletePayoutMethod($id: Int!) {
  deletePayoutMethod(id: $id)
}

Returns true on success. You cannot delete a method that is currently referenced by a pending payout — cancel or complete the payout first.

List payout methods via GraphQL

query ListPayoutMethods($payeeId: Int!, $limit: Int, $offset: Int) {
  payoutMethods(payeeId: $payeeId, limit: $limit, offset: $offset) {
    items {
      id
      currency
      type
      iban
      accountNumber
      isDefault
      status
    }
    totalCount
  }
}

Common pitfalls

See also

• GraphQL Authentication — Obtain a dashboard_session cookie before calling any GraphQL mutation.
• Payees — Create and manage the payees that payout methods are attached to.
• Payouts — Send money from a seller wallet to a payee