Core concepts

Learn the key Global Accounts concepts and API object names.

This page focuses on the concepts specific to Global Accounts. For the full Grid entity model, see Entities and Account model.

How Global Accounts fit into Grid

A platform creates customers. Each eligible customer gets a Global Account. In the API, that account is an internal account with type: "EMBEDDED_WALLET". Funding and withdrawals use quotes, while outbound movement requires customer authorization.

For a step-by-step implementation path, see Implementation overview.

Key objects

Object	Meaning
Global Account	A branded account experience that lets a customer hold a stable dollar balance and move funds through supported Grid rails.
Customer	The person or business that owns the Global Account. Customers are represented by Customer:... IDs.
Internal account	The Grid account object that holds the balance. A Global Account is an internal account with type: "EMBEDDED_WALLET".
External account	A bank account, wallet, or other destination outside Grid used for withdrawals and payouts. External accounts use ExternalAccount:... IDs.
Quote	A priced payment plan that locks amounts, currencies, fees, and payment instructions before execution. Quotes use Quote:... IDs.
Session	A short-lived signing context issued after the customer verifies a credential. Sessions use Session:... IDs.
Auth method	A registered customer credential such as passkey, OAuth, or email OTP. Auth methods use AuthMethod:... IDs.

API naming

In these docs, Global Account refers to the customer-facing account product. In the API, that account is represented as an internal account with type: "EMBEDDED_WALLET".

You may also see endpoint groups such as Embedded Wallet Auth; those are the authentication and signing APIs used by Global Accounts. The most important mapping is:

{
  "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "type": "EMBEDDED_WALLET"
}

Global Accounts vs Payouts

Choose Global Accounts when you are building a customer-owned account experience: issuing an account, showing a balance, funding it, requiring customer authorization, and moving money out of that account.

Choose Payouts & B2B when you are building a payouts-only flow: sending money from platform-managed or customer-managed balances to bank accounts and other payout destinations, without a customer-owned account experience.

The APIs overlap because both products use customers, accounts, quotes, transactions, and webhooks. The difference is the account model and authorization requirement: outbound movement from a Global Account requires a customer signature with Grid-Wallet-Signature.