Configure the GNU Taler payment gateway for wallet payments, tenant-safe webhooks, refunds, diagnostics, and settlement checks.

GNU Taler

GNU Taler is a wallet-based digital cash gateway for Ledger. Customers pay an invoice from a Taler wallet, the Taler Merchant Backend sends Ledger a tenant-scoped webhook, and Ledger updates the invoice, gateway transaction log, refund state, and settlement metadata.

Use GNU Taler when you need privacy-preserving wallet payments, a deployed Taler Merchant Backend, and auditable payment/refund records inside Ledger.

Requirements

Requirement	Description
Merchant Backend URL	Base URL for the Taler Merchant Backend, without private credentials in the URL
Instance ID	Taler merchant instance used by this Ledger gateway
API Token	Merchant Backend token with permission to create orders, read order status, issue refunds, and create/update webhooks
Currency	Currency accepted by the Taler exchange and configured for Ledger invoices
HTTPS Webhook URL	Public Ledger webhook URL reachable by the Taler Merchant Backend

Keep sandbox and production credentials outside the repository. Use environment variables, secret storage, or the encrypted Ledger gateway configuration.

Fleetbase Hosted Sandbox

Fleetbase provides hosted GNU Taler sandbox services for Ledger testing:

Service	URL	Used For
Merchant Backend	`https://merchant.taler.fleetbase.io`	Ledger gateway API calls, order creation, refunds, webhooks, and settlement checks
Exchange	`https://exchange.taler.fleetbase.io`	Wallet exchange visibility and sandbox exchange diagnostics
Bank	`https://bank.taler.fleetbase.io`	Sandbox wallet funding and bank-side test operations

Ledger talks directly to the Merchant Backend. The exchange and bank endpoints support wallet funding, wallet trust/exchange visibility, sandbox testing, and operator diagnostics.

When a GNU Taler gateway is in sandbox mode and the Merchant Backend URL is left blank, Ledger defaults to https://merchant.taler.fleetbase.io. Live gateways do not use this fallback and should always be configured with your production Merchant Backend URL.

Configure The Gateway

Navigate to Ledger -> Payments -> Gateways.

Click New Gateway and select the taler driver.

Enter the Merchant Backend URL, instance ID, API token, and the currencies this gateway should accept. For Fleetbase hosted sandbox testing, you can leave the Merchant Backend URL blank or use https://merchant.taler.fleetbase.io.

Set the environment to sandbox for test wallets or live for production wallets.

Save the gateway, then open the gateway details screen.

Run Test Credentials, Create Test Order, and Register Webhook before enabling the gateway for invoices.

Admin Diagnostics

The Taler gateway details screen includes operational checks for:

Diagnostic	Meaning
Credential status	Ledger can reach the Merchant Backend with the configured token
Webhook registration	Ledger registered or updated the Merchant Backend webhook callback
Last webhook received	Most recent Taler webhook accepted by Ledger
Last payment event	Most recent Taler payment event recorded in `GatewayTransaction`
Last refund event	Most recent Taler refund event, including wallet refund URI data
Last settlement check	Most recent reconciliation check against Taler order status or wire metadata

Non-Taler gateways may not expose every diagnostic action. Unsupported actions return an unsupported response instead of changing gateway state.

Webhook Payload

Provisioned GNU Taler webhooks must post enough data for exact tenant-safe routing:

{
  "order_id": "order_123",
  "company_uuid": "company_uuid",
  "gateway_id": "gateway_public_id",
  "event_type": "pay"
}

gateway_uuid can be used instead of gateway_id when the UUID is the identifier available to the provisioning flow. For provisioned webhooks, order_id, company_uuid, and one gateway identifier are required.

Ledger rejects ambiguous multi-company Taler callbacks rather than selecting the first active gateway. Failed resolution is recorded as a failed gateway transaction so operators can diagnose unknown gateway, wrong company, or missing routing metadata.

Duplicate Taler notifications are idempotent. Ledger keeps the gateway transaction key and includes gateway/company scope in duplicate handling and logs.

Payment Flow

Ledger creates a Taler order for the invoice amount and stores the order reference.
The public invoice page shows the Taler payment URI or QR code.
The customer pays with a Taler wallet.
The Merchant Backend posts the tenant-scoped webhook to Ledger.
Ledger verifies the order state, records the gateway transaction, and marks the invoice paid or partially paid according to the normalized amount.
A Ledger transaction and journal entry are created for the invoice payment.

If the webhook reports an unpaid or unknown order, Ledger records the event and leaves the invoice unpaid.

Refunds

Taler refunds have two separate stages:

Stage	Ledger Behavior
Backend refund requested or approved	Ledger records the refund gateway transaction and normalized refund amount
Wallet refund URI returned	The internal refund response includes `taler_refund_uri` and `refund_url` for customer wallet processing
Wallet accepted	Ledger updates refund status when the accepted state is observable
Failed or expired	Ledger records the failed or expired outcome and keeps the invoice/payment history auditable

Partial refunds reduce the paid balance without forcing the invoice to fully refunded. Full refunds move the invoice to a refunded state once cumulative refunded amount reaches the paid amount. Refund reversals are linked to Ledger transactions and journal entries.

Settlement And Reconciliation

Settlement verification checks paid Taler orders against the Merchant Backend order status. Ledger records the last settlement status, check timestamp, deposit totals, wire transfer identifiers, and raw Taler settlement fields when the backend exposes them.

Some sandbox or backend responses may not include a stable wire transfer identifier. In that case Ledger marks the record as settlement checked rather than wire reconciled and stores the best available Taler fields for audit.

Sandbox E2E Validation

Live sandbox validation is opt-in and should not run in normal CI. Configure the sandbox from environment variables or an encrypted gateway record:

TALER_E2E_ENABLED=true
TALER_E2E_BACKEND_URL=https://merchant.taler.fleetbase.io
TALER_E2E_INSTANCE_ID=default
TALER_E2E_API_TOKEN=...
TALER_E2E_COMPANY_UUID=...

The acceptance flow is:

Create or select a Taler gateway.
Create an invoice.
Start payment and pay with a sandbox wallet.
Receive the webhook and confirm the invoice moves to paid.
Issue a partial or full refund.
Confirm the refund URI is returned and the Ledger reversal is created.
Verify settlement or reconciliation metadata after the settlement check runs.

Never commit real sandbox URLs, API tokens, wallet secrets, or private Merchant Backend credentials.

Production Runbook

Use HTTPS for the Ledger webhook URL.
Scope the Merchant Backend token to only the permissions needed by Ledger.
Register webhooks from the Ledger gateway details screen so company_uuid and gateway identifiers are included.
Confirm diagnostics before enabling the gateway for public invoices.
Keep gateway records company-scoped and avoid sharing one Merchant Backend instance across companies without tenant-safe webhook metadata.
Monitor GatewayTransaction rows for failed webhooks, duplicate delivery, refund state, and settlement status.

GNU Taler

On this page