Skip to main content
Stablecoin wallets assign a Solana address to an individual customer. FossaPay currently supports the solana network and the usdc and usdt stablecoins.
FossaPay does not currently support an EVM wallet option. Send network: "solana" exactly; other values are rejected before wallet creation.

​
Prerequisites

  • Create the individual customer first.
  • Retain the customer UUID returned by FossaPay.
  • Use the production API key belonging to the same merchant.
  • Decide how your system will map the customer to the returned Solana address.

​
Create a customer wallet

Wallet creation returns a provider wallet identifier, Solana address, and network. Persist the complete response with the customer UUID. Only one Solana wallet can be created for the same customer. If a response is lost, reconcile the existing wallet before retrying; wallet creation does not provide idempotency semantics.

​
Addresses and ownership

Solana addresses are public deposit destinations, not authentication credentials. An address can receive supported assets from external senders, but authenticated wallet details and transaction history remain merchant-scoped. Validate the full address before displaying or using it. Do not truncate addresses in storage, comparison, signing, or transfer requests. Truncation is suitable only for presentation after the complete value has been retained.

​
Supported assets

Do not infer support for a token from its symbol alone. Sending an unsupported asset or using another network can make funds unavailable to the integration.

​
Retrieve wallets and balances

Customer wallets can be retrieved by FossaPay wallet ID or full blockchain address. The master endpoint returns merchant-owned stablecoin addresses and their provider-reported token balances. Token balances contain human-readable and raw representations where supplied by the provider. Preserve decimal precision and do not use JavaScript binary floating point for ledger calculations.
Wallet retrieval responses may be cached briefly. Use transaction state and confirmed provider results for operation reconciliation rather than assuming two immediate balance reads must differ.

​
Calculate a transfer fee

Before sending, call:
The response reports the configured fee quote. Fee configuration can change, so request a current quote instead of hard-coding pricing.

​
Send stablecoins

POST /api/v1/transfers/crypto sends from the customer’s wallet to a Solana recipient. The current transfer flow treats the submitted amount as the gross token amount. The configured fee is deducted and the recipient transfer uses the net amount (amount - fee). Confirm the current fee before presenting the expected recipient amount. The initial response reports provider processing; it is not final settlement. Persist the returned data and wait for the corresponding verified terminal event or reconcile the transaction through wallet history.
Confirm the customer, token, network, destination address, gross amount, fee, net amount, and available balance before submission. Confirmed blockchain transfers cannot be reversed by FossaPay.

​
Status and finality

When available, store the transaction hash and explorer link alongside the FossaPay transaction ID and references.

​
Safe retry behavior

Crypto transfer creation does not accept a merchant-provided idempotency key or reference. A timeout after submission is therefore ambiguous. Do not immediately send the same transfer again. Retrieve wallet transaction history and inspect balances before making a new business decision.

​
API reference

​
Production checklist

  • Accept only solana, usdc, and usdt where applicable.
  • Persist complete addresses and identifiers without truncation.
  • Use decimal-safe token handling.
  • Quote fees before presenting the recipient amount.
  • Treat processing responses as non-terminal.
  • Verify and deduplicate webhook events.
  • Reconcile ambiguous submissions before sending again.
  • Never promise reversibility after blockchain confirmation.