Segovia Wallets

Funds that are available to be paid to recipients are tracked in Segovia 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.

Minimum Balance

The minimum balance controls whether or not new payment requests are accepted. If the available balance is less than the minimum balance, no new payments may be initiated.

If the available balance is at or above the minimum, a payment may cause it to drop below the minimum, but see the next section.

Negative Balance Limit

For some customers, a wallet may be configured with a negative balance limit. This is the absolute minimum a wallet balance is allowed to reach. A payment that would cause the available balance to drop below this limit will be refused even if the available balance is greater than the minimum balance.

In most cases this limit will be zero, that is, negative balances aren't generally permitted.

Example

Suppose a wallet starts out with

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

The payment succeeds:

Now the client requests a payment that totals $5000 including fees. This would cause the available balance to drop below the negative balance limit, so the payment request is refused.

Later, the client requests a payment that totals $3000 including fees. The available balance is greater than the minimum, so this is accepted:

While that payment is in process, the client requests another payment of $50. The available balance is lower than the minimum balance, so the request is refused.

Subwallets

To subdivide the funds in a wallet, it's possible to create "subwallets" that can be funded by moving money from a main wallet. Each subwallet is associated with a single main wallet and has its own available and current balances, which work as described above. Subwallets always have minimum balances of zero and negative balance limits of zero.

Moving money into subwallets is subject to the minimum balance and negative balance limits on the main wallet: it's not possible to move money into a subwallet if the originating wallet is already below its minimum balance, and it's not possible to move money into a subwallet if it would cause the originating wallet's balance to go below its negative balance limit. In other words, moving money into a subwallet follows the same balance limit rules as making a payment from the main wallet.

When a payment request specifies a subwallet, only the balances of that particular subwallet are affected. A payment request will be rejected if the subwallet's available balance would drop below zero, even when there are sufficient funds in the main wallet.

A subwallet may be deactivated. Deactivated subwallets retain their balances but don't allow new payments. A deactivated subwallet may be reactivated later. Funds may be transferred out of a deactivated subwallet, but not into one. If a reversal of a payment from a subwallet is processed after the subwallet has been deactivated, the funds from the reversal will be credited to the main wallet rather than to the deactivated subwallet.

Each subwallet has a name, which is a string supplied by the client when the subwallet is created. A subwallet name must be unique among the subwallets associated with a particular main wallet, but different main wallets can have subwallets with the same names. A subwallet name may not contain the forward slash character / or the asterisk * but may contain any other valid Unicode character. Subwallet names may be up to 40 characters in length.

In the API, subwallets and main wallets are represented using a path syntax. For example, a main wallet might be called safaricom-kenya. If it has a subwallet called agent-123, this would be passed to the payment gateway as safaricom-kenya/agent-123 in API calls. The same subwallet name under a different main wallet might be mtn-rwanda/agent-123 and would refer to a completely distinct subwallet with its own separate balances.

Only one level of subwallets is supported; it is not legal for a subwallet to have subwallets of its own.