Architecture Overview

Understand how Expereon fits into your system and how data flows between parties.

Where Expereon fits

Expereon acts as a centralized B2B financial layer between buyer and seller organizations. Your system integrates with Expereon via REST API — you don't need to build direct connections with each counterparty.

graph LR
    subgraph SELLER["Seller Systems"]
        S_ERP["ERP / Accounting"]
        S_APP["Seller App"]
    end

    subgraph EXPEREON["Expereon Platform"]
        API["REST API
(api.expereon.com)"]
        INV["Invoice
Management"]
        PAY["Payment &
Settlement"]
        TREAS["Treasury &
Balances"]
        CONN["Connection
Registry"]
        WH["Webhook
Delivery"]
        STORE["File
Storage"]
    end

    subgraph BUYER["Buyer Systems"]
        B_ERP["ERP / Accounting"]
        B_APP["Buyer App"]
    end

    S_ERP -->|"Create invoices
Manage line items"| API
    S_APP -->|"Check statuses
View analytics"| API
    API --> INV
    API --> PAY
    API --> TREAS
    API --> CONN
    API --> STORE
    INV --> WH
    PAY --> WH
    TREAS --> WH
    WH -->|"invoice.approved
payment.settled"| S_ERP
    WH -->|"invoice.created
payment.due"| B_ERP
    B_APP -->|"Approve invoices
Settle payments"| API
    B_ERP -->|"Fetch invoices
Export reports"| API

    style EXPEREON fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#e2e8f0
    style SELLER fill:#1a2332,stroke:#22c55e,stroke-width:1px,color:#e2e8f0
    style BUYER fill:#1a2332,stroke:#f59e0b,stroke-width:1px,color:#e2e8f0
    style API fill:#3b82f6,stroke:#2563eb,color:#ffffff
            

API domain map

The Expereon API is organized into functional domains. Each domain groups related endpoints that manage a specific aspect of the B2B financial workflow.

graph TB
    subgraph CORE["Core Workflow"]
        INV["Invoices
/api/v1/invoices"]
        ACTIONS["Invoice Actions
approve, dispute, cancel"]
        BULK["Bulk Operations
bulk approve, archive"]
        ITEMS["Line Items
add, update, delete"]
    end

    subgraph FINANCIAL["Financial"]
        PAY["Payments
/api/v1/payments"]
        BAL["Balances
/api/v1/treasury/.../balances"]
        TXN["Transactions
/api/v1/treasury/.../transactions"]
        WDR["Withdrawals
submit, approve, reject"]
        REF["Refunds
create, approve, reject"]
    end

    subgraph SETTINGS["Settings & Integration"]
        KEYS["API Keys
/api/v1/settings/api-keys"]
        HOOKS["Webhooks
/api/v1/settings/webhooks"]
        LOGS["API Logs
/api/v1/settings/api-logs"]
        STORE["Storage
/api/v1/storage"]
    end

    INV --> ACTIONS
    INV --> ITEMS
    INV --> BULK
    ACTIONS -->|"settlement"| PAY
    PAY --> TXN
    PAY --> BAL

    style CORE fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#e2e8f0
    style FINANCIAL fill:#1e293b,stroke:#22c55e,stroke-width:2px,color:#e2e8f0
    style SETTINGS fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#e2e8f0
    style INV fill:#3b82f6,stroke:#2563eb,color:#ffffff
    style PAY fill:#22c55e,stroke:#16a34a,color:#ffffff
            

Typical integration architecture

Below is a recommended architecture for integrating Expereon into your backend. The pattern works for both buyers and sellers.

graph TB
    subgraph YOUR_SYSTEM["Your Backend"]
        APP["Your Application"]
        SYNC["Expereon Sync
Service"]
        DB[("Your Database")]
        QUEUE["Job Queue"]
    end

    subgraph EXPEREON_API["Expereon"]
        REST["REST API"]
        HOOKS["Webhooks"]
    end

    APP -->|"1. Create invoice"| SYNC
    SYNC -->|"2. POST /api/v1/invoices"| REST
    REST -->|"3. Response with ID"| SYNC
    SYNC -->|"4. Store mapping"| DB

    HOOKS -->|"5. invoice.approved"| SYNC
    SYNC -->|"6. Update local status"| DB
    SYNC -->|"7. Trigger downstream"| QUEUE

    style YOUR_SYSTEM fill:#1e293b,stroke:#334155,stroke-width:1px,color:#e2e8f0
    style EXPEREON_API fill:#1a2332,stroke:#3b82f6,stroke-width:2px,color:#e2e8f0
    style REST fill:#3b82f6,stroke:#2563eb,color:#ffffff
    style HOOKS fill:#3b82f6,stroke:#2563eb,color:#ffffff
            

API request flow

Every API call follows the same pattern: authenticate, send request, handle response. Here's the full lifecycle of a typical API call.

sequenceDiagram
    participant Client as Your System
    participant API as Expereon API
    participant Auth as Auth Layer
    participant Service as Business Logic

    Client->>API: POST /api/v1/invoices
X-API-Key + X-API-Secret
    API->>Auth: Validate API credentials
    Auth-->>API: Organization context

    alt Valid credentials
        API->>Service: Process request
        Service-->>API: Invoice created
        API-->>Client: 200 OK + invoice JSON
    else Invalid credentials
        Auth-->>API: Reject
        API-->>Client: 401 Unauthorized
    end

    Note over Client,API: Idempotent: same requestId = same response
            

Invoice lifecycle

Invoices move through a well-defined state machine. Each transition triggers a webhook event that your system can listen to.

stateDiagram-v2
    [*] --> DRAFT : Seller creates

    DRAFT --> SUBMITTED : Seller submits
    DRAFT --> CANCELLED : Seller cancels

    SUBMITTED --> APPROVED : Buyer approves
    SUBMITTED --> APPROVED_WITH_ADJUSTMENT : Buyer approves with changes
    SUBMITTED --> DISPUTED : Buyer disputes
    SUBMITTED --> CANCELLED : Seller cancels
    SUBMITTED --> INFO_REQUESTED : Buyer requests info

    INFO_REQUESTED --> SUBMITTED : Seller responds

    DISPUTED --> SUBMITTED : Seller corrects and resubmits
    DISPUTED --> CANCELLED : Either party cancels

    APPROVED --> SETTLED : Payment completes
    APPROVED_WITH_ADJUSTMENT --> SETTLED : Payment completes
    APPROVED --> CANCELLATION_REQUESTED : Cancellation requested
    APPROVED_WITH_ADJUSTMENT --> CANCELLATION_REQUESTED : Cancellation requested

    CANCELLATION_REQUESTED --> CANCELLED : Counterparty accepts
    CANCELLATION_REQUESTED --> APPROVED : Counterparty rejects

    SETTLED --> ARCHIVED : Auto or manual archive
    CANCELLED --> ARCHIVED : Auto or manual archive

    ARCHIVED --> [*]
            

Payment and settlement flow

Expereon supports multiple settlement workflows: settle individual invoices, bulk settle selected invoices, or settle all due invoices at once. Funds move through a reservation system to ensure safe, atomic transfers.

sequenceDiagram
    participant Buyer as Buyer Org
    participant API as Expereon API
    participant Treasury as Treasury
    participant Seller as Seller Org

    Buyer->>API: Approve invoice
    API->>Treasury: Reserve funds from buyer balance

    alt Sufficient balance
        Treasury-->>API: Reservation confirmed
        API-->>Buyer: 200 Invoice approved

        Note over Treasury: Settlement window (configurable)

        Buyer->>API: POST /payments/settle-all-due
or POST /payments/bulk-settle
        API->>Treasury: Execute settlement
        Treasury->>Treasury: Credit seller balance
        Treasury->>Treasury: Debit buyer reservation

        API-->>Seller: Webhook: payment.settled
        API-->>Buyer: Webhook: payment.settled
    else Insufficient balance
        Treasury-->>API: Insufficient funds
        API-->>Buyer: 400 Insufficient balance
    end

    Note over Buyer,Seller: Failed settlements can be retried
via POST /payments/retry-failed
            

Treasury and balance management

Each organization has one or more balances in their treasury. Balances hold funds that are used for invoice settlements, withdrawals, and refunds.

graph LR
    subgraph ORG["Organization Treasury"]
        BAL["Balances
(available, collateral)"]
        RES["Reservations
(held funds)"]
    end

    DEP["Deposit"] -->|"Fund balance"| BAL
    BAL -->|"Reserve on
invoice approval"| RES
    RES -->|"Execute
settlement"| SELLER["Seller Balance"]
    BAL -->|"Withdrawal
request"| WDR["Bank Account"]
    SELLER -->|"Refund
request"| BAL

    style ORG fill:#1e293b,stroke:#22c55e,stroke-width:2px,color:#e2e8f0
    style BAL fill:#22c55e,stroke:#16a34a,color:#ffffff
    style RES fill:#f59e0b,stroke:#d97706,color:#1e293b
            

Webhook delivery model

Expereon pushes events to your registered webhook URL. Your endpoint must respond with 2xx within 10 seconds. Failed deliveries are retried with exponential backoff.

sequenceDiagram
    participant EXP as Expereon
    participant WH as Your Webhook Endpoint

    EXP->>WH: POST event payload
+ X-Signature header

    alt Success
        WH-->>EXP: 200 OK
        Note over EXP: Delivered. Done.
    else Failure (5xx / timeout)
        WH-->>EXP: 500 or timeout
        Note over EXP: Retry #1 after 1 min
        EXP->>WH: POST (retry)
        WH-->>EXP: 200 OK
    end

    Note over EXP,WH: Retries: 1m, 5m, 30m, 2h, 12h (max 5 attempts)
            

Idempotency

All mutation endpoints support idempotency via a requestId field in the request body. If you send the same requestId twice, the second call returns the original response without creating a duplicate resource.

POST /api/v1/invoices
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "connectionId": "...",
  "lineItems": [...]
}

// Retry with same requestId → returns original invoice, no duplicate created

Error handling

The API returns standard HTTP status codes. Error responses include a structured body with an error code and human-readable message.