Skip to main content

Wallet Balance

What is wallet balance?​

Wallet balance is used to hold funds, just like a real wallet most people have in their pockets. The end user uses their credit card details (or US Bank Account details when enabled for USD currency) to "top-up balance" to their wallet then they use the previously added balance from their wallet to purchase campaigns. Wallet enables topping-up arbitrary amounts of money so that the end user does not enter their credit card details for each purchase. Let's say that the basket total is 1000$ but the end user can top-up 5000$, then purchase the campaign for 1000$ then they can reuse the remaining 4000$ to purchase campaigns at a later time. Wallet Balance requires a wallet to be created as explained in End User Payments and user needs to enter their billing details in the Billing Portal.

How can a user pay without topping-up their wallet​

User can pay during campaign checkout via Direct Charge.

How does it compare to Direct Charge and Purchase Order?​

It can be summarized as:

  • Wallet Balance
    • User can add balance in any amount (not less than the campaign total price)
    • User can reuse balance in subsequent campaign orders
    • User can add balance before, during or after campaign checkout
  • Direct Charge
    • User pays for the campaign total price, not less, not more
    • User pays during the campaign checkout
  • Purchase Order
    • User pays after the campaign checkout

As an ATS, how can we start using wallet balance?​

Wallet Balance is not enabled by default for all ATSs. The ATS needs to talk with VONQ Partner Account Manager to get it enabled so their end users can start using it.

info

For an end user to use the wallet balance, the user needs to enter their billing information such as name, email, billing address & tax number before being able to order.

note

On our testing environments such as Acceptance and Sandbox, money related transactions such as "topping-up a wallet" are done using test credit card and the invoices are not sent when to the end user.

Caveats to know when using wallet balance​

Wallet Balance requires a wallet to be created as explained in End User Payments and user needs to enter their billing details in the Billing Portal.

Invoicing​

After user enters their billing information in the Billing Information & Invoice History portal of Stripe, they are eligible to enter their payment details. After they fill their payment details and submit the form to Stripe, an invoice will be created and sent to the email that they specified in their billing information.

Wallet creation & using a shared/non-shared wallet​

When HAPI Elements is loaded, a wallet is created for the end user if it has not already been created before. Subsequent loads of HAPI Elements will use the wallet that has been previously created. In tenant based applications, depending on how you are passing the clientId, the wallet will be shared amongst all users. Refer to Understanding what clientId refers to section for more information.

Ordering with wallet balance​

Purchasing a campaign with wallet balance requires at least one paid product meaning that the end user needs at least one "product" (not contract) added to their basket to purchase with wallet. If the end user has basket comprised of "only contracts", the basket total will be 0$ thus the backend order endpoint will throw an error saying "at least one paid product is required". To circumvent this, Payment Method step is hidden automatically by HAPI Elements and ATS Managed Payment Method is enforced automatically.

Ordering a campaign with only "contracts" in the basket with wallet​

HAPI Elements, when end user has "all contracts" in their basket, will automatically fall back to using "ATS Managed" option and end user will not see the "Payment Method" step of the Order Journey and the ATS developer will not be able to override the paymentMethod parameter of the CampaignCreateForm object.

How can we track wallet balance top-ups?​

Please refer to Listening to Payment Success Event recipe to learn more.

How can we programmatically manage payment method for a user​

Refer to Payment Methods Configuration for enabling/disabling some payment methods based on your business requirements.


Please refer to Using Wallet Balance Payment Method recipe for more information on how to use "wallet balance" payment method programmatically.