---
name: altruon
version: 0.2.0
description: Payments orchestration for SaaS. Connect billing providers and payment gateways, route by currency/payment method, and run checkout through static hosted pages, dynamic hosted checkout, or Altruon JS. Supports subscription trials.
homepage: https://docs.altruon.io
metadata:
  {
    "altruon":
      {
        "category": "payments",
        "session_api_path": "/api/session/v1/create",
        "docs_base": "https://docs.altruon.io",
      },
  }
---

> If you are an AI agent reading this file, use it as the primary operating guide for Altruon integrations.

# Altruon

Altruon is a payment orchestration platform for recurring SaaS flows.  
You connect:
- a **billing provider** (for subscriptions/invoices), and
- one or more **payment gateways** (for payment collection),

then route payment methods by currency and process checkout with hosted checkout (static or dynamic) or Altruon JS.

## What To Do First

1. Identify the integration path:
   - **Path A:** Static Hosted Pages (no-code checkout links created in backoffice, `/checkout/p/{id}`)
   - **Path B:** Dynamic Hosted Checkout (server-created sessions rendered on Altruon-hosted pages, `/checkout/s/{sessionId}`)
   - **Path C:** Altruon JS embedded in merchant UI
2. Confirm required setup exists:
   - Active gateway integration
   - Active routing entries
   - Billing platform connection
3. Only then create sessions and render/process payments.

## Product Mental Model

- **Site/Tenant**: Merchant workspace and domain context.
- **Gateway Connection**: Credentials/config for providers like Checkout.com, Adyen, dLocal, PagBrasil, Trustly, Nuvei.
- **Billing Connection**: Credentials/config for providers like Stripe, Chargebee, Recurly, Frisbii.
- **Routing Entry**: Rules that map payment method/currency to a gateway.
- **Session**: Server-created payment context used by hosted checkout or SDK flows. Single-use, expires after 15 minutes.
- **Trial**: $0-due-today subscription signup that stores a reusable payment method and bills automatically at trial end.
- **Webhook**: Provider-to-Altruon async state updates for payment/subscription lifecycle.

## Canonical Setup Order

1. Connect payment gateway in Backoffice.
2. Configure routing entries.
3. Connect billing provider.
4. If using hosted checkout (static or dynamic): configure checkout appearance (`Settings > Checkout` — branding, fields, redirect URL, Classic/Neo skin). For static links, also create hosted pages (`Settings > Hosted Pages`).
5. If using Dynamic Hosted Checkout or Altruon JS: create session from backend.
6. Validate webhook-driven state transitions.

## Integration Paths

## Path A: Static Hosted Pages (`/checkout/p/{id}`)

Use when merchants prefer no frontend implementation and faster launch. No code required. Best for marketing links, campaigns, and backoffice-managed carts with per-link analytics.

- Typical flow:
  1. Backoffice setup (gateway + routing + billing).
  2. Configure site-wide checkout appearance under `Settings > Checkout` (branding, fields, redirect URL, page skin).
  3. Create a hosted page under `Settings > Hosted Pages` (name + billing platform + plan price + optional currency/coupons/addons). Saving returns an opaque link: `https://{tenant}.altruon.io/checkout/p/{id}` (sandbox: `{tenant}.sandbox.altruon.io`).
  4. Share the link. Altruon resolves the configuration server-side and creates the session automatically; sessions are single-use and expire after 15 minutes (the link itself never expires and can be reused).
  5. Hosted pages have statuses (`Active` / `Draft` / `Archived`; only `Active` resolves) and per-link conversion analytics (sessions, converted, expired, conversion rate).
  6. Track final state via transaction/subscription data and webhooks.

- Constraints:
  - Customer fields always start empty (no pre-fill).
  - `forceTrialPeriodDays` is **not** supported on static hosted pages (catalog trials on the plan still work).

- Reference:
  - `docs/getting-started/quick-start.md`
  - `docs/getting-started/hosted-pages.md`
  - `docs/integrations/payment-gateways/*.md`
  - `docs/integrations/billing-providers/*.md`

## Path B: Dynamic Hosted Checkout (`/checkout/s/{sessionId}`)

