Intended audience

This guide is intended for three types of users:

• administrative personnel on the merchant´s side who manage recurring billing processes daily (Recurring Billing Setup and Management Section)
• administrative staff on the facilitator’s side that perform basic merchant configurations (Billing Profile, Billing Cycle, Billing section)
• system administrators (Enabling Jobs and Timers section)

Introduction

There are goods and services that customers purchase on a regular basis — for example, gym memberships, magazine subscriptions, and mobile apps. Customers can pay for these types of goods/services via recurring billing. In the process of recurring billing, a merchant automatically charges a customer for the specific goods/services on a prearranged schedule or a payment plan. To use a payment plan, the customer must sign up for and give their consent to pay a certain amount regularly. When the customer agrees to make payments with or without the underlying payment plan, a subscription is created. If there is a need for the customer to change the existing subscription (for example, cancel gym membership for a specific period), the subscription adjustment is applied. To pay for the subscription, the customer can use any payment option (cash, card, check, etc.).

{UniBill} is one of the {UniPay} modules that provides an opportunity to set up customers, create payment plans and subscriptions, and withdraw payments on a routine basis. The recurring billing process can be set up and managed via both the gateway user interface (link to lesson) and RESTful API.

Terminology

Before you start working with the recurring billing module, make sure that you have familiarized yourself with these basic concepts.

Customer - An individual who purchases a subscription to a merchant’s goods/services and pays for them either through the gateway or through an external system (for example, a terminal not integrated with the gateway), in cash/by check.
Customer Account - A record that holds critical data about the customer (a person or an organization) including basic demographic/contact information and activity-related information (such as current balance, letter flags, etc).

Payment Option - Customer’s payment card or bank account encrypted and stored within the system.

Payment Plan - Pricing plan, which determines how often and how much a customer has to pay.
Billing frequency is defined in billing cycle parameter.
Subscription - Customer’s subscription to a specific pricing plan that represents a commitment to pay a specified amount of money regularly to receive a product or service.

Definition

Recurring billing process is comprised of several subprocesses, which are explained in detail below:

Invoicing

Invoicing is the process of generation of invoices based on the payment plans that are due on the billing date (e.g. today). As a result of the process, an invoice is generated for each payment plan that is due. The invoice is posted to the customer account that the payment plan is attributed to and, consequently, the outstanding balance on the account is increased.

Balancing 1

Balancing 1 is the process during which payments (such as prepayments or any positive balance on the account) are allocated against outstanding invoices.
The allocation (balancing) process can be performed using different approaches (algorithms). There are two balancing algorithms that are most commonly used:

• Oldest invoice first – any available payment will be allocated to the oldest outstanding invoice first, then to the second oldest and so on. This algorithm is often used for collections of past-due payments.
• Newest invoice first – any available payment will be allocated to the most recently created invoice first, then to the invoice created right before it and so on. This algorithm is often used for billing invoices as well as for prepayments and POS purchases.

Billing

Billing is the process during which all the invoices are collected and claims are generated and submitted to the processing engine to charge the respective accounts and collect payments. The billing remains open and the claims remain in pending status until the processing completes. Usually, depending on the decline recycling policy, the processing phase can take between 1 and 3 days.

Processing

Processing is the process during which respective submitted transactions are handled by the processing engine and associated accounts (bank accounts or payment cards) are charged with respective amounts.

Reprocessing

Reprocessing is the process during which soft declines are reattempted based on predefined rules (around number of attempts and their frequency). This process often involves the use of credit card account updater.

Closeout

Closeout is the process during which the result of processing is imported from the processing engine, and approvals and declines are posted to the respective customer accounts.

Fee Assessment

Fee Assessment is the process during which all newly imported declines are analyzed and respective decline fees are assessed. During this process, late fees can also be assessed on accounts with outstanding balance over a predefined time period.

Balancing 2

