Spendable balance

📘

Permission Required

This feature requires the Pay permission.

Spending Limit

HandCash users have a global limit for how much they're willing to spend on apps on a daily basis.

If an attempt is made to spend more than their limit allows, the SDK will throw an error with this message:

{ "message": "Request exceeds users global connect spend limit." }

You can control this error with a piece of color similar to this:

try {
  // omitted code...
  const paymentResult = await account.wallet.pay(paymentParameters);
} catch(error) {
  if (error.message === 'Request exceeds users global connect spend limit.') {
    // Show spend limit reached dialog
  }
}

See the errors section to find out more details

Get spendable balance

Developers can check how much money they can spend based on the limit set by the user and the amount already spent that day. This balance is called spendable balance.

This limit can be changed or reset only by users at any time.

You can fetch the user's spendable balance with the wallet.getSpendableBalance function.

const {HandCashConnect} = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect({ 
   appId: '<app-id>', 
   appSecret: '<secret>',
}); 

const account = handCashConnect.getAccountFromAuthToken(token);
var spendableBalance = await account.wallet.getSpendableBalance();

console.log(spendableBalance);

// balance
{
  spendableSatoshiBalance: 1260000,
  spendableFiatBalance: 2.96,
  currencyCode: 'CAD'
}

If you need to customize the local currency conversion, you can pass any currency code through the function:

var balance = await account.wallet.getSpendableBalance("USD");

console.log(balance);

// balance
{
  spendableSatoshiBalance: 1260000,
  spendableFiatBalance: 2.03,
  currencyCode: 'USD'
}

Reset spendable balance

Occasionally, users might reach the daily spendable limit. In that situation, they would need to reset the daily limit from the HandCash app.

In order to reduce friction and make this process as convenient as possible, you can redirect them to HandCash to the exact screen where spend limits are managed:

const changeSpendLimitsUrl = handCashConnect.getChangeSpendLimitsUrl('https://my-app.com');

// Redirect user to "changeSpendLimitsUrl"

After changing the spending limit, users will be redirected to the URL specified (<https://my-app.com> in the example above).

For example, you can show a dialog to inform the user when the daily limit has been reached and include the changeSpendLimitsUrl in the primary action.

👍

Keep the experience frictionless

Event thought the redirectUrl parameter is optional we encourage you to use it to keep the experience as frictionless as possible.

If you follow the best practices you can achieve the following with 1-2 user clicks:

• The user is redirected from your app to HandCash
• The user resets the spending limit
• The user is redirect from HandCash back to your app

📘

Why can't developers reset the limit from the SDK?

Daily spend limits is a feature to help users manage their balance by controlling how much they exepect to spend. This is why user should manually reset the limit to ensure they are aware. If developers were able to reset the limit then users wouldn't be aware when the limit is reached.