Manage wallet balance

​

Top up a wallet

There are several ways funds can be added to a customer’s wallet:

1. Initiate a prepayment from the customer’s default automatic payment method
2. Record an offline payment received outside Hyperline
3. Add free funds
4. Let customers top up independently from the customer portal
5. Top up through the API

Paid top-ups are funds your customer pays for, acting as a prepayment. Free top-ups are an offer you are making to the customer.

​

Initiate a prepayment

Use Initiate prepayment when the customer has a default automatic payment method, such as card or direct debit. Hyperline charges that payment method and adds the settled funds to the wallet. The payment transaction and wallet movement provide the audit trail. Hyperline does not create an invoice, receipt, or payment advance document for the top-up.

​

Record an offline payment

Use Add offline payment when the customer has already paid outside Hyperline and you want to make those funds available in their wallet. Hyperline does not create a technical invoice, receipt, or payment advance document. You can choose between two sources:

• Use existing transaction: select a compatible transaction that still has an unallocated amount. Hyperline adds its complete remaining amount to the wallet.
• Record transaction: record a new payment received by bank transfer or another external payment method, then add it to the wallet.

For a new transaction, enter the payment date, payment method, amount, and an optional reference. You can also add an optional comment to the wallet movement. The reference belongs to the payment transaction; the comment belongs to the wallet transaction. The transaction must belong to the same customer and use the wallet currency. If part of it is already allocated to invoices, Hyperline adds only the remaining unallocated amount to the wallet. You can also fund the wallet while recording an offline payment from the customer’s Transactions page. Turn on Add payment funds to wallet in the Record transaction > Payment form to make the recorded amount available in the wallet immediately. See Understand payment allocations.

​

Free top-ups

Use Add free funds when you want to credit a wallet without collecting payment. Hyperline adds the funds to the wallet and creates a credit note for accounting purposes. You can create the credit note immediately or keep it as a draft first.

​

API top-ups

Wallets can also be topped up through the API. Use the API when wallet loads should be triggered by your own product, backend workflows, or internal tooling.

​

From the customer portal

You can let your customers top up independently through their portal.

​

Wallet debit

Customer wallets are automatically debited when the feature is enabled in the wallet settings and the wallet has a positive balance. Wallet funds are used to pay subscriptions, related invoices, and one-time payments. A wallet cannot have a negative balance. Hyperline automatically deducts the maximum possible amount from the wallet when paying invoices. Any remaining amount is charged to the customer’s default payment method. You can also pay a specific invoice from the customer’s wallet manually. Open the invoice, select Actions > Add payment, then choose Use wallet balance. Enter the amount to apply, up to the lower of the invoice amount due and the current wallet balance. An invoice can combine multiple payment sources (e.g. wallet + credit card), and this breakdown is displayed on the generated PDF invoice. Hyperline also records which wallet credits funded each consumption. It uses the oldest available funds first, so one invoice payment can consume the end of one top-up and part of the next. See Understand payment allocations for an example and the relationship with payment allocations.

​

Reverse a wallet payment

Use Reverse wallet payment from an invoice when a wallet consumption should no longer pay that invoice. Hyperline cancels the wallet debit, returns the amount to the wallet balance, and recalculates the invoice. This is not the same as unallocating a standard transaction. Unallocating makes the amount available again on that transaction. Reversing a wallet payment makes the amount available again in the wallet because the wallet debit itself is cancelled.

​

Revert a wallet top-up

You can revert wallet top-up transactions to remove funds that were previously added to a customer’s wallet.

​

How it works

When you revert a wallet transaction:

• The credited amount is deducted from the current wallet balance
• If the transaction was a free top-up, the related credit note is voided
• If the transaction was a paid top-up, the amount is deducted from the wallet balance. If you need to refund the initial banking transaction, this must be done outside of Hyperline

​

Requirements

A transaction can only be reverted if:

• It is a top-up transaction (not a debit/consumption transaction)
• It has not already been reverted
• The wallet has sufficient balance to cover the reversal amount

​

Wallet balance & projection

Wallet balances are computed in real time in Hyperline. In addition to the wallet balance, we also compute and return a projected balance. This balance takes into account a projection of the future remaining money on the wallet after paying what will be due in the current period (subscription, usage). This is particularly useful for a pay-as-you-go use case when you want to restrict access to your product if the customer doesn’t have enough funds in their wallet.