How to debit from multiple balances in a wallet based on priority and expiration date

Last updated: February 21, 2025

When debiting from a wallet that has multiple balances, the order in which the balances are debited depends on how the balances are specified in the debit request:

  1. No balances specified: If no balances are specified in the debit request, the main balance will be debited.

  2. All balances (*): If the wildcard (*) is used in the debit request, all balances (including the main balance) will be debited. The order of debiting is as follows:

    1. Balances are sorted by expiration date in ascending order (earliest expiration date first).

    2. If multiple balances have the same expiration date, they are further sorted by priority in ascending order (highest priority first).

    3. The main balance is debited last.

  3. Specific balances listed: If specific balances are listed in the debit request, they will be debited in the order they are listed, without any sorting by expiration date or priority.

To debit from specific balances, you can use the debitWalletRequest method and specify the balances you want to debit from. For example:

List<String> balances = new ArrayList<>();
balances.add("balance1");
balances.add("balance2");

DebitWalletRequest debitRequest = DebitWalletRequest.builder()
    .id("<WALLET_ID_SOURCE>")
    .destination(new WalletSubject(Optional.of("<BALANCE_IDs_SOURCE>"), "<WALLET_ID_DEST>", "WALLET"))
    .balances(balances)
    .amount(Monetary.builder()
        .amount(new BigInteger("600"))
        .asset("USD/2")
        .build())
    .build();

In this example, balance1 will be debited first, followed by balance2. If the total amount cannot be debited from the specified balances, the main balance will not be debited.