API

Why are you reading this?

If you are reading this, chances are you are a developer who wants to monetize an HTML5 application and you’re probably asking yourself:

“How can I handle payments in my application?”

There are two answers to this question:

You implement a payment solution yourself, but, it will require a lot of development, or
You deal with a store, but that will usually cost you 30% of your income!

MonetizeJS is the best of both worlds. Whilst applying a low rate (5% on top of Stripe’s fees), it provides painless ways to ask your users for payments and frequently check that users have actually paid without the need to implement server logic or user management.

How ?

MonetizeJS platform is built on top of Stripe, which lets you charge users and handle recurring payments. As well as calling Stripe to perform payments, MonetizeJS handles user identities for you, so that you don’t have to manage users in a database. Each MonetizeJS user is potentially linked to your application via the payment of pricing options that you define for your application.

In MonetizeJS, an application can have two different types of pricing options: one-off charge and subscription. Each application has a set of configurable pricing options, and the relation between users and pricing options is defined as follows:

A user may have a current one-off charge option for a given application, and can eventually upgrade to another charge option by paying the difference.
With that, this user may also have a running subscription option for that application, and can eventually switch to another subscription option or cancel a running subscription.

Note: while the number of pricing options is not limited, a user can only select 1 one-off charge and 1 subscription at a time for a given application.

Every time a user comes to your application, you will be able to:

Check user’s selected pricing option: one-off charge and/or subscription.
Ask for a one-off charge or a subscription via a redirection to the MonetizeJS platform.

A redirection to the MonetizeJS platform is necessary when:

the user hasn’t signed in to MonetizeJS, or
the user doesn’t have the required pricing option.

Note: once signed in for the first time, a user will automatically be signed in on that computer using a “remember me” cookie. This will prevent you from having to perform a redirection every time a user comes back to your application.

Here is a typical workflow:

Step 1: Retrieve user’s one-off charge or subscription in your application without redirection (user is supposedly signed in).
Step 2.a: If retrieve is successful, validate one-off charge/subscription in your application. If it doesn’t meet your expectations, redirect the user to the platform for payment.
Step 2.b: If retrieve fails, redirect the user to the platform for sign in and, eventually, for payment.

It’s important to note that, if you have to redirect the user for sign in, you can also tell the platform what you expect as required pricing options. Thus, the platform will be able to ask the user for a payment at the same time.

Monetize.js

Monetize.js library is suitable for client side applications (browser, HTML5 application…).

Careful! Browsers don’t protect you against user scripts. If payments are critical for your application, you can use Monetize.js client-side library to retrieve an access token and then use our REST API to securely verify payments in your back-end. See the REST API section for more information.

Load the library

Monetize.js library can be loaded from our CDN:

<script src="//cdn.monetizejs.com/api/js/latest/monetize.min.js"></script>

For your convenience, this library can also be found in GitHub and the Bower registry. Once loaded, just create a MonetizeJS object, providing your application ID:

var monetize = MonetizeJS({
    applicationID: 'YOUR_APP_ID'
});

Obtain user payments

Monetize.js provides two methods to get user payments:

immmediate: if the user has already signed in and has already paid, no redirection is required, the payments are retrieved silently.
interactive: when the user has to sign in or make a payment, a redirection to the platform has to be performed.

Immediate

getPaymentsImmediate retrieves payments without redirection, assuming the user has already signed in:

monetize.getPaymentsImmediate(function(err, payments) {
    if(payments) {
        // User is signed in, you can check payments
        console.log(payments.chargeOption);
        console.log(payments.subscriptionOption);
    }
    else {
        // User is not signed in...
    }
});

Try it

Note: In most cases, when an error occurs, you will have to call getPaymentsInteractive.

Interactive with full-page redirection

If the user hasn’t signed in or doesn’t have the expected pricing option, you will have to call getPaymentsInteractive to redirect the user to the platform.

Here is how you perform a full-page redirection:

monetize.getPaymentsInteractive({
    pricingOptions: ['subscription_option_no1', 'charge_option_no2']
});

Provide us with a list of pricingOptions to let us know which options you expect the user to pay for. Note that if the user has already paid for one of these options (or if you don’t provide any option), no payment will be requested.

Try it

If you want to give the user the opportunity to review all the pricing options and to manage previous payments, you can do that using the summary parameter:

monetize.getPaymentsInteractive({
    summary: true
});

Try it

After sign in and payment, the platform will redirect the user back to your page where you will call getPaymentsImmediate again.

Tip: You can specify a custom redirect URL (make sure you’ve added the URL to your list of authorized redirect URLs):

monetize.getPaymentsInteractive({
    pricingOptions: ['subscription_option_no1', 'charge_option_no2'],
    redirectURL: 'http://your_redirect_url'
});

Interactive with pop-up

If you prefer a pop-up window in order to keep the current page context, just add a callback, much like getPaymentsImmediate:

monetize.getPaymentsInteractive({
    pricingOptions: ['subscription_option_no1', 'charge_option_no2']
}, function(err, payments) {
    ...
});

Try it

