Billing Service processes subscription transactions (SVOD), purchases (TVOD), and automatic billing through API and frontend integrations

Billing Service

Process subscription transactions (SVOD) and automatic billing through API and frontend integrations.

Overview

The Billing Service provides a unified interface for subscribers to create subscriptions and execute recurring payments.

The following payment providers are supported out of the box:

  • PayPal

  • Google in-app purchases (Google Play)

  • Apple in-app purchases

Other providers can also be integrated using extension points.

For all payment providers, the same data model is applied (including subscription plans, payment plans, claim sets, bundles, subscriptions, and payments) while there are provider-specific settings and restrictions.

Data model

The data model is described in the context of the Content Monetization Solution.

The Billing Service owns the following data:

  • Payment providers

  • Subscriptions

  • Subscription payment transactions

  • Subscription status changes

Billing ServiceSubscriptionuser_idlifecycle_statuspurchase_countryactivation_datecontent_period_end_datepayment_providerpayment_provider_referenceSubscriptionStatusChangeuser_idnew_lifecycle_statusdescriptionSubscriptionTransactionuser_idsubscription_idpayment_providermethodstatusPaymentProviderSubscriptionPlanPaymentPlan
Figure 1. Billing service data

It also stores:

  • Snapshots of the subscription plans, payment plans, claim sets, and prices received from the Monetization Service

GUI

The Billing Service does not have its own GUI.

The Admin Portal provides a GUI to manage payment providers and their configuration.

Monetization Service provides a GUI for subscription plans, payment plans, claim sets, and bundles.

Interfaces

The Billing Service provides a few programmatic interfaces for different applications.

GraphQL API - management

This API is exposed to management applications. It expects a JWT token from the Admin Service.

The API provides a read-only interface to all entities stored by the Billing Service, including the snapshots of the subscription plans and payment plans.

You can build your own service to expose the created subscriptions and processed payments as a micro-frontend in your management system.

The API also has an endpoint for creating and configuring payment providers. This endpoint is used by the Admin Portal.

GraphQL API - end-user

This API exposes endpoints for the frontend applications to initiate the payment process and show subscription and transaction data for an end-user. The endpoints are payment provider specific and allow to start the payment flows for the corresponding payment providers.

For PayPal subscriptions you can use the redirect based or the popup based purchase flow.

PayPal redirect based flow

In the redirect flow, the paypalSubscribe endpoint creates a new subscription in the initial state "Pending Activation". Then it calls the PayPal API and pre-registers a subscription in their system.

Note
The frontend application redirects the end-user to the payment provider’s GUI for payment. From there, the end-user is redirected to the "web redirect" API provided by the Billing Service.

After completing the payment process on the payment provider side, the end-user gets redirected to the "web redirect" page. It re-assures with the payment provider if the transaction was properly completed and then sets the subscription status to "Active".

Then it redirects the subscriber to a page in the frontend application.

PayPal popup based flow

In the popup flow, the paypalSubscribe endpoint prepares the data for a new subscription but does not create it yet.

The frontend application uses this data in the PayPal button SDK to render a PayPal purchase button. The end-user can click on this button and follow the purchase flow.

After completing the payment process on the payment provider side, the popup closes. The frontend application calls the paypalActivateSubscription API endpoint which re-assures with the payment provider if the transaction was properly completed. The Billing Sevice creates now a subscription with the "Active" status.

Webhooks for payment providers

Payment providers can call our webhooks for some events.

One typical event is when a end-user provided all the payment details and the payment provider finishes a transaction.

Another important event - for recurring subscriptions, when a follow-up payment is processed.

The webhook endpoint updates the subscription state in the database.

Payment providers

PayPal

PayPal integration is initially implemented and can be used out-of-the-box.

billing lifecycle paypal
Figure 2. Billing lifecycle with PayPal

Custom payment connector

You can integrate any other payment provider using provided extension points.

Custom code can talk to any payment provider using its APIs or even implement payment logic internally.

As an output, the custom payment connector shall create subscription entities. Once such an entity exists, it is considered by the rest of the system (e.g. Entitlement Service).

Roadmap

In the future we plan to extend the Billing Service with the following:

  • TVOD: allow single item purchases

  • AVOD/FVOD: manage rules/plans to allow content to be advertisement based or free

  • Apple in-app purchases

  • Google in-app purchases

  • Custom payment connector: provide APIs and background jobs to use custom 3rd party payment connectors

  • Free trial, promotion periods, and vouchers

  • Taxation

  • Notifications: sending emails for upcoming recurring payments, payments, errors, etc.

  • Item bundles: select specific entities into bundles - this is an alternative/extension for using claims

  • Device management: register end-user devices and restrict the number of them and/or the number of parallel streams

  • Geo-restrictions: allow purchases only from specific countries

  • Change plans: up-/down-/side-grade to other subscription plans

  • Parallel subscriptions: allow more than one active subscription at a time

  • Non- or fix-recurring subscriptions: a subscription that does not renew at all or only for a pre-defined number of times

  • Create a subscription without a end-user: create the end-user later

  • Migrating/adding existing subscriptions into the system

Pricing

The service fee depends on the number of processed transactions. See Mosaic Pricing for more details.