Balancing 2 is the process which allocates newly posted payments against the invoices generated as part of the invoicing process. As part of this process, all customer accounts involved in the invoicing process are updated with their new balances. In case when submitted payments came back as approved, the balance is reduced to zero. In cases of declines, the balance is updated with the total of the outstanding balance of the nvoices plus any fees that were generated within the fee assessment process.

Rebilling

Rebilling is essentially a billing process, which involves all of the phases explained above; however, it is generally done on the previously declined accounts. It can be implemented in various ways including reattempt of the last successful payment attempted or reattempt of the entire outstanding balance, including fees.

Billing Configurations

Before starting to use the recurring billing functionality, it is important to set up three configurations:

• merchant’s billing profile;
• billing cycle;
• billing.

Billing Profile

The Billing Profile can be configured in either of the two ways:

1. Add and configure a new profile for the selected merchant on Billing Profiles form on the gateway console perspective (Console perspective => Setup => Billing Profiles => New)

2. Configure a Billing Profile using configuration scripts via Management API
The example of the configuration script that should be uploaded to $app-home\resources\billing-setup\ directory before calling ~configure API function:

 
api.billingCycle("W"); // create weekly billing cycle codes (from W01 to W07) 
api.billingCycle("M"); // create monthly billing cycle codes (from M01 to M31)
api.itemCode("Membership","Membership");
api.tax("tax","tax",10);
api.adjustmentCode("adjustment","adjustmant",true,true);// 
api.groupCode("Group","Group");
api.actionCode("actionCode", "actionCode");
api.letterCode("letterCode","letterCode", true);
api.noteCode("note","note");
api.emailCode("email","email");
api.documentCode("document","document");
api.createBillingProfile(); // create default billing and billing profile
 

Find more information in the Configuration scripts guide.
If the Billing Profile hasn’t been configured, any attempt to process a payment will return the following error: O21 (Billing Profile is not configured for the referenced account).

Billing Cycle

The billing cycle defines the frequency of billings and the day when billing occurs. Billing cycles allow to group subscriptions and perform revenue analysis based on all subscriptions associated with a particular billing cycle. Based on a billing cycle, invoices are created.

Billing cycle is configured on the gateway console perspective (Console perspective => Setup => Billing Cycles=> New):

Billing

Billing - Recurring billing configuration that unifies the billing cycle and billing profile assigning them to a specific payment.

To create a billing, switch to Console perspective => Setup => Billings=> New, and select the Billing Profile and Billing Cycle that you would like to use in this Billing.

Enabling Jobs and Timers

Automated generation of invoices and claims and processing of payments is implemented using jobs and timers.
Thus, as part of the configuration process, it is necessary to make sure that the following jobs and timers are Active in Jobs=>Job Objects section on Monitoring Perspective:

• ibilling.billing-create-invoices
• ibilling.billing-create-claims
• ibilling.billing-close-billing

• ibilling.billing-open-billing-timer 0+0+0+*+*+?
• ibilling.billing-close-billing-timer 0+0+10*+*+?

It is recommended to configure “open billing” and “close billing” timers with a time gap between them (e.g., one hour).

Recurring Billing Setup and Management

Creating Customer Accounts

To charge customers automatically on a regular basis, you need to have their payment details stored within the system. This can be achieved in two steps:

1) Create a new customer account. For this, you need to provide the customer’s first and last name (required), contact details, and address (optional).

A new customer account can be created via the user interface (see tutorial) or via API call https://unipaygateway.info/billing-api/actions/v01/customers#actcreate|https://unipaygateway.info/billing-api/actions/v01/customers#actcreate. The customer account can be modified at any time or made inactive in case of need.

2) Add payment option(s) associated with the customer. You can add a credit card or a bank account that will serve as a source of payment. The system supports the ability to add multiple payment options associated with each customer. A payment option can be created via the user interface (see tutorial) or API call https://unipaygateway.info/billing-api/actions/v01/customers/[customer-id/payment-options#actcreate|https://unipaygateway.info/billing-api/actions/v01/customers/[customer-id]/payment-options#actcreate].

If a payment option is no longer in use, it can be marked as inactive within the system.

