Card payments solve this with an acquirer that calls the shop back. On Solana, a shop can do the same job itself, with no middleman and no customer data, using one idea from Solana Pay: a fresh, random reference key for every order.

This walkthrough comes from Wen Open Lab, a free set of models built by the Wen community to show what open Solana tools can do for ordinary people and small businesses.

⚠️ Educational example, not audited, not a payment product. Use devnet and a new, empty wallet. Real payments have tax, consumer-law and licensing rules that code does not replace.

The idea in four steps

1. Create a payment link for the order, with a unique random reference.
2. Show it as a link or QR code. The customer's wallet adds the reference to the transfer.
3. Find the transaction on-chain by that reference.
4. Validate recipient, amount, token, reference and memo, then mark the order paid.

The reference is a public key that nobody signs with. It rides along in the transaction as a read-only account, so the chain can be searched by it. It identifies the order without saying anything about the customer.

Step 1: a payment request per order

export async function createPaymentRequest(orderId: string, recipient: Address, amount: number, splToken?: Address) {
  const reference = (await generateKeyPairSigner()).address;   // random, never reused
  const url = encodeURL({
    recipient, amount, splToken, reference,
    label: 'Wen Open Lab demo shop',
    message: `Order ${orderId}`,
    memo: `order:${orderId}`,
  });
  return { orderId, recipient, amount, splToken, reference, url: url.toString() };
}

• splToken omitted → the payment is in SOL; set → the payment is in that SPL token.
• memo puts the order number on-chain. It is public: an order number, never a name or an address.
• The result is a solana: URL. Any QR library can turn it into a code for a checkout page or a printed receipt.

Step 2: wait, find, validate

export async function waitForPayment(req: PaymentRequest, opts: { rpcUrl: string; webhook: string; timeoutMs?: number }) {
  const rpc = createSolanaRpc(opts.rpcUrl);
  const deadline = Date.now() + (opts.timeoutMs ?? 5 * 60_000);
  while (Date.now() < deadline) {
    try {
      const found = await findReference(rpc, req.reference, { commitment: 'confirmed' });
      // throws if recipient, amount, token, reference or memo do not match
      await validateTransfer(rpc, found.signature, {
        recipient: req.recipient, amount: req.amount, splToken: req.splToken,
        reference: req.reference, memo: `order:${req.orderId}`,
      }, { commitment: 'confirmed' });
      await fetch(opts.webhook, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ orderId: req.orderId, status: 'paid', signature: found.signature }),
      });
      return found.signature;
    } catch (e) {
      if (!(e instanceof FindReferenceError)) throw e;   // not found yet: keep waiting
      await new Promise(r => setTimeout(r, 1500));
    }
  }
  throw new Error(`Order ${req.orderId}: payment not found before timeout`);
}

Two details matter more than they look:

• Finding is not trusting. findReference only says "a transaction mentions this key". validateTransfer checks that the money went to the right wallet, in the right token, for the right amount, with the right memo. Skipping validation would let anyone "pay" with a tiny transfer that carries the reference.
• Only "not found yet" is retried. Any other error, including a failed validation, stops the loop instead of being silently ignored.

The webhook call plays the role of an acquirer's callback: the shop's own order system hears "order A-1001 is paid, here is the signature", and the signature is the receipt anyone can look up in an explorer.

What the tests prove

The example repository runs its checks locally, with no network and no funds:

PASS  M4 payment link round-trips: recipient, amount, token, reference, memo
PASS  M4 every order gets a unique reference

The first check builds a link, parses it back and confirms that nothing was lost or changed. The second confirms that two orders never share a reference. The watcher itself needs a live cluster, so try it on devnet: create a request with your devnet address as the recipient, pay it from a second devnet wallet that supports Solana Pay links, and watch the loop find and validate the payment.

Why this is useful to people, not only to developers

• Small sellers can reconcile payments without a processor account and without matching amounts by hand.
• Customers give no card number and no personal data to the shop's server; the receipt is a public signature.
• Bookkeeping gets a clean link between an order number and a transaction that cannot be edited later.

Limits worth stating plainly

• Prices move if the shop accepts a volatile token. A shop that needs stable amounts should accept a stable asset; the model does not convert anything.
• Refunds, disputes and taxes are not in the code. They are the shop's responsibility, as with any payment method.
• Polling every 1.5 seconds is fine for a demo. A busy shop needs its own RPC provider and limits.
• Not audited, not a product. It is a model for learning.

The code (Apache-2.0), the tests and the other Token-2022 models (a soulbound warranty card, creator royalties, B2B invoices) are open in one place: https://github.com/wen-watt/wen-watt.github.io/tree/main/lab/code

On Solana, the Token-2022 program can make the receiving account itself refuse any payment that does not carry an invoice number. Combined with two other built-in extensions, a plain token gets rules that a B2B settlement needs, and no custom on-chain program is required:

1. Required Memo (account extension): incoming transfers must be preceded by a memo instruction, so no invoice number means no payment.
2. Default Account State = Frozen (mint extension): every new account starts frozen, and only the issuer can thaw it. Thawing = approving a counterparty after off-chain checks.
3. Transfer Fee (mint extension): a percentage fee with a hard cap, withheld by the token program itself.

Everything below is an educational model, tested in a local VM and then on devnet. It is not a stablecoin and not a payment product. A real settlement token is issued by a licensed entity.

⚠️ Not audited. Devnet only, with a new, empty wallet.

Step 1: the settlement mint

