Overview

This guide is designed to provide developers with a comprehensive understanding of how CRM.COM can be integrated with OTT platforms, which in turn integrate with leading app stores such as Apple Store and Google Play Store.

The Use Case

The use case covers an OTT business that publishes its digital service on app stores like Apply Store and Google Play store. Instead of handling billing and payments directly through their own platform, the business utilises the app store’s billing system. The app store is responsible for billing and collecting payments using the user’s listed payment methods like bank cards or mobile wallets. Payment information is forwarded to the OTT platform and hen back to CRM.COM, the business’s back-end system.

The flow

Prerequisites

1. The OTT business sets up termed services and their prices in its CRM.COM Product Catalogue. Price terms include the price (optionally in multiple currencies), billing cycle, contract and trial periods.

2. OTT business sets up Subscription and Billing business rules in CRM.COM in order to maintain alignment between CRM.COM subscriptions billing and billing information at the store’s side such as:

   1. Anniversary billing with immediate alignment and billing on the subscription’s billing day

   2. Allow cancellations at the beginning of the next billing cycle

   3. Zero credit limit in CRM.COM accounts

   4. Commerce pool that includes the services that will be published in stores. This information is utilised when payments are forwarded to CRM.COM

3. The business publishes its services to Apple/Google Play Store with the same pricing information as in CRM.COM, making them available for purchases by users. Publishing services to stores involve an agreement made between the business and Apple/Google that includes:

   1. The preferred currency(ies) in which payments will be forwarded by the store’s billing system. Users make purchases in their local currency so stores are responsible for billing and collecting money in users' currency by applying the required exchange rates when needed.

   2. Payments processing time: This part of the agreement outlines the terms of payment forwarding, including the frequency and timing of payments. It’s strongly suggested that business accepts the payments as soon as possible so as to avoid delays and minimise misalignment between the store’s subscription billing cycle and the CRM.COM subscription’s billing cycles.

4. Required OTT-side development

   1. Configure webhooks in app store platform (e.g. Google Play Developer Console) to receive notifications for subscription events such as new subscriptions, renewals and cancellations. Subscriptions details can also be obtain such as their billing cycle.

   2. Receive webhook notifications from stores that contain information about the subscription event, such as the subscription ID and purchase token.

   3. Processing the subscription or payment event’s information and then forward this information to CRM.COM using its Web APIs.

Steps

The following diagram provides an overall description of the flow, starting from the time the user makes a purchase, to registering the contact in CRM.COM side, triggering the payment-driven model or cancelling a subscription. In all cases, the flow depends on the events that the OTT-development side receives from the app store’s platform.

• OTT Development is responsible for forwarding various events to CRM.COM that include:

  • New subscribers: Identify whether the user is a contact already registered in CRM.COM or not. In the latter case, integrators must use CRM.COM Web API in order to create both the contact and their CRM.COM Wallet. In the case of returning subscribers (contact that used to be subscribers but they had cancelled their subscriptions), this step is not required. It’s suggested to utilise the app store’s references about the purchase in CRM.COM data such as the user’s code or the subscription’s code.

  • Cancellations: Users cancel their subscription in the app store so once such as event is captured, CRM.COM Web API will be triggered so as to cancel the subscription at CRM.COM side as well. Usually cancellations are configured so as to be scheduled at the end of the current billing cycle. The scheduling of the cancellation is handled by CRM.COM based on how the cancellation business rules are configured.

  • Top-up Wallet: Whenever a payment is forwarded to the OTT-side, integrators must record this payment as a CRM.COM Wallet Top-up in CRM.COM, a request that must include the commerce pool of services published to stores. Topping up the CRM.COM Wallet with a commerce pool that includes termed services triggers the payment-driven model for managing subscriptions and their billing.

    • Highly recommended to store Apple/Google’s payment reference on the Top-up as well (use same identifiers either as topup identifier or its code) to keep track of the payments in both systems.

    • When submitting the first top-up, CRM.COM is responsible not just for topping up the wallet’s business commerce pocket, but it also creates the subscription for the contact that includes the purchased service. In addition, the top-up’s amount is used to pay off the invoice which is issued at the same time.

    • When submitting subsequent top-ups, CRM.COM again bills the services and uses the business commerce pocket’s money to pay off the invoice.

Here’s an example of POST /topups where the CRM.COM Wallet is topped-up using a Commerce Pool.