Organizations
An Organization is the top-level entity in Payments AI. It represents you, or your company, as a merchant. When you first sign in to Payments AI you are prompted to create one. Every API call addresses an Organization explicitly through organizationId in the URL path or header.
Organization and Account
In Payments AI the hierarchy is Organization → Account → Gateway Connection(s). One Organization maps to exactly one Account — not many. If your business operates several legal entities or processing accounts, each one is a separate Organization in Payments AI.
- Organization ID is the UUID used in API requests and support communication.
- Account ID is the processing account beneath the Organization.
What lives under an Organization
| Resource | Scoped to organization | Notes |
|---|---|---|
| API keys | Yes | One Organization can have multiple keys (e.g., one per environment or per user role). See API key generation. |
| Users | Yes | Users are assigned to the Organization with a role (Owner, Editor, Viewer, etc.). |
| Customers | Yes | Customer IDs are unique within an Organization. |
| Payment instruments | Yes | Live on customer records, so by transitive scope. |
| Products and plans | Yes | A product or plan from Organization A is not visible to Organization B. |
| Subscriptions and transactions | Yes | All ledger records belong to one Organization. |
| Websites | Yes | See Websites. |
| Custom fields | Yes | Definitions are organization-scoped. |
| Gateways | Yes | Gateway configuration (PayPal, Stripe, Klarna, Coinbase, NMI) is set per Organization. |
URL pattern
All Public API endpoints embed organizationId in the path:
https://staging-api.payments.ai/v1/public-api/organizations/{organizationId}/...
https://api.payments.ai/v1/public-api/organizations/{organizationId}/...
The production tokenization host uses a different pattern — it expects the Organization ID in the X-Organization-Id header instead. See Base URLs.
Finding your Organization ID
Your organizationId is a UUID. You can find it in two places:
- PAI panel: Settings → General → Organization information.
POST /access-permitsresponse when you create the Organization programmatically.
Organization API endpoints
The Public API exposes a small set of Organization-level operations:
| Endpoint | Purpose |
|---|---|
POST /v1/public-api/organizations | Create an Organization (returns a redirectUrl and the new organizationId). |
GET /v1/public-api/organizations/{organizationId} | Retrieve Organization details (returns account, business, member, and onboarding status fields). |
POST /v1/public-api/organizations/{organizationId}/register-with-default-gateway | Submit business, member, and account information to register the Organization with the default payment gateway. |
POST /v1/public-api/organizations/{organizationId}/generate-hosted-onboarding-url | Generate a hosted onboarding URL for completing KYC outside the Public API. Returns null until available. |
User assignment and access flow uses POST /v1/access-permits and POST /v2/organizations/{organizationId}/access-permits.
Users and roles
A user is assigned to an Organization with a role. The most common roles:
| Role | Can do |
|---|---|
| Owner | Full access to all resources, settings, billing, and user management. Owner is also the only role with access to organization logs. |
| Admin | Same access as Owner — full access to all resources, settings, billing, and user management — except organization logs. |
| Editor | Create, edit, and suggest resources via Public API. Cannot approve changes or modify organization settings. |
| Viewer | Read-only access. |
The exact role hierarchy may include additional levels (for example, Accountant, Developer) depending on your account configuration. Role enforcement happens on every API call; calling a write endpoint with a Viewer key returns 403 Forbidden. See Errors.
Settings and feature toggles
Most Organization settings are managed in the PAI panel rather than via Public API. A few resources are exposed as dedicated endpoints:
Some optional features are gated by per-Organization toggles activated through Payments AI support:
- BIN retrieval — requires the
isBinExposureEnabledtoggle.