Wallets

Funds that are available to be paid to recipients are tracked in wallets. This section describes how a wallet works.

Available vs. Current Balance

There are two values describing the amount of money in a wallet. The current balance is the amount of money that has not yet been sent to recipients or paid as fees. The available balance is the amount of money that is available to send to recipients.

When a payment request arrives and there is enough money in the wallet to cover it, its amount (plus fees) is deducted from the available balance.

If the payment succeeds, the amount is deducted from the current balance. If the payment fails, the amount is added back to the available balance.

Generally, when there are no payments in the process of being sent, the available and current balance should be the same, but they may differ while payments are in flight, including in cases where a payment provider issue causes the status of a payment request to be unknown for some period of time.

Example

Suppose a wallet starts out with

• Available balance = $9000
• Current balance = $9000

The client requests a batch of payments totaling $7000 including fees. When the request is received, the available balance is reduced:

• Available balance = $2000
• Current balance = $9000

The payment succeeds:

• Available balance = $2000
• Current balance = $2000