Billing Provider Configuration

If this sounds familiar, it's because it's exactly what Cloud CMS uses to supports its own subscription plans for Cloud CMS customers. Just as we bill our customers for metered usage of the platform, you are free to pass those costs downstream to your own clients. And you can use the very same technical capabilities and facilities to do so.

Cloud CMS offers billing provider integration that is compatible with the APIs and client libraries made available by the billing providers themselves. These billing providers will issue you some credentials (such as a public/private key and a merchant account id). You can use those on your own, in your own code and in your own products. However, you can also plug those values into Cloud CMS and Cloud CMS can manage the platform-level billing for you.

A Billing Provider Configuration is a place where you store those values. Each Billing Provider Configuration will differ slightly depending on what the individual billing provider needs to store.

We will be adding more billing provider support as it is requested.

Configuration

Billing Provider Configurations will vary from provider to provider, however there are some properties which are in common among all of them. Those properties along with any custom properties by provider type are shown below:

Common Properties

Braintree Payments Provider

Configuration Settings

Create a Billing Provider Configuration

You can create as many billing provider configurations as you would like. Billing Provider Configurations are stored within your platform and are used by your platform's registrar data stores to handle subscriptions for any tenants contained therein.

As such, you probably won't have too many billing provider configurations but you might have multiple if, for example, you wish to switch between test and production configurations.

Here is an example that creates a configuration for Braintree Payments.

platform.createBillingProviderConfiguration("braintree", {
    "environment": "SANDBOX",
    "merchantId": "<merchant id>",
    "publicKey": "<public key>",
    "privateKey": "<private key>"
});

Update a Billing Provider Configuration

There's really nothing to it. You can modify the properties of your billing provider configuration as you see fit.

// we create a billing provider configuration
// and then update it
platform.createBillingProviderConfiguration("braintree", {
    "environment": "SANDBOX",
    "merchantId": "<merchant id>",
    "publicKey": "<public key>",
    "privateKey": "<private key>"
}).update({
    "title": "My Braintree configuration"
}).then(function() {
    console.log("The title of this billing provider configuration is: " + this.getTitle());
});

Delete a Billing Provider Configuration

You can delete billing provider configurations as you wish. If a billing provider configuration is presently in use by a registrar, this will throw back at you (a good thing).

billingProviderConfiguration.del();

Read a Billing Provider Configuration

You can read a Billing Provider Configuration by its _doc ID field or by its key field.

var authgrant = platform.readAuthenticationGrant("<my authentication grant id>");

List Billing Provider Configurations

You can retrieve a list of Billing Provider Configurations for your platform quite easily. The following code hands back the full list.

platform.listBillingProviderConfigurations();

You can then iterate over the list to pick at what you'd like.

platform.listBillingProviderConfigurations().each(function() {
    console.log("Billing Provider Configuration title: " + this.get("title"));
});

Retrieving the full list is potentially an expensive operation, depending how many items you have. The more your retrieve, the more data goes over the wire and so forth. Thus, you might wish to paginate your call and retrieve a subset of the total list at a time.

Here is an example that retrieves in pages of size 10. It starts on the second page (by skipping to starting index 20). It also sorts by the title field in a descending sequence.

platform.listBillingProviderConfigurations({
    "limit": 10,
    "skip": 20,
    "sort": { "title": -1 }
}).each(function() {
    console.log("Billing Provider Configuration title: " + this.get("title"));
});

You don't have to have all of the pagination parameters (limit, skip and sort). You might only want to include one or two. It's up to you.

Query Billing Provider Configurations

You can run custom queries against your Billing Provider Configurations to find exactly what you're looking for. Here is a query that looks for Billing Provider Configurations for "braintree".

platform.queryBillingProviderConfigurations({
    "providerId": "braintree"
});

Here is that same query followed by an iteration over the result map.

platform.queryBillingProviderConfigurations({
    "providerId": "braintree"
}).each(function(id) {
    console.log("Found a Billing Provider Configuration: " + id + " with title: " + this.get("title"));
});

Finally, you can mix queries with pagination to reduce data over the wire and speed up performance. Here is that same query with some pagination thrown in. We limit to pages of size 10 and sort by title.

platform.queryBillingProviderConfigurations({
    "providerId": "braintree"
},{
    "limit": 10,
    "skip": 20,
    "sort": {
        "title": -1
    }
}).each(function(id) {
    console.log("Found a Billing Provider Configuration: " + id + " with title: " + this.get("title"));
});