Multi-Tenant Billing

Module Multi-Tenant Billing Module Description This modules allows an application built using the WorkXpress platform to became a SAAS application by creating a multi-tenant environment and facilitating billing via credit card or check.
Built by WorkXpress
Minimum Engine Version 725
Cost Free


Fig. 1: More Options Flyout To start the installation process, click on the “more options” link under a project and then select Modules.
Fig. 2: Installed Module List You will be presented with a list of the modules currently installed on the application. To add a module, click on the “add module” link in the upper right hand corner.
Fig. 3: Modules Available List Next, you will see a list of modules that can be added to the project. Select the radio button next to the Multi-Tenant Billing Module.
Fig. 4: Install in Progress Fig. 5: Installation Done Once you select the module and click the “add” button, the module will be loaded into your application. Your application will be temporarily unavailable during the install process. Your application will become available again after the install process is done.


Fig. 1: Application Header To start configuring the Multi-Tenant Billing module, click the “Admin” link in the top right corner of the application header.
Fig. 2: Administration Menu Here you will see the application administration screen. Click on the “Edit Application Settings” link. Note: If you made changes to your administration menu prior to importing the billing module, the link may be located in a different location or missing all together. If that is the case, use the Presentation Layer to add the link.
Fig. 3: Application Settings Page Under the “Enable Multitenancy” section of the Application Settings page, you will find the checkbox to enable multi-tenancy. If you have not done so previously, click on the enable multi-tenancy check box and save the Application Settings
Fig. 4: Administration Menu w/ Multi-Tenancy When you return to the application administration screen, you will notice a new section that contains the administration section for the billing module.
Fig. 5: Administration Menu w/ Multi-Tenancy Click on the “Edit My Settings” link in the center column of the multi-tenant billing form. This will take you to the multi-tenant configuration screen. This screen is broken down into four sections: Email Settings, Registration Settings, Payment Settings, and Misc Settings. All four sections must be filled out in order for the billing module to work properly. These settings are local to the installation must be filled out for every installation of the application: build, testing, and production. Because these settings are not linked to the application, they can be different for each installation and will not be overwritten when updates are performed.
Fig. 5: Email Configuration The multi-tenant billing module will send emails to the end user when certain events occur. Each email template has five settings that must be filled in. The first two settings will create the From portion of an email. The “From Email Address” will be the address that is used for the “from” section, for example, The “From Name” will be a nicer-looking name attached to the email address, for example, “Do Not Reply.” These two settings will be combined in the form "Do Not Reply <>". The third setting is the subject line of the email. The fourth setting is used in the basic template that comes included for each email type and is a header inside the email (this is commonly set to same value as the subject). The last setting is the report that is run and its result is the body of the email. For each email type, the billing module includes a standard report. These reports then can be edited to achieve a custom look.
Fig. 12: Introduction Email Configuration The Introduction email is sent to the end user when they sign up for your application using the registration page. The pre-built report for the Introduction is titled “Email - New Customer Introduction”.
Fig. 13: Manual Billing - 1st Reminder Configuration The Manual Billing - 1st Reminder email is sent a specified number of days before an end user's payment is due when they are paying via manual means, such as by check. The pre-built report for the Manual Billing - 1st Reminder is titled “Email - Manual Payment Reminder #1.”
Fig. 14: Manual Billing - 2nd Reminder Configuration The Manual Billing - 2nd Reminder email is similar to the Manual Billing - 1st Reminder email in that it is sent a specified number of days before an end user's payment is due when they are paying via manual means. However, the 2nd Reminder email is intended to be a final reminder before it is too late for the end user to submit payment on time. The pre-built report for the Manual Billing - 2nd Reminder is titled “Email - Manual Payment Reminder #2.”
Fig. 15: Automatic Payment Failed The Automatic Payment Failed email is sent when the end user is paying via automatic means, such as by credit card, and the processing has failed. The pre-built report for the Automatic Payment Failed email is titled “Email - Automatic Payment Failed.”
Fig. 16: Automatic Payment Successful The Automatic Payment Successful email is sent when the end user is paying via automatic means and the processing succeeded. The pre-built report for the Automatic Payment Successful is titled “Email - Automatic Payment Successful.”
Fig. 17: Subscription Expired The Subscription Expired email is sent when the end user or an administrator has canceled the subscription to the application. The pre-built report for the subscription Expired email is titled “Email - Manual Payments Expired.”
Fig. 18: Account Disabled The Account Disabled email is sent when the end user is delinquent and access to the application is being removed. The pre-built report for the Account Disabled email is titled “Email - Account Shut Off.”
Fig. 19: General Email settings These settings apply to all the emails generated by the multi-tenant billing module. The first setting is an image to use as part of the standard email template. The second setting is a general footer to use as part of the standard email templates. The last setting tells the multi-tenant billing module whether it should actually send emails in development and testing environments. Sending emails using the default WorkXpress email system requires the account that the application is running to pay for emails sent, so emails should be turned off when the building and testing of the application does not require the sending of emails.
Fig. 20: Registration Settings On the default registration page, there are several areas that can be customized with html for explaining to end users about the registration process. Also on the default registration complete page there is a section for the builder to add content to thank the user for their payment or to explain the next steps of paying by check.
Fig. 21: Payment Settings The payment settings page allows the builder to configure how the end user will pay for the application and what the payment frequency will be. Until the payment options are registered, the end user can register for and use the application without payment. Reminder Email - Number of Days Before Subscription Expiration (1) and (2) are used for sending the Payment Reminder Emails when the end user pays by check. The Billing Expiration Grace Period is used in automatic payments and is the period of time given to the user to log in and update their billing information before a second and final attempt is made to charge the customer. The three Braintree settings are values that come from the builder's Braintree account. Braintree is the processing company where the multi-tenant billing module collects, stores, and charges credit cards. To sign up for Braintree, click here. When configuring a development or testing application, Braintree Sandbox credentials must be used. The same Sandbox credentials can be used for both development and testing. When configuring a production environment, Braintree Production credentials must be used. The Address to Send Checks to is used in the manual payment email templates. The next billing processing date is used to set when the nightly billing tasks, such as charging monthly or annual fees, are performed. When an application is installed, billing will not start automatically. The administrator must enter the date on which the billing process should begin. After the billing process has started, the date will automatically advance by one day after the current day's processing has started. If for some reason billing needs to be temporarily suspended, then this field can be cleared by the administrator. To restart billing, enter the date on which billing was last processed and the system will automatically process the back log. The subscription type determines whether the end user is charged monthly or annually for access to the application. For annual billing, a recurring fee is defined. For monthly billing, a default first month free and a default ongoing fee can be entered. Under the monthly billing system, promotions can be created to override the default values.
Fig. 22: Misc Settings The application login url setting is used by some of the email templates to define a login url.