Careful! Using pop-ups, be sure to trigger getPaymentsInteractive from a user click event, otherwise pop-ups will be blocked by the browser.
Also, note that if the user closes the pop-up unexpectedly, your callback won’t be fired.

OAuth2

MonetizeJS platform is OAuth2 compliant, which means you can perform payments through a standard OAuth2 flow and check payments using a bearer token.

When integrating with a classic OAuth2 identity provider like Google or Facebook, you usually perform a redirection for sign in and ask the user for permission. That’s what you’ll do with MonetizeJS, except that here, permission is actually a payment.

Note: The following paragraph describes how to implement the “authorization code” flow. The platform also supports “implicit grant”, but you probably want to use Monetize.js client-side library instead.

To ask a user for sign in and payments, just redirect the user to the authorize endpoint:

https://monetizejs.com/authorize?response_type=code&client_id=YOUR_APP_ID&redirect_uri=http://your_redirect_url&pricing_options=charge_option_no1,subscription_option_no2

Provide us with a comma-separated list of pricing_options to let us know which options you expect the user to pay for. Note that if the user has already paid for one of these options (or if you don’t provide any option), no payment will be requested.
Try it

If you want to give the user the opportunity to review all the pricing options and to manage previous payments, you can do that using the summary query parameter:

https://monetizejs.com/authorize?response_type=code&client_id=YOUR_APP_ID&redirect_uri=http://your_redirect_url&summary=true

After login and payment, we will redirect the user back to your redirect_uri with an authorization code (make sure you’ve added the URL to your list of authorized redirect URLs). To retrieve user payments and an access token for future validations, you will call the token endpoint from your back-end:

curl -X POST -d 'client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&code=YOUR_AUTHORIZATION_CODE&grant_type=authorization_code' https://monetizejs.com/token

The response will contain user payments so that you don’t have to call the REST API straight away to validate payments:

{
    "access_token": "ACCESS_TOKEN",
    "token_type": "Bearer",
    "app": "APP_ID",
    "user": "USER_ID",
    "payments": {
        ...
    }
}

Note that the access token has no expiration date, so you can reuse it anytime to check user payments using the REST API. To perform another payment, you will start a new OAuth2 flow, changing the pricing_options parameter to your needs.

Careful! You are responsible for keeping your client_secret and user access_token in a safe place.

REST

MonetizeJS platform has a single end-point in its REST API, GET /api/payments, the purpose of which is to retrieve and verify user payments for a given application. An access token has to be passed as a URL parameter:

curl https://monetizejs.com/api/payments?access_token=ACCESS_TOKEN

Or in the authorization header of the HTTP request:

curl https://monetizejs.com/api/payments -H "Authorization: Bearer ACCESS_TOKEN"

Note: You can retrieve an access token using the OAuth2 flow or using the Monetize.js client-side library by calling getTokenImmediate or getTokenInteractive the same way you would call getPaymentsImmediate or getPaymentsInteractive. Unlike the OAuth2 token, the validity of a client-side token is 1 hour (automatically refreshed by the Monetize.js library).

Security note: The result object will contain the ID of the application used to generate the token. You should check that this ID corresponds to your actual application in order to prevent malicious users injecting fake application tokens.

The end-point supports CORS, so that you can call it from the browser:

$.ajax('https://monetizejs.com/api/payments?access_token=ACCESS_TOKEN')
    .then(function(payments) {
        ...
    });

JSONP is also supported using the callback parameter.

CouchDB

MonetizeJS uses CouchDB in back-end to store users, applications and transaction logs. As a matter of fact, you can query MonetizeJS databases using the standard CouchDB REST API.

Session authentication

To access the database, you first have to log in using your MonetizeJS user ID and your password. You will have to use cookies as you will access the database via an authenticated session.

curl -X POST -d 'name=YOUR_USER_ID&password=YOUR_PASSWORD' --cookie ./tmp_file https://db.monetizejs.com/_session

Retrieve an application

The apps database contains documents describing your applications (metadata, pricing options, currencies…). To retrieve your application, use the application ID as a document ID:

curl --cookie ./tmp_file http://db.monetizejs.com/apps/YOUR_APP_ID

Retrieve user payments

The user_app_payments database contains documents that describe payments of a specific user to an application. To retrieve payments of a user for your application, you will use the following view:

curl -G -d 'key=["USER_ID","APP_ID"]&include_docs=true&reduce=false' --cookie ./tmp_file http://db.monetizejs.com/user_app_payments/_design/by_user_and_app/_view/default

Buttons

You can put a MonetizeJS button like these on any static website:

button-26.png

button-32.png

button-38.png

Just include the following HTML code in your page:

<a href="https://monetizejs.com/authorize?client_id=YOUR_APP_ID&summary=true">
    <img src="//cdn.monetizejs.com/resources/button-32.png">
</a>

Or the following markdown:

[![](//cdn.monetizejs.com/resources/button-26.png)](https://monetizejs.com/authorize?client_id=YOUR_APP_ID&summary=true)

Tip: As you would do in an OAuth2 flow, you can specify a redirect_uri query parameter if you want the user to be redirected to your website after payment (make sure you’ve added the URL to your list of authorized redirect URLs).

For your convenience, an SVG version of the button can be found here.