Credit card and bank account numbers are encrypted before being stored in the database and masked when displayed on the user interface.

Creating Billing Plans

Billing plans contain parameters that define how much (amount in dollars) and how often (weekly, monthly, quarterly, semi-annually, annually) customers will be charged.

The system allows configuring recurring billing for multi-tiered pricing models. For example, you can create different billing plans for service packages with various features and allow customers to choose to pay monthly or annually. See the example of implementation via API here. To create a plan, use the corresponding API call or UI form (see tutorial).

Plans can be marked inactive if they are no longer in use.

Creating Subscriptions for Customers

To sign a customer up for a particular payment plan, a subscription should be created.

To add a subscription to an existing customer account, you must indicate the underlying payment plan, the payment option that will be the source of payments, and the type of subscription: fixed or perpetual (pay-as-you-go/until canceled). If the subscription is fixed, it is required to define the number of billing periods or times the customer will be billed.

Optionally, you can set up the first billing date. Otherwise, the billing cycle starts on the next day after the subscription has been created.

Compared to the UI (see tutorial), the billing API provides an opportunity to create a subscription without an underlying plan. In this case, it is required to indicate the amount due and Billing Cycle Type.

Managing Subscriptions

The only parameter that can be modified in the subscription details is the associated payment option. It can be adjusted any time the customer’s payment details change.

If there is a need to suspend or cancel the subscription, the subscription adjustment of one of the following types can be applied:

• cancel
• freeze
• pause

Any subscription adjustment can take effect right away or at a specific date in the future (effective date). It is important to note that the effective date must coincide with one of the upcoming billing dates.

Cancel - action that cancels (deactivates) the subscription immediately or on a specified date (effective date).
To cancel the subscription on a specific date, one of the next billing dates, starting from which the subscription will be canceled, must be specified as the effective date. Otherwise, the subscription will be canceled immediately.
Pending cancellation subscription (the one that has an effective date in the future) can be uncancelled before the effective date. In case the subscription has been canceled right away, or the effective date has already passed, the cancellation cannot be reverted.

Freeze - action that suspends the subscription for a specified period (one or more billing cycles).
Frozen subscriptions can be unfrozen at any time, and the customer will be billed on the next scheduled billing date.

Pause - action that suspends the subscription immediately or on a specified date for an undetermined period.
Previously paused subscriptions can be unpaused at any time, and the customer will be billed on the next scheduled billing date.

View specifications and tutorial to find out more about cancel/uncancel, freeze/unfreeze, pause/unpause actions.

Subscription Life Cycle

The subscription during its life cycle may have the following statuses:

• Unbilled - indicates that no billing occurred since the subscription was created.
• Deferred - indicates that no invoice will be generated in the upcoming billing associated with the subscription.
• Current - indicates that the subscription is active.
• Freeze - indicates that the invoices won't be generated within the pre-defined number of upcoming billings (freeze length) .
• Paused - indicates that the subscription is paused.
• Cancelled - indicates that the subscription is cancelled.
• Expired - indicates that all payments associated with the subscription have been made; available only for fixed subscriptions.

The transitions between subscription statuses may be triggered by the actions performed by the users or by the system actions (jobs/timers).

The typical scenarios of the statuses transitions are displayed on the diagrams below, where:

• Subscription.firstBillingDate - the date when the first invoice associated with the subscription is generated;
• Cycle.nextBillingDate - the next date of billing within the billing cycle associated with the subscription;
• Subscription.lastBillingDate - the date when the last invoice associated with the subscription is generated;
• .effectiveDate - the date when an action with the subscription (pause/unpause, freeze/unfreeze, cancel/uncancel) comes into force.
• Cycle.billingDate - any date of billing sheduled within the billing cycle associated with the subscription.
• Cycle.billingDate-1 - the day before the billing under a particular billing cycle.

Subscription Regular Life Cycle

Freezing Subscription

Pausing Subscription

Cancelling Subscription

Customer Balance and Customer Transaction Types

