In-App Purchase

In-App Purchase (IAP) allows providers of ongoing services through Odoo apps to be compensated for ongoing service use rather than — and possibly instead of — a sole initial purchase.

In that context, Odoo acts mostly as a broker between a client and an Odoo App Developer:

  • Users purchase service tokens from Odoo.
  • Service providers draw tokens from the user’s Odoo account when service is requested.

Overview

The Players

  • The Service Provider is (probably) you the reader, you will be providing value to the client in the form of a service paid per-use.
  • The Client installed your Odoo App, and from there will request services.
  • Odoo brokers crediting, the Client adds credit to their account, and you can draw credits from there to provide services.
  • The External Service is an optional player: you can either provide a service directly, or you can delegate the actual service acting as a bridge/translator between an Odoo system and the actual service.

The Credits

‘Normal’ service flow

If everything goes well, the normal flow is the following:

  1. The Client requests a service of some sort.
  2. The Service Provider asks Odoo if there are enough credits for the service in the Client’s account, and creates a transaction over that amount.
  3. The Service Provider provides the service (either on their own or calling to External Services).
  4. The Service Provider goes back to Odoo to capture (if the service could be provided) or cancel (if the service could not be provided) the transaction created at step 2.
  5. Finally, the Service Provider notifies the Client that the service has been rendered, possibly (depending on the service) displaying or storing its results in the client’s system.

Insufficient credits

However, if the Client’s account lacks credits for the service, the flow will be as follows:

  1. The Client requests a service as previously.
  2. The Service Provider asks Odoo if there are enough credits on the Client’s account and gets a negative reply.
  3. This is signaled back to the Client.
  4. Who is redirected to their Odoo account to credit it and re-try.

Building your service

For this example, the service we will provide is ~~mining dogecoins~~ burning 10 seconds of CPU for a credit. For your own services, you could, for example:

  • provide an online service yourself (e.g. convert quotations to faxes for business in Japan);
  • provide an offline service yourself (e.g. provide accountancy service); or
  • act as intermediary to an other service provider (e.g. bridge to an MMS gateway).

Register the service on Odoo

