Skip to main content

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:

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 Monetization and Billing.

The Billing Service owns the following data:

  • Payment providers
  • Subscriptions
  • Subscription payment transactions
  • Subscription status changes

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 Identity Service.

The API provides a query interface to all entities stored by the Billing Service, including the snapshots of the subscription plans and payment plans. In addition, it offers a mutation interface to manage subscriptions and their transactions for custom payment providers.

You can build your own service to expose the created subscriptions and processed payments as a microfrontend 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 an end-user provided all the payment details and the payment provider finished a transaction.

Another important event - for recurring subscriptions - is 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. See PayPal Integration for a detailed overview of this integration.

Billing lifecycle with PayPal (redirect flow)

billing-lifecycle-paypal

Custom payment connector​

Other payment providers can be integrated using extension points. You can develop a custom payment connector that can talk to any payment provider using its APIs or even implement the payment logic internally.

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

A full guide on how to integrate a 3rd party payment connector can be found in the Payment Connectors documentation.

Pricing​

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