Skip to main content

Account Structure

Understanding how your Payments AI account is organised helps you manage users, track transactions, and connect payment gateways correctly.

Hierarchy Overview​

Organization
└── Merchant Account
    └── Gateway Connection(s)

Organization​

The organization is the top-level legal entity in Payments AI. It represents your business and holds your merchant account.

Your Organization ID is a UUID displayed in the Payments AI panel under Settings → General → Organization information (with a copy button). It is used in two situations:

  • API requests: your development team passes the Organization ID as the organisation identifier in calls to the Payments AI API.
  • Support emails: include your Organization ID when emailing Payments AI support so the team can locate your organisation quickly.

Merchant Account​

A merchant account is the processing account through which transactions are submitted. Each organization has one merchant account, identified by its own Account ID, visible in your dashboard settings.

Gateways​

One or more payment gateways can be connected to each merchant account. Payments AI supports the following gateways:

  • Payments AI Gateway (default)
  • Stripe
  • PayPal
  • NMI
  • Klarna
  • Coinbase
  • Splitit

For per-gateway setup, supported regions, and limitations, see the Gateways section. You can connect additional gateways from the Gateways tab in the top navigation bar. To request a gateway not listed, use the Request a Gateway option in the same tab. When multiple gateways are connected, Payments AI routes each transaction to the appropriate gateway based on your configured rules.

API Keys​

API keys are used by your development team to authenticate requests to the Payments AI API. As a business owner, you are responsible for the security of your account secret.

Activation​

When Payments AI creates your production account, you receive a Temporal API Key. The Temporal API Key is valid for 7 days — if you do not use it within that window, the key expires and Payments AI must issue a new one. Activate the account by setting a secret using the Temporal API Key. Until the account is activated, no payments can be processed.

This activation step applies to production only. On stage, your Integration Consultant provides a ready-to-use API Key — there is no Temporal-to-Permanent exchange. See Integration Checklist & Go-Live Runbook.

Secret Requirements​

Your secret must meet all of the following:

  • Between 12 and 30 characters
  • At least one uppercase letter
  • At least one alphanumeric character (letter or number)

Rotation Policy​

Your secret must be changed every 90 days. The new secret must be different from the last 4 secrets used.

Important:

Treat your API secret like a password. Do not share it via email or store it in unencrypted files. If your account is compromised, contact Payments AI support immediately — the team can deactivate your account or rotate your API keys.