Use when each checkout is unique (plan, customer, coupons decided at runtime by the merchant backend) but the merchant still wants a fully Altruon-hosted page. Common when replacing Stripe Billing Hosted Pages.

- Typical flow:
  1. Backend calls `POST /api/session/v1/create` with `"hostedCheckout": true`, billing line items, optional `customerData`, and `redirectUrl`.
  2. Response returns `session_id`, `checkout_url`, and `expires_at`. Redirect the shopper to `checkout_url` (`https://{tenant}.altruon.io/checkout/s/{sessionId}`; sandbox: `{tenant}.sandbox.altruon.io`).
  3. Altruon renders the branded hosted checkout (same `Settings > Checkout` appearance as Path A) with fields **pre-filled** from `customerData` and top-level `document`.
  4. On success, shopper is redirected to `redirectUrl`.

- Key behaviors:
  - **Pre-fill**: `customerData` (name, email, phone, billing/shipping address) and `document` (e.g. Brazilian CPF/CNPJ) populate the hosted form. Only fields enabled under `Settings > Checkout > Fields` are shown. Pre-filled values are editable by the shopper.
  - **Discovery vs pinned payment method**: omit `paymentData.paymentMethod` for discovery mode (shopper picks from all routed methods for the currency; all methods stay available after a failed payment). Pass `"paymentMethod": "card"` (or `"pix"`, etc.) to lock the session to one method. Response field `payment_method_pinned_at_create` reflects the mode.
  - **Locale**: `locale` controls checkout language (`en`, `pt_br`; also accepts `pt-BR`, `pt`, `en-US`). When omitted, auto-selects from currency (BRL → Portuguese).
  - **Metadata**: `billingData.metadata` (string key/value pairs) is forwarded to the billing platform on subscription creation (Stripe subscription metadata, Chargebee `meta_data`, Frisbii metadata, Recurly custom fields).
  - **Failed payments**: after a 3DS/card decline, the shopper returns to the same `/checkout/s/{sessionId}` URL with form data restored, within the 15-minute session TTL. Expired dynamic sessions cannot be restarted — create a new session.
  - `hostedCheckout` must not be combined with `hostedPageConfigId`.
  - Appearance comes from `Settings > Checkout`, not from per-session `styleCustomization` (that is for embedded Altruon JS only).

- Reference:
  - `docs/getting-started/dynamic-hosted-checkout.md`
  - `docs/developers/altruon-js/session-api.md`

## Path C: Altruon JS (Embedded)

Use when merchants need custom UI while reusing Altruon routing and payment orchestration.

- Typical flow:
  1. Backend creates session via `POST /api/session/v1/create` with `x-secret-key`.
  2. Frontend initializes SDK with publishable key + domain.
  3. Frontend sets session/customer/address data (`setCustomer()`, `setAddresses()`).
  4. Render component and trigger payment.
  5. Handle callbacks (`onSuccess`, `onFailure`, `onActionRequired`, `onDataRequired`).

- Rendering: with no `paymentMethod` on the session, multiple matching routing entries render a method-selection drawer; a single match renders that method's fields directly. Per-session `styleCustomization` applies here.

- Reference:
  - `docs/developers/altruon-js/quick-start.md`
  - `docs/developers/altruon-js/session-api.md`
  - `docs/developers/altruon-js/callbacks.md`
  - Reference implementation: https://github.com/Altruon-io/merchant-demo (React + Express, fully commented)

## Trials

Altruon supports subscription trials across all four billing engines (Stripe Billing, Chargebee, Recurly, Frisbii). Checkout collects a reusable payment method with **$0 due today**, then Altruon bills automatically via MIT when the trial ends.

