---
name: altruon
version: 0.1.0
description: Payments orchestration for SaaS. Connect billing providers and payment gateways, route by currency/payment method, and run checkout through hosted pages or Altruon JS.
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 either hosted checkout or Altruon JS.

## What To Do First

1. Identify the integration path:
   - **Path A:** Hosted checkout
   - **Path B:** 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.
- **Routing Entry**: Rules that map payment method/currency to a gateway.
- **Session**: Server-created payment context used by hosted checkout or SDK flows.
- **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. Configure checkout settings/payment links (if used).
5. Create session from backend.
6. Render checkout (hosted page or SDK embed).
7. Validate webhook-driven state transitions.

## Integration Paths

## Path A: Hosted Checkout

Use when merchants prefer less frontend implementation and faster launch.

- Typical flow:
  1. Backoffice setup (gateway + routing + billing).
  2. Session and checkout flow from Altruon-hosted routes.
  3. Track final state via transaction/subscription data and webhooks.

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

## Path B: 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.
  4. Render component and trigger payment.
  5. Handle callbacks (`onSuccess`, `onFailure`, `onActionRequired`, `onDataRequired`).

- Reference:
  - `docs/developers/altruon-js/quick-start.md`
  - `docs/developers/altruon-js/session-api.md`
  - `docs/developers/altruon-js/callbacks.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`
- Do not expose secret keys in browser code.
- Use publishable keys only on frontend SDK initialization.

## 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/*`
- **Invoices**: `/api/v1/invoice/*`
- **Subscriptions**: `/api/v1/subscription/*`

## Webhooks

Altruon relies on provider webhooks to finalize and reconcile asynchronous payment/subscription states.

- 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/`

## 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).
- 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 Checkout Hosted page config/payment links
- `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.

## 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. Verify webhook events are reaching Altruon.

## AI Agent Operating Instructions

When assisting with Altruon:
1. Ask which path is being implemented (Hosted vs SDK).
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. Escalate with concrete artifacts (session ID, transaction ID, webhook evidence, gateway/billing IDs).

## Links

- Docs home: `https://docs.altruon.io`
- 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`
- Integrations: `https://docs.altruon.io/docs/integrations/payment-gateways`