Promotion Management

Fig. 1: Promotion Management Under the monthly billing model, it is possible to create a promotion with six months of unique monthly charges and an ongoing charge that is different than the default value defined in the module settings. The promotion management system can be accessed by clicking the “Search All Monthly Promotions” link in the center of the multi-tenant administration menu form.
Fig. 2: Promotion List The promotion list shows which promotions are available, what time period they are valid for new signups, the flag to show if they are locked and made available to the public, the first three months of the promotion, and the ongoing charge that will be applied.
Fig. 3: Add Promotion The administrator can add new promotions by clicking on the “Add Monthly Promotion” link in the upper right-hand corner of the promotion list. The first setting of a promotion is the code the end user will enter on the registration screen. Note: The code is case sensitive. The Start and End Dates are the dates that control when new users can sign up under this promotion. The “lock” flag is used to publish the promotion for use by end users. The promotion will not be usable by any end user until it is locked even if the current date is during the promotion valid period. A promotion will run from the first month until it encounters a blank month. At that point, the user will be charged the ongoing value if defined. If the ongoing value is not defined, the system will use the default from the billing module settings. For example, to run a promotion described as the first 3 months for $50 and $75 per month after the first 3 months, then 50 should be entered for the first 3 month slots and 75 should be entered for the ongoing charge. Note: Zero is a valid value and is not equivalent to blank, so do not enter a zero for any values unless you intend not to charge for a month. For example, to do a promotion that is $20 for the first 3 months followed by $20 a month, you would enter 20, 0, and 0 for the first 3 months and 20 for the ongoing. Promotions can also be used to override the default ongoing charge without providing any other discounts. To override the default ongoing charge, simply enter your ongoing monthly charge in the first month and leave all of the other months empty.
Fig. 4: View/Edit a Promotion By clicking on the promotion code in the main promotion list, you will be presented with the full details of a promotion. If the promotion has not been locked and made public then the edit button will be available and changes can be made.

Tenant Management

Fig. 1: Promotion Management Every new signup in a multi-tenant application will create a new tenant. No tenant can see another tenant's data. To access the tenant management system, click on the “Search Tenants” link in the left-hand column of the billing module administration menu form.
Fig. 2: Tenant List Fig. 3: Tenant Actions The tenant list shows some summary information for the tenant. It also has a button to perform two key actions on a tenant: Disable the Tenant and Cancel the Tenant. Disabling a tenant will not allow a tenant to use the application unless they enter payment information. Canceling a tenant will allow that tenant to access the application until their next billing date (the end of their subscription).
Fig. 4: Tenant Details In the upper left-hand section of the “tenant details” page, the administrator can update the billing address, email address, or the tenant name. The payment information section will allow the administrator to change the monthly amount a tenant pays, what promotion they are assigned to, what month the tenant is in inside a promotion, the next billing date, and change or clear the tenant shutoff date. The first tab in the lower pane shows the list of users that exist under the tenant. A tenant must have at least one user.
Fig. 5: Tenant Payments The payments list will show the administrator the history of charges attempted for a tenant. If the tenant is paying via credit card, the list can also be used to issue refunds and charge a tenant's card for additional amounts to correct for billing mistakes or changes. A refund cannot exceed the full amount of a transaction. Partial refunds can only be processed after the charge has settled, which typically occurs 24 hours after the charge was submitted. The total of all the partial refunds cannot exceed the value of the original transaction. A full refund can performed at any time. If the tenant is paying via check, the payments list is how those payment are recorded and the tenant's subscription extended.
Fig. 12: Tenant Emails The email list will show the automatic emails that the billing module attempted to send and the tenant's status.

New Tenant Registration

Fig. 1: Default Registration Screen The default new tenant sign up page is located at {Your Application Url}/registration. On the default registration page a new tenant is created and the first user under the tenant is created and they are billed for their first payment if appropriate. After they successfully register they will be directed to a page of help text that was entered by the administrator in the billing settings above. This is also when the user will receive the new customer email with the link to log into the application.

Delinquent or Expired Tenants

Fig. 1: Default Expired or Delinquent Tenant Screen By default, if a tenant does not have valid payment information on file because they canceled their subscription or they went delinquent on their payments, a tenant can still log in to the application but the only screen they can access is a screen to enter updated billing information. The user must pay by credit card to restore access. Payment by check will not allow for automatic reinstatement of access to the application.
module - multi-tenant billing.txt · Last modified: 2016/09/14 18:19 (external edit)
Copyright WorkXpress, 2023