Admin API

Base URL (canonical on the service): https://<your-admin-backend-host>/api/v1 — your deployment sets the host via ADMIN_BACKEND_DOMAIN. Self-hosted examples often use api.yourcompany.com or api.example.com; hosted production uses https://api.payment-gateway.app — Hostnames & DNS conventions.

OpenAPI / Swagger UI: https://<your-admin-backend-host>/api/v1/docs/index.html

Shorter public path (default reverse proxy): same host with /v1/... — payment-gateway-reverseproxy/Caddyfile rewrites /v1/* → /api/v1/* on {$ADMIN_BACKEND_DOMAIN} before proxying to the Admin Backend.

The Admin Backend is the primary integration surface for server-side automation. All endpoints require an API Key or JWT in the Authorization: Bearer header.

For merchant integrations, this is the API you should target. Use Organization API keys for organization-scoped automation. System API keys are intended for global administrative tasks such as platform provisioning or system-wide automation.

API Key format: sk_live_<keyId>.<secret> or sk_test_<keyId>.<secret>

The key ID and secret are dot-separated. Both parts are shown only once at creation time.

Organization API keys are already bound to a single organization. Do not send X-Organization-ID with organization API key requests; the backend resolves the organization directly from the key. JWT/session-based dashboard requests resolve organization context from the route :orgId parameter when present, otherwise from the selectedOrganization cookie maintained by the admin frontend.

[!IMPORTANT] Every endpoint enforces both role permission (Viewer, Editor, Admin) and scope (resource:action). A request fails with 403 if the API key lacks the required scope.

Authentication

POST /api/v1/auth                         # Initiate WebAuthn authentication
POST /api/v1/auth/authenticate-complete   # Complete WebAuthn authentication → JWT
POST /api/v1/auth/refresh-token           # Refresh JWT
POST /api/v1/auth/logout                  # Invalidate session
GET  /api/v1/auth/login/check             # Check if current JWT is valid

Checkouts

[!IMPORTANT] The {siteId} in the create path is your Site MongoDB ObjectId (from Sites → Edit). The {checkoutId} in get / patch is the checkout document id — not the site id.

Create Checkout

POST /api/v1/checkouts/{siteId}/create
Authorization: Bearer sk_live_keyid.secret
Content-Type: application/json

[!NOTE] Path examples below use /api/v1/... as registered in the Admin Backend. On {$ADMIN_BACKEND_DOMAIN} with the default Caddyfile, the same handlers are reachable at /v1/....

{
  "amount": 4900,
  "currency": "EUR",
  "email": "buyer@example.com",
  "returnUrl": "https://yourapp.com/success?txId={transactionId}",
  "cancelUrl": "https://yourapp.com/cancel",
  "ipnUrl": "https://yourapp.com/webhooks/payment-ipn",
  "externalReference": "order_12345",
  "invoiceNumber": "INV-2026-0001",
  "clientId": "507f1f77bcf86cd799439014",
  "items": [
    {
      "name": "Professional Plan — Monthly",
      "description": "Professional Plan — Monthly",
      "quantity": 1,
      "unitPrice": 4900,
      "vatRate": 19,
      "itemType": "virtual"
    }
  }
}

[!IMPORTANT] Provide at least one of externalReference or invoiceNumber. The API accepts both, but a reference is required for reconciliation.

[!NOTE] {transactionId} in returnUrl/cancelUrl is a literal template placeholder — the gateway substitutes the actual transaction ID at redirect time.

Optional ipnUrl sets where the Main Backend sends outbound IPN for transactions created from this checkout; the Webhook Signing Secret on the Site is used to sign those requests.

Response 200:

{
  "id": "507f1f77bcf86cd799439011",
  "sessionPublicId": "abc123xyz789def456",
  "shortCode": "aB3xK9mw2P",
  "paymentUrl": "https://secure.payment-gateway.app/checkout/aB3xK9mw2P"
}

paymentUrl is always on MAIN_FRONTEND_DOMAIN (hosted: secure.payment-gateway.app). See Hostnames & DNS conventions.

Transactions

List Transactions

GET /api/v1/transactions?status=succeeded&currency=EUR&from=2026-01-01&to=2026-03-31&limit=50&page=1

Query Parameters:

Invoices

Draft Invoice Tax Semantics

Draft invoice creation, draft invoice updates, recurring invoice generation, and transaction tax calculation all rely on the same backend tax engine and tax-rate timing rules.

• Omit items[].taxRate to let the backend auto-calculate tax from the seller context, client billing country, client tax country fallback, item type, and the effective tax-rate schedule.
• Provide items[].taxRate to apply an explicit manual override for that line item.
• Use POST /api/v1/invoices/preview-tax before creating or updating a draft invoice when you need the exact canonical rate, totals, and taxRateCode the backend will use.

Example manual draft invoice payload with one automatic line and one explicit override:

{
  "siteId": "507f1f77bcf86cd799439011",
  "clientId": "507f1f77bcf86cd799439012",
  "currency": "EUR",
  "items": [
    {
      "description": "Subscription",
      "quantity": 1,
      "unitPrice": 12100,
      "amountType": "gross",
      "itemType": "virtual"
    },
    {
      "description": "Manual reduced VAT line",
      "quantity": 1,
      "unitPrice": 10700,
      "amountType": "gross",
      "taxRate": 7,
      "itemType": "physical"
    }
  ]
}

In the example above, the first line is auto-calculated and the second line uses an explicit 7% override.

Recurring Schedules

Credit Notes

Clients

Sites

Organization Settings

Invoicing Settings

The numbering contract is layout-based. Organizations store one layout for invoices and one for credit notes.

{
  "enabled": true,
  "autoGenerateInvoice": false,
  "companyName": "Example GmbH",
  "companyAddress": {
    "street": "Example Street 1",
    "city": "Berlin",
    "postalCode": "10115",
    "country": "DE"
  },
  "companyEmail": "billing@example.com",
  "invoiceNumberLayout": {
    "prefix": "INV-",
    "periodType": "calendar",
    "periodGranularity": "year",
    "fiscalYearStartMonth": 1,
    "fiscalYearLabelMode": "end_year",
    "periodSeparator": "dash",
    "infix": "-",
    "sequenceDigits": 6,
    "suffix": "",
    "resetPolicy": "calendar_year",
    "startNumber": 1
  },
  "creditNoteNumberLayout": {
    "prefix": "CN-",
    "periodType": "calendar",
    "periodGranularity": "year",
    "fiscalYearStartMonth": 1,
    "fiscalYearLabelMode": "end_year",
    "periodSeparator": "dash",
    "infix": "-",
    "sequenceDigits": 6,
    "suffix": "",
    "resetPolicy": "calendar_year",
    "startNumber": 1
  }
}

Tax settings (organization)

Notes:

• periodType is one of none, calendar, or fiscal.
• periodGranularity is one of year, year_month, or year_month_day.
• periodSeparator is dash or none and only matters when month or day is visible.
• resetPolicy is one of never, calendar_year, or fiscal_year.
• Sites inherit these layouts and may override only invoicePrefix and creditNotePrefix in their site-level invoicing settings.

Providers

Domains

API Keys

Organization API keys are already bound to one organization, but the management endpoints remain nested under /organizations/{orgId}/api-keys for admin and automation workflows. System API keys use the /api/v1/system/api-keys family and are intended for global administrative automation rather than normal merchant checkout integrations.

Portal

Create Customer Portal Magic Link

POST /api/v1/organizations/settings/portal/magic-links
Authorization: Bearer sk_live_keyid.secret
Content-Type: application/json

{
  "email": "buyer@example.com",
  "ttlMinutes": 15
}

Returns a one-time magic-link URL that can be used to direct the customer straight into the portal login flow for that email.

ttlMinutes is optional. If omitted, the system portal magic-link TTL is used. If provided, it can only shorten the lifetime; values above the system policy are capped to the configured system maximum.

Example server-side usage:

const response = await fetch(
  `${adminBaseUrl}/api/v1/organizations/settings/portal/magic-links`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${organizationApiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "buyer@example.com",
      ttlMinutes: 15,
    }),
  },
);

if (!response.ok) {
  throw new Error(`Failed to create portal magic link: ${response.status}`);
}

const { url, expiresAt, ttlMinutes } = await response.json();

return {
  loginUrl: url,
  expiresAt,
  effectiveTtlMinutes: ttlMinutes,
};

The endpoint only succeeds when:

• system-level portal access is enabled,
• system-level portal magic links are enabled,
• the authenticated organization has portal access enabled, and
• the email has at least one portal-visible invoice, credit note, or recurring subscription in that organization.

Use this for trusted backend automations only. Do not expose it to browser or mobile clients.

Tax Management

Admin JWT calls use the Admin role for these routes; API keys need the matching tax_rule:* / tax_rate:* scopes.

Tax Reports

Reports use query parameters for filters (e.g. startDate, endDate, timezone, source=transactions|invoices|both, currency, siteId). VAT OSS endpoints require year and quarter (1–4). Export endpoints return a file download and are GET, not POST.

Tax records (canonical ledger)

Immutable tax records back admin reporting drill-downs and traceability. List filters include date range, sourceKind, taxCountry, recognitionMode (accrual / cash), pagination, and links to transactions or invoices.

Data Import / Export

Dashboard

GET /api/v1/dashboard

Returns aggregated metrics: gross volume, net revenue, transaction counts, failure ratios, top providers, and recent transactions. Used by the Admin Panel home page.

API Key Scopes Reference

Common least-privilege bundles

• Checkout creation: checkout:create
• Website billing bridge auto-provisioning: client:read, client:create, invoice:read, invoice:create
• Recurring schedule management: invoice:read, invoice:create, invoice:execute

Recurring schedules do not use a separate recurring:* scope family. They are governed by the invoice:* scope family.