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/.... The default reverse proxy configuration shipped with the deployment package rewrites /v1/* to /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": "digital_service"
    }
  }
}

[!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 points to the checkout frontend host selected for the session: the default MAIN_FRONTEND_DOMAIN (hosted: secure.payment-gateway.app) unless provider/frontend-domain routing selects a provider-specific checkout host. See Hostnames & DNS conventions.

Response 409:

Checkout creation can return a business conflict instead of a payment URL. These responses include requestId; plugin and custom integrations should show that ID to the customer or operator for support.

Transactions

List Transactions

GET /api/v1/transactions?statuses[]=1&currency=EUR&startDate=2026-01-01&endDate=2026-03-31&limit=50&page=1

Query Parameters:

Invoices

The e-invoice download endpoints enforce Settings > Invoicing > eInvoice Generation before proxying to the worker. Requests return 403 EINVOICE_DISABLED when eInvoice generation is disabled, 403 EINVOICE_FORMAT_NOT_ALLOWED when the requested format is not listed in settings.invoicing.eInvoice.allowedFormats, 409 INVOICE_NOT_ISSUED when a draft invoice requests XML or hybrid eInvoice output, and 422 EINVOICE_READINESS_FAILED when the issued invoice snapshot or organization settings are missing required readiness data such as IBAN or Peppol routing addresses. Draft invoices only support pro forma PDF download; the final invoice number is assigned during issue.

Issued invoices keep their party snapshot. To copy or correct a buyer Peppol routing address for an already issued invoice, use the normal correction endpoint. The correction updates the invoice snapshot only; it does not silently mutate the linked client record.

{
  "reason": "Copied buyer Peppol routing address from linked client for eInvoice generation",
  "changes": {
    "client": {
      "peppolRoutingAddress": {
        "schemeId": "9930",
        "value": "DE987654321"
      }
    }
  }
}

Create Invoice Payment Checkout

POST /api/v1/invoices/:id/payment-checkout creates a hosted payment link for an issued invoice.

The request body is optional:

{
  "amount": 10899,
  "expireInHours": 336,
  "returnUrl": "https://yourapp.com/success",
  "cancelUrl": "https://yourapp.com/cancel"
}

• amount is in minor units. If omitted, the backend uses the invoice's payable outstanding amount.
• Partial payment links are allowed from 50 minor units up to the outstanding amount.
• Empty invoices, fully settled invoices, zero-outstanding invoices, and amounts below the minimum return 400.
• If expireInHours is omitted, the backend uses the effective invoicing setting autoPaymentLinkExpiresInHours, falling back to 336 hours. Explicit values must be between 1 and 3120.
• Reverse-charge, export, exempt, zero-rated, and manual synthetic invoice tax codes are not sent as checkout tax-rate codes; settlement tax allocation still follows the invoice tax snapshot.

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": "digital_service"
    },
    {
      "description": "Manual reduced VAT line",
      "quantity": 1,
      "unitPrice": 10700,
      "amountType": "gross",
      "taxRate": 7,
      "itemType": "goods"
    }
  ]
}

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

Recurring Schedules

Recurring schedule payloads and responses use nextRunDate for the next scheduled processing date. Use startDate when creating a schedule; the backend materializes nextRunDate from the start date and interval. Do not use the older nextRunAt name in integrations.

Updating startDate also moves nextRunDate before any invoices have been generated. Once a schedule has generated invoices, startDate can only move future billing after the current nextRunDate; moving it onto the current cycle or an earlier date returns a validation error.

The cancel endpoint accepts an optional JSON body: { "reason": "..." }. The backend trims the reason, caps it at 500 characters, stores cancellation audit metadata (cancellationRequestedAt, cancelledBy, and cancellationReason), and keeps empty-body cancellation requests backward compatible.

The due-schedule processor generates invoices for active schedules whose nextRunDate is due. It also finalizes cancel_requested schedules whose effectiveFromCycle is due, with nextRunDate fallback for older records. Generated invoices remain drafts until an operator issues them unless the schedule has autoFinalizeInvoices enabled. autoSendInvoices is valid only when autoFinalizeInvoices is also enabled; recurring auto-send is the schedule-level email trigger after automatic issue. Recurring processing does not automatically capture payment-provider funds.

The Admin Panel labels the manual processor action Run Due Schedules because it does not force future scheduled cancellations early. The response keeps processed, completed, failed, and skipped, and also includes cancellationsFinalized so cancellation-only runs are visible in UI summaries and processor metrics.

Credit Notes

Clients

Client tax data may include a buyer Peppol routing address only for customers that receive Peppol BIS 3.0 XML. The value is encrypted like other client compliance fields. Use peppolRoutingAddress, not older generic endpoint names.

{
  "taxInfo": {
    "taxId": { "plaintext": "DE987654321" },
    "taxIdType": "vat",
    "taxCountry": "DE",
    "peppolRoutingAddress": {
      "schemeId": "9930",
      "value": { "plaintext": "DE987654321" }
    }
  }
}

Do not assume the VAT ID is the Peppol address. Use a VAT-number scheme such as 9930 only when the buyer confirms that exact Peppol address. Use 0088 only for a supplied GS1 GLN. Use 0204 for a German Leitweg-ID only when the German public-sector recipient confirms it as their Peppol receiver address.

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",
  "bankIBAN": { "plaintext": "DE89370400440532013000" },
  "eInvoice": {
    "enabled": true,
    "allowedFormats": ["xrechnung", "peppol", "zugferd"],
    "strictValidation": true,
    "sellerPeppolRoutingAddress": {
      "schemeId": "9930",
      "value": { "plaintext": "DE123456789" }
    }
  },
  "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, 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
• Recurring schedule management: invoice:read, invoice:create, invoice:update, invoice:execute
• Recurring processor operations: system:read, system:execute (system API keys or global administrator sessions)

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