OTT Platform Integration with CRM.COM: Apple & Google Play Stores Guide
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(s) on app stores like Apple Store and Google Play store. Instead of managing subscriptions, their billing and payments directly through their own billing system, the business utilises an 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. Subscriptions and payments are forwarded to the OTT platform and then to CRM.COM, the business’s back-end system.
The Set up
Prerequisites
Before moving on implementing your integration to an app store, make sure you have made the required configurations in CRM.COM.
Set up your service offerings in CRM.COM’s Product Catalogue, i.e. termed services with their prices. Price terms include the price (optionally in multiple currencies), billing cycle, contract and trial periods. Services should include the same piece of information as this will also be configured in stores.
Set up your Subscription and Billing model CRM.COM in order to maintain an alignment between CRM.COM and the rules that a store will apply such as:
Anniversary billing with immediate alignment and billing on the subscription’s billing day
Allow cancellations and downgrades at the beginning of the next billing cycle
Zero credit limit in CRM.COM accounts (to enforce Payments collection)
Create Commerce pool(s) that includes the services that will be published in stores. This information is utilised when payments are forwarded to CRM.COM.
Stores Set-up
Decide the stores through which customers can make In-app purchases and order your services and configure your in-app purchases:
For Google Play store visit Google Play Console, create the in-app product and specify its pricing details. When ready you can activate it.
For Apple store visit Apple App Store Connect, create the in-app purchase product, specify its pricing details and submit to review.
Regardless of the store, make sure that the product and its price is aligned to how the product is configured in CRM.COM!
Register developer accounts in stores.
For Google Play, create a Google Play Developer account and set up a Google Payments Merchant Account
For Apple App Store Connect, sign up to Apple Developer Program and then set up your App Store Connect account to manage your apps and in-app purchases,
Publishing services to stores involve an agreement made between the business and Apple/Google that includes:
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.
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.
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 obtained, such as their billing cycle.
Receive webhook notifications from stores that contain information about the subscription event, such as the subscription ID and purchase token.
For a successful integration between a store and CRM.COM we highly recommend setting up at least the following webhooks:
New Subscription
Subscription Renewal
Cancel Subscription
Optionally, set up webhooks for:
Pause Subscription
Resuming a Subscription (after a paused)
Subscription Expired
OTT-side development
Receive webhook notifications from stores that contain information about the subscription event, such as the subscription ID and purchase token.
Processing the subscription or payment event information and then forward this information to CRM.COM using its Web APIs. Depending on the event received, various flows should be implemented, i.e. different Web API calls.
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-side development 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, their Account and their CRM.COM Wallet. In the case of returning subscribers (contact that used to be a subscriber 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 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 external reference code 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 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.
{
"wallet_id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"payment_method": {
"type": "ELECTRONIC_TRANSFER"
},
"code": "1234567891234567",
"topup_date": 1618298816,
"amount": 9.99,
"commerce_pool_id": "f283a863-18e1-7cae-48c4-7433bf28cf97"
}
- 1 Overview
- 2 The Use Case
- 3 The Set up
- 3.1 Prerequisites
- 3.2 Stores Set-up
- 3.3 OTT-side development
- 3.3.1 Steps