Accept USDC on Solana: design the complete payment flow

Choose where the merchant actually receives value

A direct route sends USDC to a receiving account you control. Your business operates payment discovery, validation, reconciliation, treasury and refunds. You retain stablecoin exposure until you use another route to convert or redeem it.

A processor can supply a checkout, status API and settlement workflow. Stripe's documentation describes customer stablecoin payment with settlement into the merchant's Stripe balance in local currency. The bank payout is a further stage.

Check current business eligibility, regions, asset-network support and settlement terms before integrating. A token existing on Solana does not mean a particular processor supports it for your account.

Define the promise to the customer: which currency the invoice is priced in, how long the quote remains valid and what counts as paid. Keep that rule consistent with the backend.

Create a precise invoice before displaying a QR code

Choose a teaching invoice INV-104 for 25 USDC on Solana mainnet. Store the exact accepted mint, recipient relationship, raw amount, expiry policy and an unpredictable unique correlation reference.

For six-decimal USDC, 25 units correspond to 25,000,000 base units. Use integer or exact decimal arithmetic. A token with the same displayed symbol but another mint does not satisfy the invoice.

Verify the published mint with the issuer's current address list. Solana Pay transfer requests can carry recipient, amount, token mint and reference fields for compatible wallets.

A request reference helps locate and match a payment. It does not stop a second transfer with that reference. A QR code describes the requested action; the actual transaction still needs validation.

Explain the wallet action and funding needs

The customer opens the request in a supported wallet and inspects the actual asset, amount and recipient. The wallet constructs and signs the transfer under its supported flow.

The transaction needs an eligible fee payer with SOL. Creating a missing token holding account can require separate setup funding. Having exactly 25 USDC alone does not guarantee the full transaction can execute.

Make the network clear before payment. The same stablecoin name on another network is not the requested Solana transfer. For a processor, let its supported checkout handle its documented route rather than inventing an unsupported deposit address.

Do not put personal information into a public memo. Use a correlation value whose public disclosure does not reveal unnecessary customer or order details.

One invoice, partial receipts and a later excess

Verify the candidate payment on the server

Discover candidate transactions through the reference or receiving-account history using a source with adequate coverage. Treat browser-provided signatures as candidates to inspect, not proof supplied by the customer.

Check cluster, execution success and required finality. Verify exact mint, correct receiving token account and its relationship to the intended recipient, accepted amount and invoice correlation.

Decode the supported transaction formats and relevant token operations. For assets with transfer fees or other features, define whether the invoice requires the actual net received amount. Do not infer settlement from an arbitrary log string.

Only after validation should the backend mark a receipt eligible for the invoice. Preserve signature, instruction identity, amounts and observation evidence for reconciliation.

Apply one-time fulfilment and explicit exception rules

Write the payment match and fulfilment decision under durable uniqueness rules. Two workers discovering the same transfer should not activate two subscriptions or ship two orders.

For INV-104, a validated 20-USDC receipt is a partial payment if the chosen policy allows accumulating payments. A further valid 5 can complete it. A second 25 after completion is an overpayment to handle, not a second reason to fulfil.

Define late payment, wrong asset, excess amount and unmatched reference paths. A final transfer can arrive after a local invoice expiry; the funds still need accounting even if the quote no longer applies.

For processors, verify webhook authenticity and use the documented authoritative payment state. Duplicate or out-of-order webhook delivery needs idempotent handling too.

Reconcile funds, service balances and refunds

Keep invoice, onchain receipt, processor settlement and bank payout as related but separate records. Their amounts can differ because of documented fees or conversion.

A direct onchain refund is a new authorized transfer. Confirm the correct recipient and applicable business policy rather than assuming every sender address is a suitable refund destination.

Use controlled receiving and treasury keys, protected signing and a tested recovery process. Monitoring does not need access to recovery phrases.

Test the full route in an appropriate test environment: success, partial payment, duplicate discovery, late receipt, callback loss and restart after settlement. Continue with reconciliation and idempotency for the backend design.

Common questions