Recurring billing is also used to keep track of payments and outstanding charges of a customer. Each customer has an account balance against which all future invoices and credits are applied.
Customer balance - Resulting of all customer transactions that represent the actual amount of debt of a customer or a merchant. A positive (outstanding) balance represents the amount due on the customer´s next invoice. A negative balance means that the merchant owes money to the customer (can be the ground for a refund).


Customer balance calculation is based on two types of customer transactions: revenue-related and payment-related.
Revenue-related transactions represent an increase or decrease of the customer’s debt that imposes payment obligations on a customer or merchant but does not imply physical movement of money from the customer's account to merchant´s (or vice versa). Among them: invoices, fees, and credits.
Invoice - Transaction that represents the outstanding customer balance (increase in debt) to be paid by the customer for a purchased product or a service.
Fee - Transaction surcharged to the account automatically by the system when a specific condition occurs or is met. The fee can be charged to a customer only if this condition is explicitly stated in the agreement between the customer and merchant. In order for the fee to be applied correctly, a policy indicating the principal for fee withholding has to be configured.
Credit - Transaction that represents the decrease in customer’s debt in case of cancellation of purchase, applied discounts, etc.

Payment-related transactions represent payments collected from or returned to a customer. Among them: claims, payments, and refunds.
Claim - Attempt by the billing system to collect a recurring payment against the outstanding (positive) balance on a specific due date. Claims are processed in batch files. The result of the claim transaction is obtained within 3 days upon submission. Thus, within this period of time decline may be returned.
Payment - Transfer of funds from the customer to the merchant that covers debts represented by invoices. The result of a payment transaction is obtained in real-time and is final.
Refund - Transaction that represents an actual return of the money to a customer that covers the debt of a merchant represented by credit. For example, a refund is made if it was decided to return the amount of negative balance to a customer rather than apply it to other invoices due for payment.


In case you need to cancel a transaction that has been either created or processed, use the reverse action. After the action is applied, the indicate transaction is reversed. Note that the transaction cannot be returned to its initial state after reversal. A list of the transaction types that can be reversed, as well as their final states, are listed below.

All above-mentioned transaction types are merchant-initiated. They are submitted by a merchant via billing module UI or API.
Along with them, there are bank/processor-initiated transactions. They are retrieved from a processor and imported to Unibill automatically from the processing module. Among them:
Return - represents a direct debit payment that has not been honored by a bank.
Chargeback - represents a reversal of a prior outbound transfer of funds from a customer's payment card to a merchant.
Chargeback Reversal - represents a reversal of a payment card chargeback, i.e. money is given back to the merchant or customer.

Collecting Payments

Let us view the most common scenarios when the payments can be collected.

1. One-time payment is a regular purchase that is not related to any of the current subscriptions that the customer may have.
Prior to collecting the payment, the fact of a one-time purchase should be recorded with an invoice. This way if the payment turns bad in the future, the system will still recognize outstanding balance for the product or service that has been delivered.

2. Past due refers to a payment that has not been collected on the due date of some previously created invoice. At a time when the payment is collected the customer has an unpaid balance. When collecting a past due payment, there is no need to create an invoice because it already exists in the system. In this case, it’s enough to process a payment transaction to collect the outstanding amount (or some part of it).

3. Prepayment/advance payment is a payment collected for some future invoices.
To collect a prepayment there is no need to create an invoice.

*transaction~create API call **transaction~process API call
Both revenue- and payment-related transactions (Invoices, Credits, Fees, Payments, and Refunds) can be registered in the system using transaction~create operation. As a result, the transaction will be created in the system and used in the calculation of the customer´s balance. However, payment-related transactions (Payments and Refunds) created this way won´t get actually processed through the underlying processing module. If you want the payment not only to be recorded, but also electronically processed, you should submit transaction~process API call API call. It will use the supplied credit card or bank account information to process the transaction and then will use the transaction~create operation to record the outcome under the account of the respective customer.

Issuing Credits and Refunds

There may be situations when you need to issue a refund.


*transaction~reverse API call **transaction~create API call *** transaction~process API call