Skip to main content

Base URLs and environments

PaymentsAI exposes two distinct APIs with different URL patterns and authentication conventions. Using the wrong pattern is a common source of integration errors.

Environments​

EnvironmentPublic API baseTokenization API
Stagehttps://staging-api.payments.aiNot available. Use FramePay for tokenization on stage.
Productionhttps://api.payments.aihttps://tokenization.payments.ai

The Public API has separate stage and production hosts. The Tokenization API is available on production only. On stage, tokenize cards client-side through FramePay instead.

Public API​

The Public API hosts the majority of endpoints, including customers, subscriptions, transactions, invoices, and gateways.

URL pattern:

Stage: https://staging-api.payments.ai/v1/public-api/organizations/{organizationId}/...
Production: https://api.payments.ai/v1/public-api/organizations/{organizationId}/...
  • The host differs between environments: staging-api.payments.ai on stage, api.payments.ai on production.
  • The organizationId is embedded in the URL path on every request.

Authentication header:

Authorization: ApiKey <accountId>_<apiKey>_<apiKeyId>

See Authentication for the full format and security rules, and API key generation to learn how to obtain the key.

Tokenization API​

The Tokenization API is a separate endpoint for creating payment-instrument tokens server-side. It is restricted to production and uses a different URL pattern and authentication header from the Public API.

URL pattern:

https://tokenization.payments.ai/tokens
  • Production only. On stage, tokenize cards client-side through FramePay.
  • The organizationId is excluded from the URL path.

Authentication header:

X-Organization-Id: <organizationId>

Mixing these two patterns is a common integration mistake. The Public API expects the organizationId in the path, while the Tokenization API expects it as a header.

Required environment variables​

Configure these variables in your backend before making any API calls:

VariableValueWhere to find it
API_URLhttps://staging-api.payments.ai/v1/public-api (stage) or https://api.payments.ai/v1/public-api (production)Constant per environment
API_KEYThe full concatenated key: <accountId>_<apiKey>_<apiKeyId>Returned from the API key generation flow. See API key generation
ORGANIZATION_IDYour Organization ID (UUID)PAI panel → Settings → General → Organization information

Never store these values in frontend code or commit them to source control. See Authentication for security rules.