Clover Platform Docs

Billing lifecycle

Clover processes the charges for a merchant’s app usage and tracks the charges through various statuses of the billing lifecycle. Using the Developer Dashboard, you can track the transactions of merchants in the Billing > Transactions page. See statements for disbursements to you in the Billing > Statements page.

The following figure shows you the workflow of a charge through various Charge Statuses in the billing lifecycle.

The billing lifecycle showing the happy path, refund, and the ACH reject charge status workflow.

Monthly payment workflow

Clover's billing does the following:

  • Tracks app usage, generates charges, and sets the charge status to Pending.
  • Bills in advance on the first of the month for paid subscriptions, adjusts the previous month’s refunds, and changes the charge status from Pending to In Progress.
  • Attempts to debit the merchant's bank account and changes the charge status to Billed.
  • Pays your share of the amount in the third week of the following month and sets the charge status to Disbursed.
  • Send you a confirmation email.

Clover bills partial monthpartial month - The first prorated charge added when a merchant installs a new app and the installation occurs after the first of the month., or prorated subscriptionprorated subscription - A merchant subscription tier adjustment, when a merchant downgrades their subscription, or uninstalls an app, and Clover adjusts the charge difference in the current month's advance on the merchant account. charges based on the situation.

🚧

IMPORTANT

In the EU, ACH rejected charges continue in the In Progress charge status. You don't see the charges in the Incurred charge status.

Clover billing does the following when a merchant fails to pay the amount due:

  • Tracks app usage, generates charges, and sets the charge status to Pending.
  • Bills in advance on the first of the month for paid subscriptions, adjusts the previous month’s refunds, and changes the charge status from Pending to In Progress.
  • Attempts to debit the merchant's bank account and changes the charge status to Billed.
  • Sets the rejected charges to the ACH Reject status.
  • Sets all existing pending charges or refunds to the Incurred status.
  • Sends an email to the merchant asking them to update their banking information and includes the balance due in the next month’s statement.
  • Attempts to debit the account a second time in a couple of days if the reason for ACH Reject is insufficient funds. For other reject reasons, Clover attempts to debit the account only once.
  • Sets all subsequent charges to Incurred.
  • Allows you to request refunds for the incurred charges.
  • Creates a new refund charge associated with the main charge in the Refund Incurred status. See Processing Refunds to learn more.
  • Sets the merchant account to the Lapsed status when the charge status is ACH Reject.
  • Changes the Incurred charge status to Pending if the merchant fixes their bank account and includes the incurred charges to the next month’s account statement.

Reasons for ACH Reject

Because Clover serves small and medium businesses, we expect to have issues with some merchants paying Clover on time.

There are several reasons why payments to Clover fail:

  • Insufficient funds
  • Account was closed or doesn’t exist
  • Invalid bank account number or account incorrectly set up
  • Payment stopped
  • Bank account frozen
  • Merchant goes out of business

Processing refunds

Clover calculates prorated refunds when merchants change subscriptions or uninstall an app. If a merchant requests a full refund, you can initiate a refund for the remaining transactions from the Developer Dashboard.

Initiate refunds

On the Developer Dashboard, in the Billing section:

  1. Search for a specific transaction or merchant.
  2. Click a transaction to open the Billing History panel.
  3. Select an app and view the charges on the app in various statuses.
  4. Click a transaction charge to display the Charge Details panel.
  5. Click Refund Charge to refund charges in the Pending, Incurred, In Progress, or Billed statuses.
  6. Clover creates a new charge in the Refund Pending charge status.
  • You can cancel the refund if the charge status is either Refund Pending or Refund Incurred.

Refunds workflow

Refund scenarios for merchant downgrade or uninstalling an app, ACH Reject, and Incurred charges.

You can do the following from the Developer Dashboard:

  • Initiate refunds for changes in the Pending, In Progress, or Billed charge statuses.
  • Cancel a refund as long as the refund is still pending.
  • See the charge status changes to Refund In Progress after Clover exports the refund charges.
  • If the refund completes successfully, the charge status changes to Refunded.
  • If the refund fails, it changes to Refund ACH Reject.

📘

NOTE

When charges are in the Disbursed status, you can’t initiate refunds from the dashboard. Contact the Clover App Market team to initiate refunds.

Refund scenarios

Clover-initiated refund

  • When a merchant changes subscription tiers or uninstalls an app, Clover creates a new Refund Downgrade Pending charge, and adjusts the prorated amount in the next billing cycle.
  • If the merchant account is in the Lapsed status, the charge goes into the Refund Downgrade Incurred charge status. The workflow resumes when the merchant fixes their bank account.
  • On the first of the following month, the refund charge status changes to Refund Downgrade In Progress.
  • After the refund is successful, the charge status changes to Refunded Downgrade.
  • If the refund fails, the status changes to Refund Downgrade ACH Reject.

Developer-initiated refund

  • When you refund a charge from the Developer Dashboard, Clover creates a new Refund Pending charge.
  • If the merchant account is in the Lapsed status, the charge goes into the Refund Incurred charge status. The workflow resumes when the merchant fixes their bank account.
  • You can cancel the refund before it goes to the Refund In Progress charge status.
  • On the first of the following month the refund charge status changes to Refund In Progress.
  • After the refund is successful, the charge status changes to Refunded.
  • If the refund fails, the status changes to Refund ACH Reject.

Handling merchant payment delays

When there is an issue with a merchant's bank account and a charge is unpaid, several things happen. The charges that were previously ACH rejected, move to the ACH Reject status. All Pending or other future charges move to the Incurred status.

You can see Incurred charges on the Developer Dashboard. You won't be paid for these charges until the merchant has fixed their bank account with Clover.

After the merchant corrects their bank information, Clover moves the incurred charges to the Pending status and exports them for processing during the next month’s billing cycle. You’re paid according to the normal payout schedule in the third week of the following month.

You can reach out to the merchants whose charges are in the ACH Reject charge status and ask them to update their bank information. Merchants can update their bank information by calling Clover Customer Support.

Alternatively, you can handle this situation within your app. Use the billing_info endpoint or the getAppBillingInfo() method to get a merchant's billing information. With this information, you can find alternative ways of handling Lapsed merchants after repeated ACH Rejects on their bank account. Clover’s Developer Agreement recommends this as your responsibility in Part 1, section 8.5.

Getting paid

You can view the amount Clover disbursed to you and the transactions in various statuses in the Billing section on the Developer Dashboard. View your monthly statements in the Statements section to see the exact charges to merchants and the amount disbursed to you.

The Billing section shows you the following information on the amounts charged to merchants for your apps and the amounts disbursed to you.

Total Number of Charges: Total number of charges to billable merchants

Total Billable Merchants: Total number of billable merchants

The Statements section shows you the Total Charge and Disbursed amounts for a billing cycle. The disbursed amount is your share of the total charge to merchants. The amount will vary depending on refunds and delays with collecting amounts from merchants. For example, refunding a charge or a delay in collecting a charge from a merchant may cause that portion of your payment to roll over to the next month.

You can see the tax amount against each charge on your statement. See how order totals are calculated.

Updated 26 days ago


Billing lifecycle


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.