Skip to main content

Base URLs and environments

Payments AI 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 baseServer-side tokenizationClient-side tokenization
Stagehttps://staging-api.payments.aiPOST /v1/public-api/organizations/{organizationId}/payment-instruments/tokens (Public API, STAGING ONLY)FramePay
Productionhttps://api.payments.aiPOST https://tokenization.payments.ai/tokens (dedicated host)FramePay

The Public API has separate stage and production hosts. There are three ways to obtain a token:

  • Stage server-side tokenization: POST /v1/public-api/organizations/{organizationId}/payment-instruments/tokens on staging-api.payments.ai. Restricted to stage; testing only. Uses a flat body (primaryAccountNumber, cardVerificationValue, expirationMonth, expirationYear). Returns HTTP 201 with { type, data: { id, createdAt, expiratedAt } }.
  • Production server-side tokenization: POST /tokens on the dedicated host tokenization.payments.ai. Production only; the host does not respond on stage. Uses a nested body (method, paymentInstrument, billingAddress, optional riskMetadata) and the X-Organization-Id header.
  • FramePay (client-side): works on both stage and production. The JavaScript SDK mounts hosted iframe fields in your frontend; raw card data never reaches your server. Keeps PCI scope at SAQ A.

For the choice between server-side and FramePay, see When to use FramePay vs server-side. For the stage-vs-production request and response body shapes, see Tokenization endpoint.

Public API​

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

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.

Production tokenization host​

The production tokenization endpoint is hosted on a separate domain (tokenization.payments.ai) and uses a different URL pattern and authentication header from the Public API.

URL pattern:

https://tokenization.payments.ai/tokens
  • Production only — the host does not respond on stage. For stage server-side tokenization, use the Public API endpoint instead: POST /v1/public-api/organizations/{organizationId}/payment-instruments/tokens.
  • The organizationId is excluded from the URL path.

Authentication header:

Authorization: ApiKey <accountId>_<apiKey>_<apiKeyId>
X-Organization-Id: <organizationId>

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

FramePay (client-side, both environments)​

FramePay is a JavaScript SDK that mounts Payments AI-hosted iframe fields directly into your payment form. It works on both stage and production, keeps raw card data out of your server, and minimizes PCI scope.

See FramePay for the full integration guide.

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.