Introduction

The OpenChannel API and webhooks allow a custom payment processing or billing system to be integrated with your OpenChannel marketplace. In your dashboard, payments must be enabled and ‘Custom’ must be selected as the gateway in order to use the Custom Gateway API endpoints. Unlike with other supported payment gateways, the Custom Gateway will not attempt to automatically enforce and process payments. Instead, you (the marketplace owner), will be able to integrate with your own payment processing and billing system.

In this article we will take a look at how pricing models are setup, how app ownership works and how to integrate your own billing system.

How to setup a pricing model for apps

Each app can have many different (pricing) models. Typically pricing models are setup during app creation. As part of the Create App API, an optional model parameter can be passed in order to set the models that are available for this app. If no model is provided then the app will default to a free model.

Free model example:

{ 
    "type": "free", 
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD"
  }

Alternatively, the desired model for a user can be overridden by supplying the model parameter when ‘installing’ the app using the Install App API. This gives the flexibility in order to change the price, period or any other values based on user context. For additional flexibility, the model object also contains a customData object which can be used to help orchestrate more complicated pricing models.

For models, there are three model types: Free, Single and Recurring. First, a free type requires no payment at all in order to be installed. A single type requires a single payment to be made for the app to be owned outright. Last, a recurring type requires regular payments to be made in order for a subscription to an app to be maintained.

In addition to model types there are two model subtypes: First, a seat subtype indicates that the price is applicable on a ‘per seat’ basis where the user may one one or more seats. Last, a usage subtype indicates that this app will be subject to usage based pricing.

One-time pricing models

In this model, the user pays a single flat fee in order to own the app perpetually.

{ 
    "type": "single", 
    "price": 499, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD"
 }

A one-time model example for an app that costs $4.99 USD

Recurring pricing models

In this model, a user will pay a recurring fee for the ability to use an app over a certain period of time.

{ 
    "type": "recurring", 
    "price": 499, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD",
    "billingPeriod": "monthly"
}

A recurring model example for an app that costs $4.99 USD per month

Seat based pricing models

In this model, a user is able to purchase multiple licenses or ‘seats’ for a single app. 

{ 
    "type": "recurring", 
    "subtype": "seat"
    "price": 499, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD",
    "billingPeriod": "monthly"
}

A seat model example for an app that costs $4.99 USD per month per seat.

{ 
    "type": "single", 
    "subtype": "seat",
    "price": 499, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD",
    "billingPeriod": "monthly"
}

A seat model example for an app that costs $4.99 USD (one-time) per seat.

Usage based pricing

In this model, a user will pay a fee based on how much they use the app.

{ 
    "type": "free",
    "subtype": "usage",
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD",
    "customData": {
        "api-call-tiers": [
            {"number": 1000, "price": 500},
            {"number": 10000, "price": 1000},
            {"number": 100000, "price": 2000},
        ]
    }
}

A usage model example for an app that costs nothing upfront but charged based on the number of API calls. 

{ 
    "type": "recurring",
    "subtype": "usage",
    "price": 40000, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD",
    "customData": {
        "per-scan": 10
    }
}

A usage model example for an app that costs $400 per month and charges $0.10 per ‘scan’ (a sample usage metric for this app). 

How app ownership works

Ownership records tracks the relationship between a user and an app. An ownership record can be created by calling the OpenChannel Install App API and has three different types: full, subscription or trial. First, full ownership records indicate that the user fully owns the app and is not required to make any additional payments in order to retain ownership of the app. Subscription ownership records indicate that the user must pay a recurring fee in order to maintain ownership of the app. Last, trial ownership records indicate that the user is able to use the app for a specified amount of time before the ownership license expires.

In addition, an ownership record has four statuses but only three of which are used when building a custom billing integration: active, cancelled and uninstalled. First, an active ownership status signifies that the license is valid and the app is installed. A cancelled ownership status signifies that the license is no longer valid and the user must re-purchase a license to re-install the app. Last, an uninstalled ownership status signifies that the license is no longer valid and the user has uninstalled the app. Apps with a Free or Single model may be re-installed without additional cost.

How to integrate into your billing system

There are times where you’ll want to use your own billing system when selling apps on your OpenChannel marketplace. OpenChannel can integrate into many popular billing systems like Zuora, Recurly, Chargbee and more. However, integration does require the creation and hosting of a connector that listens to webhook events and makes API calls.

Integration works by allowing your billing system to become the single source of truth for all billing, payment and subscription information. As such, your billing system will be responsible for deciding when an app is installed, uninstalled and transacted upon while OpenChannel will sync it’s state accordingly.

Billing system concepts

Most billing systems are very similar and have the concept of accounts, products, invoices, transactions and subscriptions. We’ll be utilizing these different concepts in order to get our integration up and running. 

In addition, there are two types of synchronization methods: active and passive. When performing active synchronization, your billing connector be syncing OpenChannel with your billing system as events occur. For example, when a user is created in OpenChannel, the connector listens to the user.created events in order to immediately create an account in the billing system. When performing passive synchronization, your billing connector will create an account for a user on the billing system only when the user makes a purchase.

App install flow

Let’s take a look at how a basic install flow would work and the part that your custom connector plays in the integration.

In the above flow diagram, we see how the connector receives a buy request from the marketplace site. From the user’s perspective this may be initiated using an “Install App” button or a checkout flow. 

The connector’s first responsibility will be to setup the account, product and subscription on the billing system. For instance, most billing systems have the concept of an ‘account’ which represents the user in this case. In our example here, the connector can use passive synchronization at the moment of purchase to:

  1. Create a new account for the user if one doesn’t exist
  2. Create a new product representing the billing model for this app if one doesn’t exist
  3. Create a new subscription for this user (which will send out an invoice or charge a credit card)

The connector’s second responsibility is to call the OpenChannel API to mark the app as ‘installed’ and return a confirmation back to the user through the marketplace.

App uninstall flows

Let’s take a look at how a basic uninstall flow would work and the part that your custom connector plays in the integration.

In the above flow diagram, we see how the connector receives an uninstall request from the marketplace site. From the user’s perspective this may be initiated using an “Uninstall App” button. 

The connector can then cancel the subscription in the billing system and call the OpenChannel API to mark the app as ‘uninstalled’.

Recording transactions

Transactions may be recorded in OpenChannel in order to provide revenue and sales visibility to developers and marketplace administrators.

In the above flow diagram, we see how the connector receives events from the billing system which can be debit (payment) or credit (refund) events. These events can then be used to record the transaction on OpenChannel using the Add Payment or Add Refund APIs.

Displaying invoices to users

Invoices are generated and sent to users by your billing system. However, sometimes it’s convenient for a user to view their invoices directly within their marketplace account. 

To achieve this, add an API method to your connector that retrieves the list of invoices for a user from your billing system.