Balance and Payment Preference Hooks

1 views Markdown

The four hooks over the wallet, balance adjustments and the auto-payment chain.

Overview

Money enters or leaves a customer wallet four ways: a top-up request, credit from an invoice, a manual adjustment by an administrator, and a change in the auto-payment chain.

Currency is the trap here: a balance is kept in its own currency while an invoice may be in another. Check which one an amount is in before carrying it anywhere.

Reference

Following the auto-payment chain

actionuser.autopay_changed

AccountCards head of the chain

Runs when the auto-payment chain of an account changes.

Parameters 2

$uidintThe owner of the account.

$autopayCtxarrayThe current head of the chain. When the chain empties this arrives empty: the account has no card left to pay with and renewals will fail.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.autopay_changed', 10, function ($uid, $autopayCtx) {
    // An empty chain means renewals will fail.
    if (!($autopayCtx['backup_card'] ?? null)) Acme::warnNoCard($uid);
});

Following credit reaching the balance

actionuser.balance_credited

Invoices after conversion

Runs when credit from an invoice reaches a customer balance.

Parameters 4

$user_idintThe customer whose balance grew.

$amountfloatThe amount credited, in the balance currency and after conversion. It need not match the invoice total: the invoice may be in another currency.

$currencyintThe balance currency.

$invoicearrayThe source invoice.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.balance_credited', 10, function ($user_id, $amount, $currency, $invoice) {
    // The amount is in the balance currency: do not mix it with the invoice one.
    Acme::ledgerCredit($user_id, $amount, $currency);
});

Following a balance adjustment

actionuser.credit_adjusted

AdminUsers two directions

Runs when an administrator adjusts a balance by hand.

Parameters 5

$user_idintThe customer whose balance moved.

$typestringWhich way: up credit, down debit.

$amountfloatThe adjustment amount.

$new_balancefloatThe balance after the change.

$cidintThe balance currency.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.credit_adjusted', 10,
    function ($user_id, $type, $amount, $new_balance, $cid) {
        Acme::ledgerAdjust($user_id, $type, $amount, $new_balance);
    });

Following a top-up request

actionuser.funds_added

AccountBalance the net amount

Runs when a customer asks to top up their wallet.

Parameters 3

$uidintThe owner of the wallet.

$amountfloatThe net amount asked for. Tax and gateway commission are not included: what the customer pays is higher. Do not book this number as the amount paid.

$fundsCtxarrayContext: which surface the request came from and the minimum.

Return 1

voidThe return is ignored.

Listener

Hook::add('action:user.funds_added', 10, function ($uid, $amount, $fundsCtx) {
    // The NET amount: tax and commission are not in it.
    Acme::noteTopupIntent($uid, $amount);
});

Pitfalls

The balance amount is not the invoice amount

What reaches a balance arrives in the balance currency and after conversion. It need not equal the invoice total; treating them as one number produces a gap in your books.

The top-up amount is the net amount

The amount in the top-up hook is net: tax and gateway commission are not in it. What the customer pays is higher, so do not record this number as the sum collected.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Overview

Reference

Following the auto-payment chain

Following credit reaching the balance

Following a balance adjustment

Following a top-up request

Pitfalls

Related Articles