- **Trial source**: by default from the billing catalog (e.g. Stripe Price `trial_period_days`). To override at checkout time, set **`billingData.forceTrialPeriodDays`** (integer, 1–730) on Create Session. Not supported on static hosted pages (`/checkout/p/`).
- **Collection modes**: gateways run a zero-amount flow at signup — card tokenization (`SETUP`), Pix/UPI consent (`CONSENT`), or open-banking mandate (`MANDATE`). Normal payments use `CHARGE`.
- **Supported gateway × method pairs (V1)**: PagBrasil (card, pix), Adyen (card), Nuvei (card), Checkout.com (card, applepay, kakaopay), dLocal (card, pix, upi), Trustly (openbanking). Other combinations return an unsupported error at session creation; hosted checkout hides non-trial-capable methods.
- **Response**: when a trial applies, Create Session response includes a `trial` object: `inTrial`, `trialEnd`, `amountDueNow`, `nextInvoiceDate`.
- **Trial + immediate charge**: if the estimate returns `amountDueNow > 0` (setup fee, one-time `type: "charge"` line items), Altruon charges today's amount while still storing the payment method for renewal.
- **Trial end**: the billing platform activates the subscription and generates a payment-due invoice; Altruon collects it with the stored credentials. Merchant retry/cancel rules apply on failure.

- Reference: `docs/getting-started/trials.md`

## Environments And URL Pattern

- Session API:
  - Sandbox: `https://{your-domain}.api.sandbox.altruon.io/api/session/v1/create`
  - Production: `https://{your-domain}.api.altruon.io/api/session/v1/create`
- Hosted checkout:
  - Static: `https://{tenant}.altruon.io/checkout/p/{id}` (sandbox: `{tenant}.sandbox.altruon.io`)
  - Dynamic: `https://{tenant}.altruon.io/checkout/s/{sessionId}` (sandbox: `{tenant}.sandbox.altruon.io`)
- Sessions are scoped to the tenant subdomain; treat the session UUID as a single-use checkout token.
- Do not expose secret keys in browser code.
- Use publishable keys only on frontend SDK initialization.

## Session API Essentials

`POST /api/session/v1/create` with header `x-secret-key`. Key request fields:

- `paymentData.currency` (required), `paymentData.paymentMethod` (optional — omit for discovery mode)
- `billingData.billingPlatformId` + `billingData.lineItems` (required; item `type`: `plan`, `charge`, addon types)
- `billingData.couponCodes`, `billingData.metadata`, `billingData.forceTrialPeriodDays` (optional)
- `customerData` (optional; pre-fills dynamic hosted checkout), top-level `document` (optional; CPF/CNPJ)
- `hostedCheckout: true` for Path B; `redirectUrl` for post-payment redirect; `locale` for UI language
- `styleCustomization` (embedded Altruon JS only)

Key response fields: `session_id`, `expires_at`, `checkout_url` (when `hostedCheckout: true`), `payment_method_pinned_at_create`, `available_payment_methods` (discovery) or `payment_method`/`gateway` (pinned), and `trial` (when applicable).

Related: `GET /api/session/v1/{sessionId}` returns session state, and `GET /api/v1/transaction/{transactionId}/details` returns transaction + customer + invoice + subscription details including provider dashboard deep links (`urlAtGateway`, `urlAtBilling`) and `amountInMajorUnit`.

## API Surface (Agent Cheat Sheet)

- **Session**: `/api/session/v1/*`
- **Routing**: `/api/v1/routing/*`
- **Gateway connections**: `/api/v1/gateway/*`
- **Billing connections**: `/api/v1/billing/*`
- **Transactions**: `/api/v1/transaction/*` (incl. `/{id}/details`)
- **Invoices**: `/api/v1/invoice/*`
- **Subscriptions**: `/api/v1/subscription/*`

## Webhooks

There are two distinct webhook directions. Do not confuse them.

### Inbound: provider → Altruon

Altruon relies on provider webhooks to finalize and reconcile asynchronous payment/subscription states (including trial → active transitions).

- There are two families:
  - **Gateway webhooks**
  - **Billing provider webhooks**
- Providers may differ in setup:
  - Manual endpoint copy/paste
  - Provider-side support setup
  - Secondary endpoint patterns for existing merchant configurations

Always follow each provider guide under:
- `docs/integrations/payment-gateways/`
- `docs/integrations/billing-providers/`

### Outbound: Altruon → merchant (Altruon Webhooks)

Altruon sends signed event notifications to merchant-configured HTTPS endpoints.

