🚧

Beta

Please note that it is a Beta phase.

Overview

Integration of mobile apps, connected TVs, telco carriers, and other channels of distribution is one of the key challenges faced by OTT services. Cleeng harmonizes these different platforms with a unique API framework for synchronizing externally-managed purchases in our multi-channel subscriber business management.

OTT teams can now focus on building unified strategies across the whole business, adding channels when attractive opportunities emerge because Cleeng provides:

• a unified API for both Cleeng-managed and externally-managed purchases, so integration with the Cleeng platform is frictionless
• the ability for the Cleeng platform to reflect the state of subscriptions, passes, and payments where applicable, from a source other than Cleeng - making it a source of truth on par with Cleeng.

Note:

If a subscription originates from an external source, Cleeng is not a Merchant of Record.

Integration Steps

Multi-channel billing requires detailed configuration to best reflect broadcasters’ needs and business models, but once configured, the feature gives great benefits:

• it allows you to have unified and consolidated entitlements for various external sources in the Cleeng platform
• it provides enhanced reporting capabilities.

Prerequisites

1. Offers

Make sure you have offers created in the Cleeng dashboard.

2. Payment method configuration

External sources will be visible as separate (external) payment methods in the Cleeng platform. You need to configure payment methods for externally-managed purchases. In order to do that, you need to contact the Cleeng Broadcaster Success Specialists team, and provide the following information:

• Payment gateway (e.g. Samsung)
• Payment method (e.g. Samsung TV, Samsung Mobile)
• Whether the payment method allows payment creation for subscriptions or passes created with this payment method.
  This will depend on your business model. For example, in the case of carrier billing - some broadcasters partner with external vendors, like mobile operators, cable TV operators, credit card operators etc. and sell the OTT Package bundled with the external vendor service. Billing in those cases is handled by a billing system on the partner side and customers have access to a broadcaster’s video content as long as they pay their bills to a partner. In such cases the payment method does not allow payment creation.
  👉 Note: If you select “No” here, Cleeng API will not allow you to create payments.
• Accuracy of a payment amount provided to Cleeng - depending on whether you have financial information, and whether you want to provide it (for example to have more accurate reporting) you can select from the options below:
  • Exact external store-based - for cases when Cleeng obtains the exact payment amount from the external source (this is the exact amount paid by a customer). Note that the selected payment method has to allow payment creation for this to work. This option ensures best reporting results.
  • Approximate offer-based - for cases when Cleeng does not get the exact payment amount. The amount is estimated on the basis of an offer.
    👉 Note that the selected payment method has to allow payment creation for this to work.
  • No accuracy - select this option if you do not want to or cannot provide payment amounts to Cleeng.
    👉 Note that this is used when the selected payment method does not allow payment creation.
• Whether passes should be terminated automatically.
  If you enable auto-termination during configuration of a payment method, Cleeng platform will terminate a pass when its expiration date is reached. If auto-termination is not enabled, Cleeng platform will not terminate a pass when its expiration date is reached, and the broadcaster will need to send the termination request to revoke access.
• Payment gateway specific parameters (optional) - any parameters specific for a payment gateway or any additional data required by a broadcaster can be provided here. Cleeng does not need this data, but a broadcaster or a connector might need it.

Synchronize Multi-Channel Billing

The lifecycle of externally-managed subscriptions or passes is outside of Cleeng’s control. It’s controlled by external parties, such as telcos and direct carriers, external payment gateways, mobile and TV apps.

An external system may be directly integrated with Cleeng API, but a more common case is when a connector acts as a proxy between an external system and Cleeng API and synchronizes externally-managed purchases.

Synchronizing involves:

• Synchronizing Accounts
• Synchronizing Payments
• Synchronizing Externally-Managed Subscriptions and/or
• Synchronizing Externally-Managed Passes

Synchronize Accounts

Check if User Exists

Use GET /3.1/customers to check if a customer account already exists.

If yes, you can jump to the section about synchronizing payments.

If not, proceed to Create User Account.

Create User Account

If the user doesn’t exist, create a new user account with POST /3.1/customers.

Synchronize Payments

Create Payment

Multi-channel billing may or may not involve payments - depending on your configuration.

Payment creation is not mandatory, however, payment information provides a lot of insights into reporting - we recommend that you always report payments when possible. That’s why payments should be tied to specific events in a subscription/pass lifecycle.

Payments for externally-managed purchases are created without orders, but instead they provide net and tax amounts (zero-value payments are allowed). The above will be possible only if payment creation is enabled for this payment method (see the Prerequisites section on payment configuration).

After creating a payment:

• webhooks will be emitted as in the usual payment flow
• no emails will be sent.

If an external source reports payments, and you decide to create a payment for a given purchase, it is important to provide paymentId of this payment while creating an externally-managed subscription or externally-managed pass to connect a payment to a given subscription/pass.

Similarly, the paymentId that you provide in the renew subscription endpoint is the paymentId of the previously created payment. That allows better financial reporting, for example revenue and customer lifetime value.

Update Payment

If you have decided to create payment for your externally-managed purchase, you might need to update it. Updating payments is useful for refunded payment cases.

📘

Important Points

• Only captured payments can be refunded.
• When payment is updated due to refund, a subscription will not be terminated automatically. (Update subscription needs to be sent to change status to terminated).

Synchronize Externally-Managed Subscriptions

For details of creating and managing externally-managed subscriptions, see Externally-Managed Subscriptions.

Synchronize Externally-Managed Passes

For details of creating and managing externally-managed passes, see Externally-Managed Passes.