Organizations and Locations

An organization is the business/authorization boundary; a location belongs to exactly one organization and identifies concrete payment work. Use organizationId for shared resources and policy and locationId for location-owned work. A vendor MID, physical serial, and Gateway location ID are different identities.

Organization-scoped access covers authorized descendant locations; location-scoped users and OAuth clients are limited to their explicit location set. Request only the scopes your application needs; see Authentication.

Shared policy and credential selection

Tax configuration has organization defaults and optional location overrides. Gift cards can be redeemed within the organization subject to enforced location restrictions; see Gift cards. Credential profiles are organization-owned and assigned to locations. A location-specific assignment takes precedence over the organization default; only ACTIVE or ROTATING profiles are eligible for processing. Never substitute a profile from another organization when a route is unavailable.

SDK and onboarding

Use OrganizationsApi for organization resources and LocationsApi for location records. Organization-scoped location onboarding needs organizations:read, organizations:write, and the appropriate organization or location binding. Global organization creation is platform-only.

1. Locate the authorized organization.
2. Use a stable POS store ID as the location externalId and look up the location by organization and external ID.
3. If absent, create it with stable business, address, contact, and metadata. A location has no MCC: the MCC is set on the processor account (credential profile) and recorded on each transaction.
4. On duplicate/race responses, repeat that lookup rather than creating another identity. Provision a distinct online location only when required.

Metadata can hold stable POS IDs and a support ticket reference, never secrets, processor credentials, card data, or customer personal information.