Solana Pay USDC Test Finds Errors in Commerce Kit Example

A test conducted on Oct. 8, 2026, found two problems in Solana’s Commerce Kit example for accepting USDC payments. The example asks customers to pay 0.025 USDC instead of 25 USDC and builds the transfer with the wrong token program. The @solana/pay SDK generated and simulated a 25 USDC payment successfully.

The test used @solana/pay 1.0.26 and @solana-commerce/solana-pay 0.1.1, the latest versions available at the time. It used live Solana mainnet mint accounts, a mainnet transaction simulation and a local mock RPC for validation cases. No real funds were transferred.

Solana Pay payment URLs use human-readable token amounts. USDC has six decimal places, so a request for 25 USDC should contain amount=25. The corresponding on-chain transfer uses 25,000,000 base units.

The Commerce Kit example instead passes 25,000,000n to its URL encoder. The test found that the encoder applies nine-decimal precision, which is used by SOL, even when USDC is selected. The resulting URL requests 0.025 USDC. A customer paying the displayed amount would send one-thousandth of the requested 25 USDC.

The transaction builder created a separate problem. Commerce Kit kept 25,000,000 as the raw token amount but generated the transfer for the Token-2022 program. Solana USDC uses the original Token program. A simulated 1.25 USDC transfer built with Commerce Kit failed with an IncorrectProgramId error. The same transfer built with @solana/pay used the original Token program and completed simulation.

The test used decimal USDC amounts with @solana/pay. Merchants converting prices from cents should perform that conversion once when creating the payment request. For example, a 25.99 USDC order should use 25.99 in the URL, rather than the token’s base-unit value.

Each order should have a unique public-key reference linked to the order record. Merchants can use the reference to find matching transactions and check the recipient, mint, amount, reference and optional memo before releasing goods or services. Every matching signature should be reviewed because a reference displayed in a QR code can also appear in failed, spam or low-value transactions. The test found that findReference can return the oldest matching transaction.

The validation function accepts overpayments because it checks whether at least the requested amount arrived. Merchants should compare the received amount with the order total and record or refund any difference. The test also found that validation can fail when a customer creates the merchant’s USDC account inside the payment transaction. The account should exist before payments begin.

The tested version of validateTransfer requested transaction data with support for version 0 or earlier. When it encountered a version 1 transaction, the RPC returned error -32015 before payment validation. The test found version 1 transactions among recent Solana transactions involving the USDC mint, but did not establish whether wallets use that format for Solana Pay transfers.

The same @solana/pay version handled PYUSD, which uses the Token-2022 program. PYUSD has Token-2022 settings that merchants must monitor, including transfer fees and transfer hooks. A nonzero transfer fee could reduce the amount received and cause an exact-payment check to fail.

Solana Pay is an open payment-link standard, not a payment processor. The customer’s wallet creates and signs the transfer, and generally pays Solana’s network fee. The payment process consists of creating a URL, displaying it as a QR code or link, finding the transaction through its reference and validating it before fulfillment.