Skip to main content
Wallets are the accounts through which FossaPay attributes balances and money movement. Every wallet has an owner, a currency rail, and a specific operational purpose.

​
Wallet model

Choose the source wallet according to economic ownership. Customer funds must use customer-wallet operations; business funds must use the merchant master wallet and Payouts API.

​
Customer and master wallets

A customer wallet is linked to a customer UUID created through the Customers API. The authenticated merchant must own that customer. A master wallet belongs directly to the merchant. Retrieve it using the authenticated API key; no customer or wallet identifier is supplied. Master-wallet funds must not be represented as belonging to an individual customer.

​
NGN and stablecoin rails

NGN wallets expose bank account details and separate available and ledger balances. Crypto wallets expose a Solana or Stellar address and token balances. These are separate resources—an NGN wallet ID cannot be used with a crypto endpoint, and a blockchain address cannot identify an NGN wallet. FossaPay currently supports production access only. All wallet operations can affect live resources.

​
Balances

Use the current authenticated wallet response as the balance authority before initiating an operation. Do not derive a balance solely by adding webhook amounts in your application.
Money and token values may be returned as decimal strings. Use a decimal or money library instead of binary floating-point arithmetic.

​
Ownership isolation

Wallet lookups are merchant-scoped. A valid API key does not authorize access to another merchant’s customer or wallet. Persist the IDs returned under each merchant and never accept an arbitrary wallet ID from a client without applying your own ownership checks.

​
Wallet lifecycle

  1. Create the individual customer.
  2. Create the appropriate customer wallet.
  3. Persist the wallet ID, customer ID, reference, and account or address details.
  4. Retrieve balances and transaction history for operational use.
  5. Process verified webhook events exactly once.
  6. Reconcile important operations through authenticated retrieval endpoints.
Wallet creation does not provide general idempotency semantics. If a create response is lost, retrieve or reconcile the customer’s wallet before submitting another request.

​
Transactions and webhooks

Wallet transactions describe financial state. Webhook records describe delivery attempts. A failed webhook delivery does not make its financial transaction failed, and a successful webhook response does not independently prove that funds moved. Use:
  • transaction IDs and references for reconciliation;
  • eventId for webhook deduplication;
  • terminal transaction statuses for final internal state; and
  • wallet retrieval for current balances.

​
Choose a wallet rail

NGN wallets

Provision bank accounts, collect NGN, inspect balances, and move customer funds.

Crypto wallets

Provision Solana or Stellar wallets, view supported balances, and manage customer crypto transfers.

​
Operational checklist

  • Identify whether the funds belong to a customer or the merchant.
  • Persist customer, wallet, transaction, and merchant references together.
  • Keep NGN and stablecoin identifiers separate.
  • Treat non-terminal statuses as unresolved.
  • Verify and deduplicate webhook events.
  • Reconcile balances and transactions through authenticated endpoints.
  • Keep API keys, personal data, and full account details out of unnecessary logs.