export const DECIMALS = 6;
export const FEE_BPS = 25;                               // 0.25%
export const FEE_CAP = 50n * 10n ** BigInt(DECIMALS);    // never more than 50 units

const space = getMintLen([ExtensionType.TransferFeeConfig, ExtensionType.DefaultAccountState]);

const ixs = [
  SystemProgram.createAccount({ fromPubkey: issuer, newAccountPubkey: mint,
    space, lamports: rent, programId: TOKEN_2022_PROGRAM_ID }),
  createInitializeTransferFeeConfigInstruction(mint, issuer, issuer, FEE_BPS, FEE_CAP, TOKEN_2022_PROGRAM_ID),
  createInitializeDefaultAccountStateInstruction(mint, AccountState.Frozen, TOKEN_2022_PROGRAM_ID),
  createInitializeMintInstruction(mint, DECIMALS, issuer, /* freeze authority */ issuer, TOKEN_2022_PROGRAM_ID),
];

The detail that matters: the issuer keeps the freeze authority. Without it, "frozen by default" would freeze accounts forever; with it, the issuer becomes the gatekeeper of who may hold the token.

Step 2: a company account that demands an invoice number

const space = getAccountLen([ExtensionType.TransferFeeAmount, ExtensionType.MemoTransfer]);

const ixs = [
  SystemProgram.createAccount({ fromPubkey: company, newAccountPubkey: account,
    space, lamports: rent, programId: TOKEN_2022_PROGRAM_ID }),
  createInitializeAccount3Instruction(account, mint, company, TOKEN_2022_PROGRAM_ID),
  createEnableRequiredMemoTransfersInstruction(account, company, [], TOKEN_2022_PROGRAM_ID),
];

TransferFeeAmount must be in the account size because fee-bearing mints withhold the fee in the recipient account. MemoTransfer is the switch that the seller turns on for its own account. The rule belongs to the receiver, not to the sender's app.

Step 3: approve a counterparty

createThawAccountInstruction(account, mint, issuer, [], TOKEN_2022_PROGRAM_ID);

One instruction. The checks behind it (company registration, contract and so on) stay off-chain; the chain records only the outcome: this account may now send and receive.

Step 4: pay the invoice, memo first

const SPL_MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');

const memo = new TransactionInstruction({
  programId: SPL_MEMO_PROGRAM_ID,
  keys: [{ pubkey: payer, isSigner: true, isWritable: false }],
  data: Buffer.from(`invoice:${invoiceId}`, 'utf8'),
});

const fee = (amount * BigInt(FEE_BPS)) / 10_000n;
const expectedFee = fee > FEE_CAP ? FEE_CAP : fee;

const ixs = [
  memo,   // must be IMMEDIATELY before the transfer
  createTransferCheckedWithFeeInstruction(from, mint, to, payer, amount,
    DECIMALS, expectedFee, [], TOKEN_2022_PROGRAM_ID),
];

Two traps we hit, so you don't have to:

• The memo must be the instruction right before the transfer. Token-2022 looks at the previous instruction in the transaction, not "somewhere in the transaction".
• Use the canonical Memo program ID. Token-2022 checks for MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr. Building the memo instruction by hand, as above, avoids depending on whichever ID a helper library defaults to.

TransferCheckedWithFee also asks you to state the fee you expect. If your number differs from what the mint computes, the transfer fails. That keeps the payer's software honest about the fee.

What the tests prove

The model runs inside LiteSVM (a local Solana VM: no network, no funds). The log of the last run:

PASS  M3 settlement mint created (fee 0.25% cap 50, frozen by default)
PASS  M3 seller account requires an invoice memo
PASS  M3 issuer funds the buyer account
PASS  M3 payment WITHOUT invoice number is rejected
        — Program log: Error: No memo in previous instruction required for recipient to receive a transfer
PASS  M3 payment to a NOT approved company is rejected (account frozen)
        — Program log: Error: Account is frozen
PASS  M3 invoice INV-2026-0042 paid with memo to approved company
PASS  M3 invoice number is recorded on-chain (memo in logs)
PASS  M3 seller received amount minus fee; fee withheld for the platform — received 997.5, fee 2.5
PASS  M3 fee cap works (fee on 100,000 is 50, not 250)

The two rejections are the interesting lines: they come from the token program itself, so no wallet, app or front end can skip them.

Run it yourself

solana-keygen new -o devnet-wallet.json            # new throwaway wallet
solana airdrop 2 $(solana-keygen pubkey devnet-wallet.json) --url devnet
npm install
npm test                                           # LiteSVM, local
KEYPAIR=./devnet-wallet.json npm run devnet        # devnet, prints Explorer links

The devnet script creates the mint, opens two accounts, approves both, pays INV-DEVNET-0001, then tries a payment without a memo and confirms that it was rejected. Every step prints a Solana Explorer link with ?cluster=devnet, so the invoice number can be read straight from the transaction logs.

Limits worth stating plainly

• A memo is public. Put an invoice number in it, never names, amounts in words or anything personal.
• The issuer holds real power. It can thaw, and with the freeze authority it can also freeze. That is the point of a permissioned rail, and also the reason it needs a trustworthy, regulated issuer.
• Withheld fees still have to be collected. The fee sits in recipient accounts until the withdraw authority harvests it; the model does not include that step.
• Not audited, not a product. It is a model for learning how far built-in token rules can go.

The code (Apache-2.0), the LiteSVM tests and the other Token-2022 models (a soulbound warranty card, creator royalties, a payment link bridge) are open in one place: https://github.com/wen-watt/wen-watt.github.io/tree/main/lab/code