haravan Billing API
Our developers and store owners love the haravan Billing API. Developers love that it integrates into their app easier than other payment systems. Store owners love that the charge shows up on their haravan invoice; no credit cards or third parties needed.
As with any other billing mechanism, with the haravan Billing API you are entitled to 80% of the revenue share.
In this article:
- Step 1: How it works
- Step 2: One-time application charge
- Step 3: Recurring application charges
- Step 4: FAQ
- Step 5: Potential errors
Step 1: How it works
With the haravan Billing API you can create and issue charges to store owners purchasing your app.
Creating and issuing charges to store owners is a multi-step process:
- You need to identify a trigger for the charge (e.g. upon app installation, service plan upgrade, individual purchase, etc.).
- Your app needs to create a charge to be issued to the store owner (e.g. recurring or one-time charges). haravan will verify the charge and return a
confirmation_urlthat will redirect the store owners to an area where they can accept/decline the charge.
- When a store owner accepts/declines the charge they will be sent to a
idfor the charge.
- If the store owner accepts your charge, your app needs the
idto activate it. Once the charge is activated, you will get paid. Failure to activate the charge will result in the charge not appearing on the store owners invoice and consequently you will not get paid.
Through the haravan Billing API, setting up free trials, discount codes, subscription renewals, and upgrading/downgrading plans is all possible and easily done.
Step 2: One-time application charge
One-time application charges are exactly what they say they are; a one-time charge created and issued to the store owner for purchasing your app. Once the store owner accepts the charge and the app activates it, the store owner is billed for their app purchase on their next invoice.
To see Application Charge endpoints, view our Application Charge Reference guide.
Step 3: Recurring application charges
Alternatively, you can create and issue a recurring application charge. The recurring application charge is applied every 30 days from the day the store owner accepts the charge. This means a shop will have its own 30-day billing cycle with haravan, plus an independent 30-day cycle for each recurring app charge.
Here's an example timeline:
|Day 0||Shop signs up; 30-day shop billing cycle starts|
|Day 5||App is installed; 30-day recurring app billing cycle starts; recurring charge is added to shop's next invoice.|
|Day 30||Shop is invoiced; app charge appears for the first time.|
|Day 35||Recurring charge cycle restarts; recurring charge is added to shop's next invoice.|
|Day 60||Shop is invoiced; app charge is included.|
Once a recurring application charge is activated and approved, the system has to handle the case where future payments are declined for some reason. If a shop stops paying its bills, haravan will freeze the account. This means that your recurring application charge will be frozen as well and you will not get paid. In the event that a shop starts payments again the shop will be unfrozen and charges will resume.
From the app developer perspective, service should continue to be provided to a shop as long as their recurring charge is in the Active state.
It should be noted that each shop can have only one recurring application charge per app. If you activate a new recurring application charge (e.g. service upgrade) for a shop that already has a recurring application charge in place, the existing recurring application charge will be cancelled and replaced by the new charge. Then, the new recurring application charge will activate. This means that upgrading and downgrading a store owner's recurring application charge or plan is straightforward; just change their plan and have them accept the new recurring charge.
To see Recurring Application Charge endpoints, view our RecurringApplicationCharge Reference guide.
Step 4: FAQ
- Can I use PayPal/Other as my billing mechanism, or do I have to use the haravan Billing API?
You can use other payment systems, but apps that use the haravan Billing API are given a higher preference when it comes to promoting apps through our newsletters, blogs, Twitter account, and other promotional mediums.
- What is my share of the revenue?
As a developer, you are entitled to 80% of the revenue.
- What happens if a shop that uses an accepted recurring app charge uninstalls my app?
If a store owner uninstalls your app they should do it before the first day of the independent app billing cycle. Otherwise, they may be charged for the entire month even if they uninstalled only one day after the cycle started. There is no pro-rating.
- What happens to my payment when a shop cancels their haravan account?
When a shop cancels their haravan account, it is the same as when a shop uninstalls an app. Recurring app charges are not prorated.
- What happens when I upgrade/downgrade an app plan for a shop with a recurring application charge?
Since a shop can only have one recurring charge per app, when you upgrade or downgrade a shop's plan, the previous recurring charge will be cancelled and replaced by the new charge. The new recurring charge will then be activated and the regular billing cycle will resume.
- What happens to my payment when a shop changes its haravan plan?
When a shop changes its haravan plan, the shop's billing cycle restarts, but the recurring app charge cycle remains unchanged.
- When does an unapproved app charge expire?
If an app charge (one-time or recurring) is not approved by the store owner within 48 hours, it expires and is deleted from the system. When this happens, you'll need to recreate the charge if you still want to bill the store owner.
- Where's my money?
The Partners Dashboard only reports the money haravan has successfully charged the store owner for the amount on their invoice, including the charges your app levied. That means if you've made a 30 day recurring charge, that charge won't be added to the running total in the Partners Dashboard until the store owner has paid haravan for the invoice the charge was added to. For this reason, it may be up to 37 days between activating the charge and it appearing in your partner dashboard total summation.
haravan store owner payment cycles are 30 days long with a 7 day invoice review period.
Step 5: Potential errors
Successful API request.
The request has been fulfilled and a new resource has been created.
400 Bad Request
The request cannot be fulfilled due to bad syntax.
Authentication is required and has not been provided or has failed.
The request was a valid request but the server is refusing to respond to it.
404 Not Found
The requested resource could not be found but could be available again in the future.
405 Method Not Allowed
A request was made of a resource using a method that is not accepted by that resource. For example, using a GET request when it should be a POST.
406 Not Acceptable
The requested resource is only capable of generating content not acceptable accroding to the Accept headers sent in the request.
411 Length Required
The request did not specify the length of the content, which is required by the requested resource.
422 Unprocessable Entity
The request was well-formed but there was some semantic errors.
500, 501, 502
haravan Server Errors.
503 Service Unavailable
The server is currently unavailable (because it is overloaded or down for service). If you reach your API limits you will recieve this error.