Organization and Account

What is an organization?

Your organization is the top-level entity that represents your overall business in MoneyHash - everything else, including accounts, payment flows, connections, customers, and users, lives under this single organization. Inside it, you create accounts, and each account holds its own connections, flows, and API keys. Knowing which key belongs to which layer - and where each key is allowed to live - is essential to integrating securely.

• Parent entity: the organization is a container for one or more accounts, and all financial activity rolls up under it.
• Shared at the org level: some things belong to the organization and are shared across all accounts - notably customers, wallets, and risk rules - while account-specific things like transactions, connections, and flows belong to an individual account (see What lives at each level below).
• Central management: organization-wide settings, roles, and permissions let you keep each account and user within the right controls under one shared identity.

What is an account?

An account is a distinct financial entity inside your organization. It can represent a business unit, a subsidiary, or any division that needs its own separate setup. Each account maintains its own connections, payment defaults, and flows - effectively an isolated environment.

Benefits of using accounts

• Separate financial data - keep transactions, reports, and financial details confined to one unit, for clean separation and privacy.
• Streamlined workflows - configure payment methods and risk rules uniquely per account.
• Enhanced security - isolate operations so sensitive data stays accessible only to authorized users.

Common ways to use accounts

• Geographic locations - categorize transactions and revenue by region.
• Platforms - separate different online platforms or sales channels.
• Sub-merchants - represent sub-merchants or partners and manage their transactions independently.
• Testing & development - dedicated accounts for testing so experiments don't affect live operations. See Integration Modes (Test vs Live) for how Test and Live behave.

What lives at each level

Knowing what is scoped to the organization versus an account prevents a lot of confusion:

• Organization-level (shared across accounts): customers, wallets, risk rules, and organization-wide settings.
• Account-level (specific to each account): connections, flows, transactions, and payment defaults.
• Roles & permissions are supported at both the organization level and per account.

What an account inherits: currencies & payment methods

You don't manage currency lists or payment methods directly on the account - they're inherited from the Connections you add:

• Currencies are dynamic. When you add a connection, the currencies that connection supports automatically become available in the account.
• Payment methods work the same way. Enabling methods on a connected provider makes them available in the account, deactivating or removing them at the connection level removes them from the account.

The three keys at a glance

The keys map directly to the hierarchy - one operates at the organization level, one at the account level, and one on the client.

Where each key lives

This is the part to get right for security: two of the keys are server-side secrets, and one is meant for the client.

Organization API key & secret - the organization level

The organization API key & secret are your top-level, highest-privilege credential. They operate above any single account and are used for organization-wide actions, such as:

• Creating and managing accounts programmatically (via API).
• Other organization-level management actions across your accounts.

Account API key - a single account

The account API key is scoped to one account. It's used for server-to-server communication and account-level operations within that account. It is a secret: store it as a secure environment variable on your backend, and never include it in a frontend or mobile app.

You pass it in the x-api-key request header:

curl --location '<API_ENDPOINT>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR_ACCOUNT_API_KEY>' \
  --data '<REQUEST_BODY>'

The endpoint and body above are placeholders - what matters here is how the key is passed: in the x-api-key header, from your server. The key it carries determines which account the request acts on.

Use it for: server-side, account-level operations (the everyday work - payments and account actions).
Don't: put it in your frontend, mobile app, or any client-side code.

Public API key - the client (SDK & frontend)

The public API key is used by the MoneyHash SDKs on your frontend. Unlike the other two keys, it is not a server secret - it's designed to be used on the client.

Even so, the best practice is to not hardcode it into your app build. Instead, serve it from your remote / payment configuration that you control. That way you can change or revoke it at any time - for example if it's ever misused - without shipping a new app release.

Use it for: initializing the SDK and frontend payment experience and getting the account available methods.
Best practice: deliver it via remote/payment config so it stays easy to rotate or revoke.

Test and Live modes: what they apply to

A common misconception: Test and Live modes do not apply to organizations or accounts. They apply to entities like payment flows, connections, and transactions.

You have one organization and the same set of accounts across both modes - the structure is never duplicated. The same account can handle both test and live transactions at the same time, through different flows or connections.

What does differ per mode is the credentials: each account exposes a separate Account API key and Public API key for Test and for Live. Use the key that matches the mode you're operating in.

For how the modes themselves behave, see Integration Modes (Test vs Live).

Security best practices

• Keep the organization API key & secret and the account API key on your server only, as secure environment variables.
• The public API key is the only key meant for the client - and even that is best delivered via remote/payment config so you can revoke or rotate it instantly.
• Use the account API key for payments and account operations; reserve the org key & secret for organization-level automation.
• Always use the key that matches your mode (Test vs Live).