Payments & Transactions

The Payments module covers three interconnected areas: payment gateways for processing real money, wallets for tracking internal balances, and transactions as the immutable audit trail of every wallet movement.

Navigate to Ledger → Payments to access gateways, wallets, and transactions.

Core Components

Payment Gateways

External payment processors — Stripe, QPay, and Cash — integrated with encrypted credentials and sandbox/live environments. All three drivers support both purchase and refund capabilities. Stripe additionally supports tokenization, setup intents, checkout sessions, webhooks, and recurring payments. Each gateway interaction is logged as a GatewayTransaction for idempotency and audit. See Payment Gateways.

Wallets

Digital balance accounts tied to drivers, customers, your company, or individual users. Every wallet operation (credit, topup, transfer, payout) creates one or more journal entries maintaining double-entry integrity. Wallets can be frozen to block all operations. See Wallets.

Transactions

The complete, immutable ledger of every wallet movement. Transactions are never edited or deleted — they are the full audit trail for compliance and reconciliation. See Transactions.

A Typical Payment Lifecycle

Customer pays via Stripe (e.g. invoice payment or wallet top-up)
  → GatewayTransaction logged (idempotency check)
    → PaymentSucceeded event fires
      → Ledger Transaction created (credit direction)
        → Journal Entry posted by the relevant service
          (invoice → invoice_payment / wallet → general / storefront → storefront_sale)

The exact journal entries differ per source — see the per-flow examples on Wallets and Invoices.

Webhook Security

All payment gateways send webhooks to confirm transactions. Each driver verifies its webhook signature before processing (Stripe via Webhook::constructEvent, QPay via its own driver). Duplicate webhooks are deduplicated using GatewayTransaction::isProcessed() — a check on (gateway_reference_id, event_type) — so each event is processed exactly once.

Multi-Currency

Wallets are denominated in a single currency. If you operate in multiple currencies, create separate wallets per currency. Transaction records include exchange_rate, settled_currency, and settled_amount fields for multi-currency reconciliation.