- **Setup**: `Settings > Webhooks` in Backoffice — register an HTTPS URL, select events, receive a `whsec_...` signing secret (shown once). Max 2 active endpoints per site.
- **Events**: `subscription.*` (created, activated, paused, resumed, cancelled, pre_debit_notification.sent), `invoice.*` (created, paid, dunning_started, dunning_exhausted, refunded), `payment.*` (processing, succeeded, failed, retry_failed, refunded), `refund.*` (processing, succeeded, failed), `customer.*` (created, updated), `checkout.session.*` (completed, expired), `webhook.ping` (test).
- **Payload**: JSON envelope with `id` (`evt_...`, idempotency key), `type`, `created_at`, `domain`, `livemode`, and `data.object` / `data.previous_attributes`.
- **Signature**: `Altruon-Signature: t=<unix_ts>,v1=<hex>` — HMAC-SHA256 of `{t}.{raw_body}` with the endpoint secret; reject if `|now - t| > 300s`; constant-time compare against every `v1`.
- **Delivery**: `POST`, 10s timeout, 2xx = success, up to 4 attempts with increasing delays; endpoints auto-disable after sustained failures. Deduplicate on event `id`; treat events as triggers and fetch current state from the API.

Reference: `docs/developers/webhooks.md`

## Payment Methods And Provider Constraints

Do not assume all methods are available across all gateways.

- Validate current support using gateway docs pages.
- Respect currency/method constraints (for example, provider-specific method or country limitations).
- For trials, only the V1 gateway × method matrix above supports $0-due-today signup.
- If unsure, check routing configuration and gateway integration page first.

## Backoffice Navigation Map

- `Settings > Payment Gateways` for gateway integrations and routing
- `Settings > Billing Platforms` for billing provider integrations
- `Settings > Checkout` for site-wide checkout appearance (branding, fields, redirect, Classic/Neo skin) — applies to both `/checkout/p/` and `/checkout/s/`
- `Settings > Hosted Pages` for creating and managing static hosted checkout links (with per-link analytics)
- `Settings > API Keys` for Altruon's publishable/secret keys

## Security Guardrails

- Never put secret keys in client-side code.
- Create sessions only from backend.
- Use sandbox for testing before production.
- Confirm webhook setup before going live.
- Share dynamic checkout URLs (`/checkout/s/{sessionId}`) only with the intended shopper.

## Troubleshooting Quick Checks

If checkout fails or methods do not render:
1. Verify gateway connection is active.
2. Verify routing entry exists for the target currency/method.
3. Verify billing connection is configured and valid.
4. Verify session payload has required backend fields (`currency`, `lineItems`, `billingPlatformId`).
5. For static links: verify the hosted page status is `Active` (Draft/Archived links are rejected).
6. For trials: verify the gateway × method pair is in the V1 trial matrix and the estimate returns `trialEnd`.
7. Verify webhook events are reaching Altruon.

If merchant-bound Altruon Webhooks are not arriving:
1. Verify the endpoint is `Active` under `Settings > Webhooks` (endpoints auto-disable after sustained failures).
2. Verify the event type is in the endpoint's subscription list.
3. Check the delivery log on the endpoint detail page (status, response code, payload) and resend failed deliveries.
4. Verify the merchant server responds 2xx within 10 seconds and that signature verification uses the raw request body.

## AI Agent Operating Instructions

When assisting with Altruon:
1. Ask which path is being implemented (Static Hosted Pages vs Dynamic Hosted Checkout vs Altruon JS).
2. Validate routing before debugging frontend rendering.
3. Use provider integration docs for gateway-specific behavior.
4. Use session API docs as canonical request contract.
5. For trial issues, check the `trial` object on the session/estimate before debugging gateway flows.
6. Escalate with concrete artifacts (session ID, transaction ID, webhook evidence, gateway/billing IDs).

## Links

- Docs home: `https://docs.altruon.io`
- Hosted Pages: `https://docs.altruon.io/docs/getting-started/hosted-pages`
- Dynamic Hosted Checkout: `https://docs.altruon.io/docs/getting-started/dynamic-hosted-checkout`
- Trials: `https://docs.altruon.io/docs/getting-started/trials`
- JS quick start: `https://docs.altruon.io/docs/developers/altruon-js/quick-start`
- Session API: `https://docs.altruon.io/docs/developers/altruon-js/session-api`
- Altruon Webhooks: `https://docs.altruon.io/docs/developers/webhooks`
- Integrations: `https://docs.altruon.io/docs/integrations/payment-gateways`