Skip to content

Architecture

How a payment moves through the Stablecoin Stack

The four actors

Every payment involves four participants. Understanding what each one does — and doesn't do — is the foundation for understanding the system.

Actor What they do
Merchant Creates a payment request. Receives funds and a settlement confirmation. Never interacts with the network directly.
Payer Holds the funds. Signs the payment authorisation on their device. Never submits a network transaction.
Payment Processor Operates the infrastructure. Validates payments. Submits network transactions on behalf of payers. Covers network transaction costs.
Settlement Contract An open, auditable piece of code deployed on a public network. Verifies signatures, moves funds, distributes fees. Cannot be overridden by any off-chain party.

💡 Architectural Note: While there are four distinct technical roles, they do not require four separate business entities. A merchant can easily self-host the stablecoin stack and act as their own Payment Processor. Commercially and legally, the entire system can operate with just two parties: the Payer and the Merchant.

The five phases of a payment

Phase A — The merchant creates a charge

The merchant's system sends a request to the Checkout Engine: amount, currency, destination account, and order reference. The Checkout Engine generates a session, a unique payment reference, and a short-lived token.

The merchant presents this to the payer as a QR code or a deep link.

Phase B — The payer authorises

The payer's wallet scans the QR code or follows the deep link. It retrieves the payment parameters — amount, destination, fees — and displays them clearly.

The payer reviews and confirms. Their device produces two cryptographic signatures:

Authorises the settlement contract to access the payer's funds for this specific payment. Tied to the exact token, the exact amount (including fees), and an expiry time.

This signature is verified by the token contract — independently of the processor.

Authorises the processor to submit this exact operation: this token, this merchant, this amount, this reference. Any alteration to any parameter invalidates the signature.

This signature is verified by the settlement contract — on-chain, in public.

Both signatures are produced entirely on the payer's device. The private key never leaves the device.

Phase C — The processor validates

The payer's wallet sends both signatures to the processor gateway over HTTPS.

The processor validates:

  • All fields are present and correctly formatted.
  • The deadline hasn't passed.
  • The permit nonce matches the current on-chain state.
  • The recovered signer matches the payer's address.
  • The payment reference corresponds to an active session.

Any failure causes immediate rejection. Nothing goes on-chain until every check passes.

Phase D — The settlement contract executes

The processor's Relayer submits a single transaction to the Settlement Contract, paying the network fee from its own account.

The settlement contract executes atomically:

  • Verifies the Binding Signature and checks it hasn't been used before.
  • Calls the token contract with the Permit Signature, granting itself a one-time allowance.
  • Transfers the full amount from the payer's wallet to the contract.
  • Distributes fees to the processor (and acquirer, if applicable).
  • Sends the principal to the merchant's wallet.
  • Records the Binding Signature as used — it can never be replayed.
  • Emits a public event confirming settlement.

Everything in Phase D either completes in full or reverts entirely. There is no partial state.

Phase E — Confirmation reaches everyone

After a configurable number of network confirmations, the Stablecoin Stack's event indexing service picks up the settlement event and notifies the Checkout Engine. The Checkout Engine marks the charge as settled and sends a webhook to the merchant.

The payer's wallet receives a final confirmation over its existing connection.

The flow at a glance

sequenceDiagram
    actor Merchant
    actor Payer
    participant Processor
    participant Settlement Contract

    Merchant->>Processor: Create charge (amount, token, destination)
    Processor-->>Merchant: Session token + QR code

    Merchant->>Payer: Present QR code / deep link
    Payer->>Processor: Retrieve payment parameters
    Processor-->>Payer: Amount, fees, reference, deadline

    Note over Payer: Signs Permit + Binding Signature<br/>on device — key never leaves

    Payer->>Processor: Submit both signatures (HTTPS)
    Processor->>Processor: Validate all fields + signatures

    Processor->>Settlement Contract: Submit transaction (pays network fee)
    Settlement Contract->>Settlement Contract: Verify signatures
    Settlement Contract->>Settlement Contract: Transfer funds atomically
    Settlement Contract-->>Processor: PermittedTransfer event

    Processor-->>Merchant: Settlement webhook
    Processor-->>Payer: Payment confirmed

Key properties of this design

The processor cannot forge a payment

The Binding Signature covers every parameter of the payment — token, merchant address, amount, and reference. Any modification invalidates the signature. A processor cannot change where funds go or how much is taken.

The processor cannot replay a payment

Every time a payment settles, the settlement contract records the Binding Signature's unique digest. Any future attempt to re-use the same signatures causes an immediate revert.

The payer never pays network fees

The processor's Relayer submits the transaction and pays the network fee. The Relayer recovers this cost through the processing fee embedded in the payment amount. The payer holds only the currency they want to spend.

Settlement is atomic

Either every step completes — signature verification, fund transfer, fee distribution, merchant credit — or none of them do. There is no stuck state, no partial transfer, no "payment pending" that never resolves.

Any party can verify settlement

The settlement event is recorded on a public network. The merchant's accountant, the payer's bank, a regulator, or an auditor can all verify independently that a specific payment settled — without asking the processor for records.

Component reference

Component Role Operated by
Checkout Engine Merchant-facing API, session management, webhooks Processor
Payment Widget Payer-facing checkout page, QR code delivery Processor
Payment Gateway Receives signed payloads, validates, queues for broadcast Processor
Relayer Submits on-chain transactions, pays network fees Processor
Settlement Contract Verifies, executes, distributes — atomically Public network (deployed by Processor)
Event Indexer Monitors settlement events, triggers reconciliation Processor
Client Wallet Signs and submits payment authorisations Payer's device
Basic Data Service Public directory of tokens, processors, acquirers Processor / Foundation

Open Standard details → Get Started →