Accounts

BETA: This endpoint is subject to change without notice.

A platform account can create two kinds of sub-account. Both are managed using the parent's API key:

A platform can freely mix both kinds. For example, a marketplace might use independent accounts for sellers who need to accept payments directly, and fund pool members for internal entities that only need to receive transferred funds. The two kinds are mutually exclusive in their capabilities — independent accounts cannot receive transfers, and fund pool members cannot process card payments.

The type field (EMBEDDED / STANDALONE) is deprecated. It is still accepted for backward compatibility and still appears in responses, but new integrations should use capabilities.balance.requested instead.

This guide covers fund pool member accounts (formerly "embedded"). For independent accounts, see Independent Accounts.

When to use fund pool members

Fund pool member accounts are useful when your platform needs to hold and distribute funds on behalf of other entities. Common scenarios:

• Marketplaces — split payment proceeds between sellers
• Platforms — hold funds for service providers and pay out on a schedule
• Multi-entity businesses — track and distribute funds across divisions or locations

The parent account collects payments and uses transfers to move funds to fund pool members. Each fund pool member tracks its own balance and can pay out to its own bank account.

Prerequisites

The parent account must have a custodial bank account connected before it can create fund pool members. This custodial bank account defines the fund pool. Contact [email protected] to set this up.

Creating a fund pool member

API reference

The Idempotency-Key header lets you safely retry the request if it fails — see Idempotency.

curl -X POST https://api.synaptopay.com/v1/accounts \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": "accounts/acct_YOUR_ACCOUNT",
    "account": {
      "display_name": "Example Seller",
      "contact_email": "[email protected]",
      "account_holder": {
        "country_code": "GB",
        "verification_policy": "PARENT_ACCOUNT_ATTESTATION"
      },
      "capabilities": {
        "balance": {
          "requested": true
        },
        "transfers": {
          "requested": true
        }
      }
    }
  }'

Response

{
  "name": "accounts/acct_EMBEDDED_ACCOUNT",
  "display_name": "Example Seller",
  "contact_email": "[email protected]",
  "type": "EMBEDDED",
  "state": "ACTIVE",
  "capabilities": {
    "transfers": {
      "requested": true,
      "state": "PENDING"
    },
    "balance": {
      "state": "ACTIVE",
      "external_transfer_policy": "PARENT_APPROVAL_REQUIRED"
    }
  },
  "parent_account_name": "accounts/acct_YOUR_ACCOUNT",
  "create_time": "2026-01-15T10:30:00Z",
  "update_time": "2026-01-15T10:30:00Z"
}

Account fields

Capabilities

Fund pool members support two capabilities:

• balance — track balance positions and pay out to external bank accounts. Set requested: true during account creation.
• transfers — receive funds from the parent account via transfers. Must be requested alongside balance.

Fund pool members cannot have card payments enabled. Payouts from fund pool members require approval by the parent account in the Dashboard before they are submitted.

Account lifecycle

Fund pool members are created in ACTIVE state. The transfers capability starts as PENDING until the account holder's legal name is provided — either at creation or during the boarding flow via an account session.

Retrieving an account

API reference

curl https://api.synaptopay.com/v1/accounts/acct_EMBEDDED_ACCOUNT \
  -H "Authorization: Api-Key $API_KEY"

Listing accounts

API reference

List all child accounts under your parent account:

curl -X POST https://api.synaptopay.com/v1/accounts:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_account_name": "accounts/acct_YOUR_ACCOUNT"
  }'

Account sessions

API reference

An account session creates a temporary URL that redirects to the Dashboard for collecting account holder details. Use this to let account holders complete their own boarding.

The boarding flow collects the account holder's legal name (if not already provided) and an external bank account for payouts. Note that an external bank account is not required when creating an account via the API — it is only collected during the boarding flow.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_EMBEDDED_ACCOUNT/account-sessions \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_session": {
      "type": "BOARDING",
      "boarding_details": {
        "return_url": "https://example.com/boarding-complete",
        "refresh_url": "https://example.com/boarding-refresh"
      }
    }
  }'

Response

{
  "type": "BOARDING",
  "url": "https://dashboard.synaptopay.com/account-session/acct_sess_SESSION_ID",
  "boarding_details": {
    "return_url": "https://example.com/boarding-complete",
    "refresh_url": "https://example.com/boarding-refresh"
  },
  "create_time": "2026-01-15T10:30:00Z",
  "expire_time": "2026-01-15T11:30:00Z"
}

Redirect the account holder to the url to begin boarding. When they complete the session, they are redirected to return_url. If the session expires, they are redirected to refresh_url.

Inviting users

You can invite users to access a fund pool member account via the Dashboard. Invited users sign in and can view and manage the account based on their assigned role:

To invite a user, go to Settings > Team in the Dashboard for the fund pool member account and click Invite member. The invitee receives an email with a link to accept the invitation.

Parent account admins automatically have access to their child accounts — they do not need a separate invitation.

Webhooks

When an account's details or capabilities change, an account.updated event is sent to your webhook endpoints. See Collect Webhooks for setup instructions.