Accounts

BETA: This endpoint is subject to change without notice.

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

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

This guide covers embedded accounts. For standalone accounts, see Standalone Accounts.

When to use embedded accounts

Embedded 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 embedded accounts. Each embedded account tracks its own balance and can pay out to its own bank account.

Creating an embedded account

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]",
      "type": "EMBEDDED",
      "account_holder": {
        "country_code": "GB",
        "verification_policy": "PARENT_ACCOUNT_ATTESTATION"
      },
      "capabilities": {
        "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

Embedded accounts support two capabilities:

• transfers — receive funds from the parent account via transfers. Must be requested during account creation.
• balance — track balance positions and pay out to external bank accounts. Enabled automatically when transfers is active.

Payouts from embedded accounts require approval by the parent account in the Dashboard before they are submitted.

Account lifecycle

Embedded accounts 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 an embedded 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 embedded 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 Webhooks for setup instructions.