Solana Pay links and QR codes: from a payment request to a verified receipt

Choose the request type

A transfer request states payment parameters in the URL. The wallet can construct the transfer from those fields. An interactive transaction request points to an HTTPS service that returns transaction information, allowing a more dynamic action.

That distinction affects the review boundary. A fixed transfer link describes a recipient and asset. An interactive service can supply a transaction containing other instructions. The wallet must treat that transaction as untrusted and present the action for review.

Use the current protocol specification and compatible libraries. This article explains the request and validation model; it does not claim a new SDK implementation has been executed.

Read the transfer fields

A schematic token request has this shape:

solana:RECIPIENT?amount=25&spl-token=MINT&reference=REFERENCE

The capitalized values are placeholders, not a payable example. The recipient is the receiving wallet's public address under the transfer-request convention, not a token-account address pasted into that field. The spl-token parameter identifies the mint; the wallet derives the suitable recipient token account for the flow.

The amount uses the token's displayed units. Verify its decimal handling before converting to raw integer quantities. Labels and messages provide human context. They do not change the receiving address or establish the issuer of a token with a familiar symbol.

A reference supplies a lookup identifier for the request. A memo is public transaction content. Avoid putting private order details, customer contact data or secrets in either field.

Bind the invoice on the merchant server

Create an invoice record containing the cluster, recipient, mint, exact expected amount and a unique reference. Establish its expiry and fulfilment policy before presenting the link. The browser can display those details, but it should not become the authority that decides what counts as paid.

For a 25-USDC teaching invoice, save the expected 25,000,000 raw units for a six-decimal mint. If the customer changes the cart, create or update the corresponding invoice state rather than accepting an unrelated client-reported total.

Tie a returned signature to the stored record. The payment request helps locate candidates; the record defines which candidate can satisfy this order.

Read each field for the job it performs

Validate more than the reference

A matching reference can occur in a transaction that paid the wrong recipient, used another mint, transferred too little or failed execution. Fetch the accepted transaction and validate the required asset movement under the correct network and program interpretation.

Use the stored amount and recipient. A wallet callback or a screenshot saying “sent” is not a substitute for the merchant's validation. On migrated Solana clusters, use the current documented commitment semantics and choose a consistent finality policy.

As a teaching case, a valid 20-USDC transfer with the invoice's reference is still five USDC short of a 25-USDC invoice. A failed transaction containing that reference contributes no successful token receipt. A second valid 25-USDC transfer is additional money to reconcile, not permission to ship twice.

Make fulfilment durable

Store the validated receipt and enforce a one-time transition from the invoice state to fulfilment. Two workers can observe the same transaction. A WebSocket reconnect can deliver an event you have already processed. The reference does not replace a durable uniqueness rule.

Define what happens to late, partial, excessive and duplicate payments. A refund is another authorized payment, so identify the intended recipient and keep the refund signature in the same ledger. Do not copy a claimed return address from an untrusted browser field without verification.

Inspect the customer's complete cost

A token payment can require network fees and account setup. A service may sponsor those costs, but the integration must supply the supported fee-payer and authority arrangement. A QR link alone does not provide gas sponsorship.

For a merchant, the completed result is a validated asset receipt plus a correctly reconciled order. A later conversion to another stablecoin or bank money is another stage with its own costs and evidence. Keep that distinction visible in the checkout status and accounting record.