Billing

Note

All app fees, payment from the merchant for use of your app, and merchant-customer payment processing must be implemented within the Clover and/or First Data platforms. Refer to the Developer Agreement for details.

If you choose to charge for your app, there are three options:

  1. Subscription billing – A recurring monthly subscription
  2. Metered billing – A charge per action
  3. A combination of subscription and metered billing

All charges are processed at the beginning of the month. Disbursements are issued in the middle of the following month (about the third week). For example, the status of a monthly subscription charge covering January 1, 2017 to February 1, 2017 will be Charge Pending/In Progress on January 1, but will not be Disbursed to you until mid-February.

Also, all refunds issued for the previous month get processed in beginning of the month and are disbursed before you are paid.

With any billing, you can enable a 30-day free trial by ticking a checkbox in your developer dashboard under the Pricing section. The 30-day free trial option allows merchants to try your app to ensure that it suits their business needs. The 30-day free trial is handled by Clover billing, nothing needs to be coded on your end. On the 31st day, billing will start for any of the billing methods if the merchant has not uninstalled your app.


Subscription Billing

The subscription model is based on a recurring monthly charge. On the first of each month, the merchant is billed the cost associated with the subscription tier that was selected when the app was downloaded. For example, you might offer a free tier with limited functionality to encourage merchants to try your app, as well as a paid tier they can upgrade to later.

On the day of the original download or the 31st day of the month (if a 30-day free trial is enabled), Clover billing will show an entry for a Partial Month pro-rated charge in the Charge Pending stage for the day of the install until the end of the month day, but the billing stage will not change to In Progress until the beginning of the following month.

Metered Billing

Metered billing allows you to define specific actions for which the merchant is charged. With metered billing, you define the action and price in the Developer Dashboard, then use Clover’s web and Android methods to notify us when an action has occurred. On a monthly basis, Clover will tally all of the actions and bill the proper amount.

For example, consider an online order app that charges $0.40/order. On the first of the month you would see a charge for $2.00 if metered billing was triggered five times during the previous month.

Note

You will not be able to edit, add, or delete metered pricing after your app has been approved.

REST API Endpoint

The REST API endpoint for metered billing is:

POST /v3/apps/{aId}/merchants/{mId}/metereds/{meteredId}

See the REST API Reference and REST API web page for more information.

Android AppsConnector Method

The Android AppsConnector Method for metered billing is:

logMetered(String meteredId, int numberOfEvents)

Android Example

The following example demonstrates how to implement metered billing through the Android AppsConnector method.

Account account = CloverAccount.getAccount(this);

final AppsConnector appsConnector = new AppsConnector(this, account);

new AsyncTask<Void, Void, Void>() {

 @Override
 protected Void doInBackground(Void[] params) {
 try {
 appsConnector.logMetered("{meteredID}", 1);
 return null;
 } catch (Exception e) {
 e.printStackTrace();
 }
 return null;
 }
}.execute();

Subscription and Metered Billing

With a combination of subscription and metered billing, the merchant will see two charges – a single subscription charge for the new month, and a separate charge for the metered billing from the previous month’s total triggers.

One example would be a gift card app with the following billing structure:

  • A $10/month subscription charge for up to five gift cards
  • $2 for every gift card thereafter

If the merchant used eight gift cards during the month of May, it would be charged the following amounts on June 1st:

  • A $10 subscription charge for June 1-July 1
  • A $6 (3 additional gift cards * $2 = $6) metered charge for May

See the Subscription Billing and Metered Billing sections above for more information.

Important

You cannot add or change metered billing after the app has been approved. You can add or change subscription tiers and pricing at any time, but any merchants who previously downloaded the app will continue under the old subscription price until that merchant uninstalls and reinstalls the app.

Billing Stages

A charge will pass through the status flow illustrated on the top level of the diagram below until it is finally disbursed.

A refund will pass through the status flow illustrated on the bottom level of the diagram below until it reaches the status Refund Downgrade In Progress.

Overview

  • Charge Pending – The merchant charge is scheduled. It has been registered with the Clover system but hasn’t begun to process.
  • In Progress – The merchant charge is being processed. You can still refund the charge during stage.
  • Billed – The merchant account has been debited the charged amount.
  • Disbursed – The funds have been released to your bank account.

The Charge Pending stage ends on the first of the month and becomes In Progress. You will only see the status Charge Pending on Partial Month charges before they move to the In Progress stage on the first of the following month (or if the developer account isn’t configured properly).

