Skip to main content
FossaPay supports merchant master wallets and individual customer wallets on Solana and Stellar. Solana wallets support SOL, USDC, and USDT; Stellar wallets support XLM and USDC.
FossaPay does not currently support EVM wallets. Use network: "solana" or network: "stellar" when creating a wallet.

​
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 network address.

​
Create a customer wallet

Set network to stellar in the same request to create a Stellar customer wallet. Save the returned data.id, data.address, and data.network with the customer ID. Use data.id for wallet-by-ID and wallet-transactions requests, and data.address for wallet-by-address requests. Only one wallet per network 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.

​
Create a merchant master wallet

Create a master wallet only when the business needs an address on that network:
The response contains the newly created master wallet in data, including its FossaPay id, Stellar address, network, and tokens. The endpoint rejects a second active master wallet for the same network. Existing wallets are not created automatically by this request; retrieve them with GET /api/v1/wallets/crypto/master.

​
Addresses and ownership

Wallet addresses are public deposit destinations, not authentication credentials. A wallet can receive assets beyond FossaPay’s supported set. 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

Only NGN, USDC, and USDT are accepted for checkouts and payment links; XLM and SOL are wallet assets, not checkout methods. Stellar wallet support does not add Stellar as a checkout or payment-link network. An incoming asset outside the supported set can appear as a successful deposit transaction with cryptoAssetStatus: "unsupported", but is not added to a FossaPay spendable balance and cannot be used for transfers, checkouts, or payment links. Token symbols are not proof of identity; inspect the token locator, mint, or contract. Contact support about recovery of an unsupported asset. An unsupported-asset receipt does not emit a deposit.completed merchant webhook: that event could otherwise be mistaken for spendable customer credit. Retrieve wallet transaction history to inspect these receipts.

​
Retrieve wallets and balances

Customer wallets can be retrieved by FossaPay wallet id, customer ID, or full blockchain address. For customer balance lookup, add ?network=stellar to retrieve Stellar; omitting network selects Solana. Wallet lookup responses also include the FossaPay id, so an existing wallet can be looked up by address before requesting its transaction history. The master endpoint returns the merchant’s created Solana and Stellar addresses with supported balances. Unsupported tokens are recorded in transaction history, not these standard balance responses. Token balances contain human-readable and raw representations when available. Preserve decimal precision and do not use JavaScript binary floating point for ledger calculations.
Wallet retrieval responses may be cached briefly. Use transaction status and wallet history for reconciliation rather than assuming two immediate balance reads must differ.

​
Calculate a transfer fee

Before sending, call:
The response reports the configured fee quote. Include network=stellar when quoting Stellar USDC or XLM; omitting network selects Solana for currencies other than XLM. Fee configuration can change, so request a current quote instead of hard-coding pricing. For SOL, use currency=sol. The SOL transfer fee is 0.001 SOL for amounts below 1 SOL, 0.01 SOL for amounts from 1 through 10 SOL, and 0.1 SOL for amounts above 10 SOL. The merchant dashboard quotes the same tiers. The external customer-transfer API subtracts this fee from the submitted gross amount; the merchant dashboard payout adds it to the requested recipient amount. Crypto deposits carry no collection fee: the credited deposit amount equals the confirmed amount received. This does not remove transfer or payout fees. NGN collection fees remain unchanged.

​
Send SOL and stablecoins

POST /api/v1/transfers/crypto sends from the customer’s wallet to a recipient on the selected network. The current transfer flow treats the submitted amount as the gross token amount. Any quoted transfer fee is deducted and the recipient transfer uses the net amount (amount - fee). SOL amounts support up to nine decimal places; XLM amounts support up to seven. Solana wallets need enough native SOL for network execution. Stellar wallets must retain the configured XLM reserve for account reserves and network fees; the default minimum is 1.5 XLM. Confirm the current fee and network requirements before presenting the expected recipient amount. If no Stellar memo is supplied, FossaPay generates one. The initial response reports 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

For custom Solana program interactions, follow the Solana Transaction Signing guide. Signing supports arbitrary validated Solana versioned transactions; it does not expand the assets supported by FossaPay transfers, checkouts, or payment links.

​
Production checklist

  • Match the wallet network and currency: Solana supports SOL/USDC/USDT; Stellar supports XLM/USDC. Crypto checkout and payment links accept only their documented USDC/USDT methods.
  • 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.