Early Access operations

Tollstile does not require a particular cloud, database, or monitoring vendor. Choose the adapter that matches your deployment, then keep the payment state and secrets outside the application process.

Keep payment state durable

memoryLedger() is for local development and tests. Use a durable ledger when more than one process can serve a request or when the process may restart:

• SQLite for a local file, node:sqlite, or Cloudflare D1.
• Postgres for a shared database used by multiple instances.

Apply the ledger schema through your migration process before accepting payments. Back up the database and test restoring it before Early Access.

Store secrets in the host's secret store

Keep quote secrets, provider keys, and facilitator credentials in the secret mechanism supplied by your host. The application should read them as environment variables at startup:

const toll = createTollstile({
  rails,
  ledger,
  secret: process.env.TOLLSTILE_SECRET,
});

Never commit these values, put them in a client bundle, or log request headers. Rotate any key that was exposed during testing.

Run reconciliation on a schedule

Provider timeouts and process crashes can leave charges unknown. Run toll.reconcile() from a scheduler that is independent of request handling. Pick an interval and olderThanMs greater than the slowest handler, and alert when the report has unresolved charges.

const report = await toll.reconcile({ olderThanMs: 15 * 60_000 });
if (report.pending > 0) alertOnCall(report);

The scheduler can be a cron job, a Workers Cron trigger, a container task, or another job runner. It must use the same ledger and provider configuration as the API.

Connect events to monitoring

Use onEvent to forward structured events to the monitoring system you already operate. Tollstile does not choose a vendor or make telemetry calls itself.

const toll = createTollstile({
  rails,
  ledger,
  onEvent: (event) => monitor.record(event),
});

Alert on repeated payment_unavailable, payment_outcome_unknown, PROVIDER_TIMEOUT, and unexpected already_paid rates. Redact credentials, signatures, and provider secrets before exporting event data.

Before inviting Early Access users

• Run the conformance kit and the rail's failure tests.
• Verify a testnet payment, replay, handler failure, restart, and reconciliation.
• Confirm the durable ledger schema is applied and backups are restorable.
• Confirm secrets are injected by the host and absent from logs and repositories.
• Define an owner and response procedure for provider outages and pending charges.
• Publish which rails are verified, experimental, or unavailable in your environment.