The first step is to register your service on the IAP endpoint (production and/or test) before you can actually query user accounts. To create a service, go to your Portal Account on the IAP endpoint (https://iap.odoo.com for production, https://iap-sandbox.odoo.com for testing, the endpoints are independent and not synchronized). Alternatively, you can go to your portal on Odoo (https://iap.odoo.com/my/home) and select In-App Services.

Log in then go to My Account ‣ Your In-App Services, click Create and provide the informations of your service.

The service has seven important fields:

  • name - ServiceName: This is the string you will need to provide inside the client’s app when requesting a transaction from Odoo. (e.g. self.env['iap.account].get(name)). As good practice, this should match the technical name of your app.
  • label - Label: The name displayed on the shopping portal for the client.
  • icon - Icon: A generic icon that will serve as default for your packs.
  • key - ServiceKey: The developer key that identifies you in IAP (see your service) and allows to draw credits from the client’s account. It will be shown only once upon creation of the service and can be regenerated at will.
  • trial credits - Float: This corresponds to the credits you are ready to offer upon first use to your app users. Note that such service will only be available to clients that have an active enterprise contract.
  • privacy policy - PrivacyPolicy: This is an url to the privacy policy of your service. This should explicitly mention the information you collect, how you use it, its relevance to make your service work and inform the client on how they can access, update or delete their personal information.

You can then create credit packs which clients can purchase in order to use your service.

Packs

A credit pack is essentially a product with five characteristics:

  • Name: name of the pack,
  • Icon: specific icon for the pack (if not provided, it will fallback on the service icon),
  • Description: details on the pack that will appear on the shop page as well as the invoice,
  • Amount: amount of credits the client is entitled to when buying the pack,
  • Price: price in EUR (for the time being, USD support is planned).

Odoo App

The second step is to develop an Odoo App which clients can install in their Odoo instance and through which they can request the services you provide. Our app will just add a button to the Partners form which lets a user request burning some CPU time on the server.

First, we will create an odoo module depending on iap. IAP is a standard V11 module and the dependency ensures a local account is properly set up and we will have access to some necessary views and useful helpers.

coalroller/__manifest__.py
{
    'name': "Coal Roller",
    'category': 'Tools',
    'depends': ['iap'],
}
coalroller/__init__.py
# -*- coding: utf-8 -*-

Second, the “local” side of the integration. Here we will only be adding an action button to the partners view, but you can of course provide significant local value via your application and additional parts via a remote service.

coalroller/__manifest__.py
    'name': "Coal Roller",
    'category': 'Tools',
    'depends': ['iap'],
    'data': [
        'views/views.xml',
    ],
}
coalroller/views/views.xml
<odoo>
  <record model="ir.ui.view" id="partner_form_coalroll">
    <field name="name">partner.form.coalroll</field>
    <field name="model">res.partner</field>
    <field name="inherit_id" ref="base.view_partner_form" />
    <field name="arch" type="xml">
      <xpath expr="//div[@name='button_box']">
        <button type="object" name="action_partner_coalroll"
                class="oe_stat_button" icon="fa-gears">
          <div class="o_form_field o_stat_info">
            <span class="o_stat_text">Roll Coal</span>
          </div>
        </button>
      </xpath>
    </field>
  </record>
</odoo>

We can now implement the action method/callback. This will call our own server.

There are no requirements when it comes to the server or the communication protocol between the app and our server, but iap provides a jsonrpc() helper to call a JSON-RPC2 endpoint on an other Odoo instance and transparently re-raise relevant Odoo exceptions (InsufficientCreditError, odoo.exceptions.AccessError and odoo.exceptions.UserError).

In that call, we will need to provide:

  • any relevant client parameter (none here),
  • the token of the current client that is provided by the iap.account model’s account_token field. You can retrieve the account for your service by calling env['iap.account'].get(service_name) where service_name is the name of the service registered on IAP endpoint.
coalroller/__init__.py
# -*- coding: utf-8 -*-
from . import models
coalroller/models/__init__.py
from . import res_partner
coalroller/models/res_partner.py
# -*- coding: utf-8 -*-
from odoo import api, models
from odoo.addons.iap import jsonrpc, InsufficientCreditError

# whichever URL you deploy the service at, here we will run the remote
# service in a local Odoo bound to the port 8070
DEFAULT_ENDPOINT = 'http://localhost:8070'
class Partner(models.Model):
    _inherit = 'res.partner'
    def action_partner_coalroll(self):
        # fetch the user's token for our service
        user_token = self.env['iap.account'].get('coalroller')
        params = {
            # we don't have any parameter to provide
            'account_token': user_token.account_token
        }
        # ir.config_parameter allows locally overriding the endpoint
        # for testing & al
        endpoint = self.env['ir.config_parameter'].sudo().get_param('coalroller.endpoint', DEFAULT_ENDPOINT)
        jsonrpc(endpoint + '/roll', params=params)
        return True

Service

Though that is not required, since iap provides both a client helper for JSON-RPC2 calls (jsonrpc()) and a service helper for transactions (charge) we will also be implementing the service side as an Odoo module:

coalroller_service/__init__.py
# -*- encoding: utf-8 -*-
coalroller_service/__manifest__.py
{
    'name': "Coal Roller Service",
    'category': 'Tools',
    'depends': ['iap'],
}

Since the query from the client comes as JSON-RPC2 we will need the corresponding controller which can call charge and perform the service within:

coalroller_service/controllers/main.py
import time

from passlib import pwd, hash

from odoo import http
from odoo.addons.iap import charge

class CoalBurnerController(http.Controller):
    @http.route('/roll', type='json', auth='none', csrf='false')
    def roll(self, account_token):
        # the service key *is a secret*, it should not be committed in
        # the source
        service_key = self.env['ir.config_parameter'].sudo().get_param('coalroller.service_key')

        # we charge 1 credit for 10 seconds of CPU
        cost = 1
        # TODO: allow the user to specify how many (tens of seconds) of CPU they want to use
        with charge(http.request.env, service_key, account_token, cost):

            # 10 seconds of CPU per credit
            end = time.time() + (10 * cost)
            while time.time() < end:
                # we will use CPU doing useful things: generating and
                # hashing passphrases
                p = pwd.genphrase()
                h = hash.pbkdf2_sha512.hash(p)
        # here we don't have anything useful to the client, an error
        # will be raised & transmitted in case of issue, if no error
        # is raised we did the job
coalroller_service/controllers/__init__.py
# -*- encoding: utf-8 -*-
from . import main
coalroller_service/__init__.py
# -*- encoding: utf-8 -*-
from . import controllers

The charge helper will:

  1. authorize (create) a transaction with the specified number of credits, if the account does not have enough credits it will raise the relevant error
  2. execute the body of the with statement
  3. if the body of the with executes successfully, update the price of the transaction if needed
  4. capture (confirm) the transaction
  5. otherwise, if an error is raised from the body of the with, cancel the transaction (and release the hold on the credits)

The charge helper has two additional optional parameters we can use to make things clearer to the end-user.

description
is a message which will be associated with the transaction and will be displayed in the user’s dashboard, it is useful to remind the user why the charge exists.
credit_template
is the name of a QWeb template which will be rendered and shown to the user if their account has less credit available than the service provider is requesting, its purpose is to tell your users why they should be interested in your IAP offers.
coalroller_service/controllers/main.py
    def roll(self, account_token):
        # the service key *is a secret*, it should not be committed in
        # the source
        service_key = http.request.env['ir.config_parameter'].sudo().get_param('coalroller.service_key')

        # we charge 1 credit for 10 seconds of CPU
        cost = 1
        # TODO: allow the user to specify how many (tens of seconds) of CPU they want to use
        with charge(http.request.env, service_key, account_token, cost,
                    description="We're just obeying orders",
                    credit_template='coalroller_service.no_credit'):

            # 10 seconds of CPU per credit
            end = time.time() + (10 * cost)
coalroller_service/views/no-credit.xml
<odoo>
  <template id="no_credit" name="No credit warning">
    <div>
      <div class="container-fluid">
        <div class="row">
          <div class="col-md-7 offset-lg-1 mt32 mb32">
            <h2>Consume electricity doing nothing useful!</h2>
            <ul>
              <li>Heat our state of the art data center for no reason</li>
              <li>Use multiple watts for only 0.1€</li>
              <li>Roll coal without going outside</li>
            </ul>
          </div>
        </div>
      </div>
    </div>
  </template>
</odoo>
coalroller_service/__manifest__.py
    'name': "Coal Roller Service",
    'category': 'Tools',
    'depends': ['iap'],
    'data': [
        'views/no-credit.xml',
    ],
}

JSON-RPC2 Transaction API

  • The IAP transaction API does not require using Odoo when implementing your server gateway, calls are standard JSON-RPC2.
  • Calls use different endpoints but the same method on all endpoints (call).
  • Exceptions are returned as JSON-RPC2 errors, the formal exception name is available on data.name for programmatic manipulation.

Authorize

/iap/1/authorize

Verifies that the user’s account has at least as credit available and creates a hold (pending transaction) on that amount.

Any amount currently on hold by a pending transaction is considered unavailable to further authorize calls.

Returns a TransactionToken identifying the pending transaction which can be used to capture (confirm) or cancel said transaction.

Parameters
  • key (ServiceKey) –
  • account_token (UserToken) –
  • credit (float) –
  • description (str) – optional, helps users identify the reason for charges on their account
  • dbuuid (str) – optional, allows the user to benefit from trial credits if his database is eligible (see Service registration)
Returns
TransactionToken if the authorization succeeded
Raises
AccessError if the service token is invalid
Raises
InsufficientCreditError if the account does not have enough credits
Raises
TypeError if the credit value is not an integer or a float
r = requests.post(ODOO + '/iap/1/authorize', json={
    'jsonrpc': '2.0',
    'id': None,
    'method': 'call',
    'params': {
        'account_token': user_account,
        'key': SERVICE_KEY,
        'credit': 25,
        'description': "Why this is being charged",
    }
}).json()
if 'error' in r:
    # handle authorize error
tx = r['result']

# provide your service here

Capture

/iap/1/capture

Confirms the specified transaction, transferring the reserved credits from the user’s account to the service provider’s.

Capture calls are idempotent: performing capture calls on an already captured transaction has no further effect.

Parameters
Raises
AccessError
  r2 = requests.post(ODOO + '/iap/1/capture', json={
      'jsonrpc': '2.0',
      'id': None,
      'method': 'call',
      'params': {
          'token': tx,
          'key': SERVICE_KEY,
          'credit_to_capture': credit or False,
      }
  }).json()
  if 'error' in r:
      # handle capture error
  # otherwise transaction is captured

Cancel

/iap/1/cancel

Cancels the specified transaction, releasing the hold on the user’s credits.

Cancel calls are idempotent: performing capture calls on an already cancelled transaction has no further effect.

Parameters
Raises
AccessError
r2 = requests.post(ODOO + '/iap/1/cancel', json={
    'jsonrpc': '2.0',
    'id': None,
    'method': 'call',
    'params': {
        'token': tx,
        'key': SERVICE_KEY,
    }
}).json()
if 'error' in r:
    # handle cancel error
# otherwise transaction is cancelled

Types

Exceptions aside, these are abstract types used for clarity, you should not care how they are implemented.

class ServiceName

String identifying your service on https://iap.odoo.com (production) as well as the account related to your service in the client’s database.

class ServiceKey

Identifier generated for the provider’s service. Each key (and service) matches a token of a fixed value, as generated by the service provide.

Multiple types of tokens correspond to multiple services. As an exampe, SMS and MMS could either be the same service (with an MMS being ‘worth’ multiple SMS) or could be separate services at separate price points.

class UserToken

Identifier for a user account.

class TransactionToken

Transaction identifier, returned by the authorization process and consumed by either capturing or cancelling the transaction.

exception odoo.addons.iap.models.iap.InsufficientCreditError

Raised during transaction authorization if the credits requested are not currently available on the account (either not enough credits or too many pending transactions/existing holds).

exception odoo.exceptions.AccessError

Raised by:

  • any operation to which a service token is required, if the service token is invalid; or
  • any failure in an inter-server call. (typically, in jsonrpc()).
exception odoo.exceptions.UserError

Raised by any unexpected behaviour at the discretion of the App developer (you).

Test the API

In order to test the developped app, we propose a sandbox platform that allows you to:

  1. Test the whole flow from the client’s point of view - Actual services and transactions that can be consulted. (again this requires to change the endpoint, see the danger note in Service).
  2. Test the API.

The latter consists in specific tokens that will work on IAP-Sandbox only.

  • Token 000000: Represents a non-existing account. Returns an InsufficientCreditError on authorize attempt.
  • Token 000111: Represents an account without sufficient credits to perform any service. Returns an InsufficientCreditError on authorize attempt.
  • Token 111111: Represents an account with enough credits to perform any service. An authorize attempt will return a dummy transacion token that is processed by the capture and cancel routes.

Odoo Helpers

For convenience, if you are implementing your service using Odoo the iap module provides a few helpers to make IAP flow even simpler.

Charging

class odoo.addons.iap.models.iap.charge(env, key, account_token, credit[, dbuuid, description, credit_template])

A context manager for authorizing and automatically capturing or cancelling transactions for use in the backend/proxy.

Works much like e.g. a cursor context manager:

  • immediately authorizes a transaction with the specified parameters;
  • executes the with body;
  • if the body executes in full without error, captures the transaction;
  • otherwise cancels it.
Parameters
  • env (odoo.api.Environment) – used to retrieve the iap.endpoint configuration key
  • key (ServiceKey) –
  • token (UserToken) –
  • credit (float) –
  • description (str) –
  • template credit_template (Qweb) – 
  @route('/deathstar/superlaser', type='json')
  def superlaser(self, user_account,
                 coordinates, target,
                 factor=1.0):
      """
      :param factor: superlaser power factor,
                     0.0 is none, 1.0 is full power
      """
      credits = int(MAXIMUM_POWER * factor)
      description = "We will demonstrate the power of this station on your home planet of Alderaan."
      with charge(request.env, SERVICE_KEY, user_account, credits, description) as transaction:
          # TODO: allow other targets
          transaction.credit = max(credits, 2)
          # Sales ongoing one the energy price,
          # a maximum of 2 credits will be charged/captured.
          self.env['systems.planets'].search([
              ('grid', '=', 'M-10'),
              ('name', '=', 'Alderaan'),
          ]).unlink()

Authorize

class odoo.addons.iap.models.iap.authorize(env, key, account_token, credit[, dbuuid, description, credit_template])

Will authorize everything.

Parameters
  • env (odoo.api.Environment) – used to retrieve the iap.endpoint configuration key
  • key (ServiceKey) –
  • token (UserToken) –
  • credit (float) –
  • description (str) –
  • template credit_template (Qweb) – 
  @route('/deathstar/superlaser', type='json')
  def superlaser(self, user_account,
                 coordinates, target,
                 factor=1.0):
      """
      :param factor: superlaser power factor,
                     0.0 is none, 1.0 is full power
      """
      credits = int(MAXIMUM_POWER * factor)
      description = "We will demonstrate the power of this station on your home planet of Alderaan."
      #actual IAP stuff
      transaction_token = authorize(request.env, SERVICE_KEY, user_account, credits, description=description)
      try:
          # Beware the power of this laser
          self.put_galactical_princess_in_sorrow()
      except Exception as e:
          # Nevermind ...
          r = cancel(env,transaction_token, key)
          raise e
      else:
          # We shall rule over the galaxy!
          capture(env,transaction_token, key, min(credits, 2))

Cancel

class odoo.addons.iap.models.iap.cancel(env, transaction_token, key)

Will cancel an authorized transaction.

Parameters
  • env (odoo.api.Environment) – used to retrieve the iap.endpoint configuration key
  • transaction_token (str) –
  • key (ServiceKey) – 
  @route('/deathstar/superlaser', type='json')
  def superlaser(self, user_account,
                 coordinates, target,
                 factor=1.0):
      """
      :param factor: superlaser power factor,
                     0.0 is none, 1.0 is full power
      """
      credits = int(MAXIMUM_POWER * factor)
      description = "We will demonstrate the power of this station on your home planet of Alderaan."
      #actual IAP stuff
      transaction_token = authorize(request.env, SERVICE_KEY, user_account, credits, description=description)
      try:
          # Beware the power of this laser
          self.put_galactical_princess_in_sorrow()
      except Exception as e:
          # Nevermind ...
          r = cancel(env,transaction_token, key)
          raise e
      else:
          # We shall rule over the galaxy!
          capture(env,transaction_token, key, min(credits, 2))

Capture

class odoo.addons.iap.models.iap.capture(env, transaction_token, key, credit)

Will capture the amount credit on the given transaction.

Parameters
  • env (odoo.api.Environment) – used to retrieve the iap.endpoint configuration key
  • transaction_token (str) –
  • key (ServiceKey) –
  • credit – 
  @route('/deathstar/superlaser', type='json')
  def superlaser(self, user_account,
                 coordinates, target,
                 factor=1.0):
      """
      :param factor: superlaser power factor,
                     0.0 is none, 1.0 is full power
      """
      credits = int(MAXIMUM_POWER * factor)
      description = "We will demonstrate the power of this station on your home planet of Alderaan."
      #actual IAP stuff
      transaction_token = authorize(request.env, SERVICE_KEY, user_account, credits, description=description)
      try:
          # Beware the power of this laser
          self.put_galactical_princess_in_sorrow()
      except Exception as e:
          # Nevermind ...
          r = cancel(env,transaction_token, key)
          raise e
      else:
          # We shall rule over the galaxy!
          capture(env,transaction_token, key, min(credits, 2))