Invoice Portal

Invoice Portal Overview, Features, & How-To's

Overview

The Billflow Invoice Portal gives your customers a page to view, pay, and download their invoices. It works with any invoices created in Stripe whether that be from Billflow, a custom Stripe integration, or another 3rd party app.

You can configure the actions a user can perform in the portal, as well as enable options to increase up-sells and reduce churn.

The Invoice Portal has a simple HTML/Javascript embed so it can be embedded onto any website that will accept this common embed method. It authorizes users with a security hash generated with the logged-in user's email or Stripe Customer ID. This method of authorization allows Billflow to work with any authentication provider. Make sure to check out plugins to make integration easier.

Invoice Portal Settings

How to Identify Customers

You must choose how you will identify customers. You have an option to pass in a customer's email address or their Stripe Customer ID in order for Billflow to look up their information in Stripe.

Identifying with email is simpler as it requires less data to store. Identifying with Stripe Customer ID is more robust because you do not need to handle email changes and is also needed when doing a tenant based architecture where multiple account are under the same group.

Enable Security Hash

Turn on to enable security on your page in test mode. This option is required in live mode. In order for the customer portal to securely display customer billing information, a hash must be passed to the billing page options. This hash must be generated on the server with the logged in user's email or Stripe customer ID, whichever you are using to identify users. This step is covered in more detail in the Secure Setup.

Show all customer invoices

Turn on to show all customer invoices including one-time invoices. By default, the invoices section will only show invoices related to the subscription the customer is viewing. If you do enterprise deals or one-off invoicing for services, enable this so customers can view all their invoices.

Language Settings

All Billflow billing pages have the ability to automatically detect the customer's browser language preference and translate the billing page accordingly. If the language is not supported by our page, a default language will be displayed. The default language is English US.

Automatically Detect User's Browser Settings

Turn on to automatically detect the customer's browser settings and translate the page. If not enabled, select your default language. Not seeing a language you need there? Contact us on the chat to request a translation.

Add a Custom Resource

Turn this option on to pass in your own translations. This can be used to host your own language files, but can also be used to change the text of specific sections to your desired text. To learn more about this option, read along here.

Advanced Settings

Enable Handle Response

Turn on to enable the handleResponse function. The function is used to handle events with custom code when events happen on the billing page like button clicks and actions performed. To learn more about events available and sample code snippets, read along here.

Debug Mode

Turn on to enable debug mode for extra console logging.

Embed

Embedding the Invoice Portal is a two-step process. For the client side installation just copy and paste the provided HTML snippet. The next step is secure setup.

If you have a frontend framework, check out the samples of embedding with those.

Authentication Secure Setup

The customer portal must be behind some kind of user authentication in order to safely show customers their billing information. Billflow authenticates users with an HMAC hash generated for the logged-in user, this allow is to work with any authentication system. If you are using a No-code platform, make sure to check out our plugins as they handle this step for you. If you are integrating into a custom application, continue on.

Your code to generate an HMAC for your app must be placed in the back-end of your application. Grab the snippet from the dashboard to add to your server. You may generate the HMAC with the user's email OR the user's Stripe Customer ID (customer_id).

The HMAC generated will be passed to the client-side snippet to a property called 'hash'.

Don't see your server-side language listed? Let us know and we'll get a code snippet for you!

Node.js

const crypto = require("crypto");
const email_hash = crypto.createHmac(
    "sha256",
    "YOUR_SECRET_KEY" // SECRET KEY (KEEP SAFE!)
).update(req.user.email).digest("hex") // PASS THIS TO FRONT-END

Rails (Ruby)

email_hash = OpenSSL::HMAC.hexdigest(
    'sha256', # HASH FUNCTION
    'YOUR_SECRET_KEY', # SECRET KEY (KEEP SAFE!)
    current_user.email # REPLACE WITH USER'S EMAIL ADDRESS
) # PASS THIS TO FRONT-END

Django (Python)

import hmac
import hashlib

email_hash = hmac.new(
    'YOUR_SECRET_KEY', # SECRET KEY (KEEP SAFE!)
    request.user.email, # REPLACE WITH USER'S EMAIL ADDRESS
    digestmod=hashlib.sha256 # HASH FUNCTION
).hexdigest() # PASS THIS TO FRONT-END

PHP

$email_hash = hash_hmac(
    'sha256', // HASH FUNCTION
    $user->email, // REPLACE WITH USER'S EMAIL ADDRESS
    'YOUR_SECRET_KEY' // SECRET KEY (KEEP SAFE!)
); // PASS THIS TO FRONT-END

Other

Generate an HMAC with SHA256 whenever a user logs into your app. Most web frameworks will have a method or library to help you do this. You'll need your app’s secret key and the email or user_id of the currently logged-in user.

Secret Key Get Your Secret Key

Seeing 403s? You can verify your HMAC is being generated properly by creating one here. Use "SHA256", pass in the customer's email or customer ID, and use your Billflow secret key as the secret. Compare that with what you're generating server-side and what's being passed to the client-side.

Keep your secret key safe! Never commit it directly a public repository, client-side code, or anywhere a third party can find it.

Don't forget to check out our integration samples!

Popular How-to's

pageEnterprise Sales Flow

Developers

The invoice portal has many more powerful features that can be unlocked with some simple coding. Check out the developer docs to learn more.

pageEmbed Configurations