Terminal Mode

Route all merchant payments to a single owner wallet, ideal for POS setups.

Overview

Terminal mode is designed for businesses where multiple staff members (e.g. waiters in a restaurant) each have their own merchant account but all payments should ultimately flow to a single owner wallet. Instead of each merchant withdrawing funds individually, every verified payment is automatically forwarded to the partner's master forward address.

Restaurant Scenario

Imagine a restaurant with 5 waiters. Each waiter is onboarded as a separate merchant so they can create payment requests from their own device. However, the restaurant owner wants all USDC to arrive in a single wallet they control.

With terminal mode enabled:

  • Waiter A creates a payment request for table 3.
  • The customer pays USDC to waiter A's embedded wallet.
  • Once proof is verified, JoPay automatically forwards the USDC from waiter A's wallet to the owner's master address.
  • The waiter's individual withdraw address setting is ignored.
Terminal mode uses the same auto-forward mechanism as regular auto-forward, but the destination is always the partner-level master address — it overrides any per-merchant withdraw address.

Requirements

  • Embedded wallets only — auto-forward (and therefore terminal mode) only works with Sequence WaaS embedded wallets. External wallets cannot be swept server-side.
  • Valid EVM address — the master forward address must be a valid 0x-prefixed, 40-character hex address.
  • Not self-referential — the master address cannot be the same as any merchant's own wallet address (forwarding to self is rejected).
  • Trails API key — the server must have a valid TRAILS_API_KEY configured to execute the on-chain sweep.

Setup Steps

Set the master forward address

A JoPay admin sets the auto_forward_master_address field on the partner record. This is the EVM wallet address that will receive all auto-forwarded USDC.

Onboard merchants with embedded wallets

Each staff member (e.g. waiter) signs up using a partner invite link and authenticates with Sequence. They receive an embedded wallet automatically.

Merchants create payment requests as usual

Staff create POS-mode payment requests from the merchant dashboard. Customers pay to the merchant's embedded wallet address shown on the payment page.

Auto-forward triggers on verification

When proof is verified (either via Trails on-chain check or manual approval), JoPay automatically initiates a transfer from the merchant's embedded wallet to the partner's master address using the Trails QuoteIntent and ExecuteIntent flow.

Owner receives USDC

The USDC arrives in the owner's master wallet. Individual merchants do not need to perform any withdrawal action.

How It Works Internally

When a payment is verified, the auto-forward system checks for a destination in this order:

  1. Partner master address — if auto_forward_master_address is set on the partner, it always wins. This is terminal mode.
  2. Merchant withdraw address — if no master address is set but the merchant has auto_forward_enabled and a valid withdraw_address, funds go there instead.
  3. No forward — if neither is configured, funds stay in the merchant's embedded wallet until manually withdrawn.
Auto-forward is fire-and-forget. If the Trails API call fails (timeout, network error), the failure is logged but does not block proof verification. The funds remain in the merchant's wallet and can be manually withdrawn or retried.