Skip to main content

Organizations and Locations

Gateway’s current tenant model is organization-first:

  • Organization is the top-level business boundary.
  • Location is an operational endpoint under an organization.
  • Gateway-owned APIs, SDKs, claims, and docs use organizationId and locationId for tenant scope. Vendor prose may still use "merchant" when it is the vendor's domain term.

Data model​

Organization
  ├─ owns many Locations
  ├─ owns credential profiles
  ├─ owns org-scoped configs
  │    ├─ tax configs
  │    ├─ gift-card configs
  │    └─ setup-intent defaults
  └─ owns org-scoped business objects
       ├─ gift cards
       ├─ customers
       ├─ products
       └─ subscriptions

Location
  ├─ belongs to exactly one Organization
  ├─ may override selected org defaults
  ├─ carries runtime state such as status / type / credential profile
  └─ is the operational unit used by checkout, in-person, and provisioning flows

Access-control summary​

  • Platform admins can read and write across organizations and locations.
  • Organization-scoped portal users can operate on the organizations they are assigned to and their descendant locations.
  • Location-scoped users or OAuth clients are restricted to their explicit location set.
  • Internal service callers use Cloud Run IAM plus service-to-service identity and may cross organization boundaries where the workflow requires it.

Inheritance patterns​

The rename is not just terminology. Several resources are intentionally organization-scoped with optional location overrides:

  • Tax configuration: organization defaults with location-specific overrides where needed.
  • Gift cards: redeemable across locations in the same organization.
  • Credential profiles: managed at organization scope, then assigned to locations.

Important current caveat:

  • the only unresolved runtime gap in this area is gift-card location- restriction enforcement at redemption; modeled rows exist, but runtime redemption is still organization-wide

Credential resolution​

Credential selection is runtime, not just data-model structure:

  • the gateway first checks for a location-specific credential-profile assignment
  • if none exists, it falls back to the organization default profile

Only credential profiles in ACTIVE or ROTATING status are eligible to process transactions. Other statuses remain visible for admin workflow and audit purposes but do not participate in runtime credential resolution.

That pattern keeps external integrators on a small number of stable concepts:

  • look up the organization for shared policy
  • operate on a location for concrete runtime work
  • avoid duplicating org-wide state across every location

SDK shape​

The SDKs follow the same split:

  • OrganizationsApi for organization-scoped resources
  • LocationsApi for concrete location records and operational status

Organization-scoped location onboarding​

For POS or support-created stores, onboard locations through the organization-scoped location APIs instead of the platform-only global location create path.

Required OAuth posture:

  • organizations:read
  • organizations:write
  • an organization or location binding for the Gateway organization being managed

admin:* also works for platform operators, but it is broader than the intended support/POS-created organization flow. Global organization creation remains platform-only.

Retry-safe POS onboarding flow:

  1. Create or locate the organization.
  2. Use the POS store id as the Gateway location externalId.
  3. Look up the location by organization and external id.
  4. If absent, create the location with stable business, address, MCC/contact, external id, and metadata values.
  5. On duplicate or race responses, repeat the lookup by externalId.
  6. Provision an online location only when the workflow needs a distinct online runtime endpoint.

Recommended metadata keys are stable POS/support identifiers such as sourceSystem, posOrganizationId, posStoreId, onboardingRunId, and supportTicketId. Do not put secrets, processor credentials, card data, or customer PII in location metadata.

Contract promises​

  • Organization/location terminology is the primary model for docs, SDK entry points, and Gateway-owned wire fields.
  • SDKs expose OrganizationsApi and LocationsApi for tenant operations.
  • Location-owned payment work should use locationId.
  • Organization-owned policy and shared resources should use organizationId.
  • Every organization limits cross-location gift-card redemption only when the configured restriction rows require that behavior.