Similarly, any Prorated Subscriptions (resulting from merchants moving to a lower pricing tier or uninstalling the app) will change from Refund Downgrade Pending to Refund Downgrade In Progress on the first of the following month.

In Progress means that the charge has been submitted to the merchant’s bank account for debiting. The typical length for this stage is 10-15 business days. Note that the charge may remain in this state if there are any issues with the merchant’s bank account, or the information relating to it.

Next, the charge will proceed to the Billed stage, which means Clover has debited the merchant. If you see a charge stuck in the Billed stage, verify that the developer account is set up correctly.

ACH Reject means the charge was rejected by the merchant’s bank. When this happens, Clover sends an email to the merchant asking them to update their banking information. Clover will reattempt ACH two additional times after the initial reject. As a developer, you can reach out to the merchant and ask them to contact Clover support to update their billing. You may use your own discretion on degrading usage of your product until they have sorted out their account.

After Billed or ACH Reject, the next and final state is Disbursed. This means the funds have been paid out to your bank account.

Getting a Merchant’s Billing Information

Using Clover’s web and Android methods, you can determine:

  • A merchant’s current subscription tier
  • If a paid app offers a trial, whether the merchant is using a trial, and if so, when its billing start time is
  • Whether a merchant’s account is ACTIVE or LAPSED (an account is marked as lapsed when a merchant’s credit card is declined, or when a merchant hasn’t entered credit card information)
  • The number of days lapsed (if applicable)

REST API Endpoint

The REST API endpoint for obtaining merchant billing information is:

GET /v3/apps/{aId}/merchants/{mId}/billing_info

See the REST API Reference and REST API web page for more information.

The following states will be applicable:

  • Normal: An account where the merchant is paying as agreed
  • Lapsed: A delinquent account that Clover will not continue to bill

Android AppsConnector Method

The Android AppsConnector method for obtaining merchant billing information is:

getAppBillingInfo()

Android Example

The following snippet demonstrates how to obtain merchant billing information with the getAppBillingInfo() method.

Account account = CloverAccount.getAccount(this);

final AppsConnector appsConnector = new AppsConnector(this, account);

new AsyncTask<Void, Void, AppBillingInfo>() {

 @Override
 protected AppBillingInfo doInBackground(Void[] params) {
 try {
 return appsConnector.getAppBillingInfo();
 } catch (Exception e) {
 e.printStackTrace();
 } 
 return null;
 }
}.execute();

Refunds

The Refund button is available under your app’s billing section during the In Progress and Billed states for the previous and current month. When Clover begins processing the developer disbursement (or if there is an ACH Reject), the Refund button will no longer appear (as of the first of the following month), and you will have lost the opportunity to provide a refund to the merchant via the Clover billing system.

There is also a Cancel Charge refund button for Partial Month charges and metered charges that are in the Charge Pending state. It will turn into a Refund button when the state changes to In Progress on the first of the month.

When a merchant uninstalls your app, reinstalls the app, or switches to a lower pricing tier, a Refund Downgrade Pending will be issued for a Prorated Subscription. The status will change to Refund Downgrade In Progress (the final state) on the first of the following month.

Clicking on the Refund button will change the status to Refund Pending (if billed). Afterwards, the developer will be able to click the Cancel Refund button for the transaction until the refund has been processed (usually on the 1st of the month).

Targeted Links

Once you’ve set up your subscriptions, you can send merchants to your app using a link that pre-selects a given subscription level. To do this, add the subscriptionId={sID} query parameter to the URL. Here’s an example that targets Charity Checkout’s free subscription:
https://www.clover.com/appmarket/apps/X9A8J6KXNY96J?subscriptionId=E2CH2KW99MB8R

You can also launch a subscription page from an Android app.

When using targeted links, be sure to lead merchants to the public URL for your app (not to your developer page).

Determining Whether a Merchant is Billable

If you have a paid app, you may want to know whether you can bill a given merchant. For example, test merchant accounts used by developers and sales people are not billable, so you will not be paid for apps installed to these types of accounts.

Use the following endpoint to determine whether a merchant is billable:

GET /v3/merchants/{mId}?expand=gateway

This call returns an isBillable property. (Note that you must use the expand=gateway parameter to prevent the isBillable field from returning as null.) If isBillable is true, the merchant is a live, billable merchant.

Note

See the REST API Reference and the REST API web page for more information about working with the API.