Billing Service Technical Specification

Table of Contents

Overview
Data model
Interfaces
- GraphQL API - management
- GraphQL API - end-user

Overview

The Billing Service processes subscription transactions and automatic billing through API and frontend integrations. It uses different payment providers like PayPal for the payment fulfillment and data from the Monetization Service which defines the available subscription plans.

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

Data model

The Billing Service contains data from many different entities. This section describes all those entities and their related data.

The following diagram gives an overview of the data model of the billing system. The green boxes reflect the business-related data that is owned by the Billing Service. Yellow boxes are used for the settings and configurations while the blue boxes are used for published data from the Monetization Service.

Figure 1. Billing Service data model

Published entities

Subscription plans, payment plans, their price list, and claim sets are managed in the Monetization Service. After they have been created and are validated, they are published to the Billing Service. The Billing Service stores all the details from them in its data store. Some of their settings can change when the data is re-published while others are locked from further changes by the Monetization Service.

You can find the full description of those entities in the documentation of the Monetization Service. This section describes the use-cases and scenarios on how they are used in the Billing Service.

Subscription plan

A subscription plan consists of payment plans that define how much an end-user has to pay. Examples would be a “Basic” plan with a description that allows watching all movies from the catalog. And a “Premium” plan with a description telling that it allows watching all movies and also all TV shows in 4k quality.

A subscription plan has a list of all the payment providers that can be used to acquire this subscription plan. For some payment providers, the plans include external identifiers that are required during the corresponding purchase process.

A subscription plan can be marked as not active. All existing subscriptions for this plan will still continue to work but it will not be possible to create a new subscription for such an inactive subscription plan.

Payment plan

A payment plan with its payment provider settings and price list represents the “how and what to pay” to subscribe to its subscription plan. It defines which payment providers can be used and the recurring settings (e.g. weekly or monthly).

The price of a subscription plan depends on the country in which the end-user is located when initially subscribing. A price and a currency are defined for each country in which the subscription can be purchased.

Similar to subscription plans, a payment plan can be marked as not active as well. Existing subscriptions will still continue and will be charged but it is not possible anymore to create a new subscription based on such a payment plan.

Claim sets

A claim set defines a specific selection of claims (permissions and restrictions) that should be applied when evaluating if an end-user is entitled to have access to some content (e.g. a movie). A subscription plan can have one or multiple associated claim sets.

The Billing Service does not actually use those claim sets/claims but only exposes them through the GraphQL API. The evaluation of the claims is done e.g. in an Entitlement Service and potentially used in end-user apps.

Subscription

Subscriptions offer access to some specific content for a defined duration. Once the duration is over, the subscription will be renewed by collecting another payment. This continues until the end-user cancels the subscription or if the payment attempts fail too often.

Subscription properties

Table 1. Subscription properties
Property	Type	Description	Example
user_id	UUID	The ID of the end-user provided as part of the JWT from the Mosaic User Service.	8e980bcb-63db-4c65-8ede-d3d73cf1fa62
payment_provider_reference	String	A reference value for the subscription handle on the payment provider side. This is generated and maintained by the payment provider during the initial subscription process.	I-H91UUCJ8N2W5
activation_date	DateTime ⁽¹⁾	The date at which the subscription was activated for the first time.	2022-02-24T14:17:35+00:00
period_end_date	DateTime ⁽¹⁾	The date at which the current subscription period ends. When this time is reached and the subscription is not cancelled, another payment is made.	2022-03-24T10:00:00+00:00
lifecycle_status	lifecycle status enum	The current lifecycle status of the subscription. See the table below for a full overview of the possible values.	ACTIVE
purchase_country	String ⁽²⁾	The country in which the end-user was located when initially subscribing. The country is evaluated based on the IP address of the user. The country is not used within the billing service for any kind of evaluations/restrictions.	DE

⁽¹⁾ ISO 8601 date and time including time zone e.g. "2022-02-06T05:52:12.71219+00:00"
⁽²⁾ ISO 3166-1 alpha-2 country format e.g. “DE”, “US”, “CN”…

Subscription relations

The subscription entity has relations to multiple other entities in the Billing Service.

Table 2. Subscription relations
Entity	Description
Subscription plan	The subscription plan which the end-user purchased with this subscription.
Payment plan	The payment plan with its options on how the initial and recurring payments are handled.
Subscription transaction	All the payments, failed payment attempts, and refunds that were made for this subscription are available via this relation
Subscription status change	When and why the lifecycle status of the subscriptions changed.
Payment provider	The used payment provider to receive payments for this subscription.

Subscription status change properties

This model includes the information on when and why the lifecycle status of a subscription changed. It has a relation to the subscription to which it belongs.

Table 3. Subscription status change properties
Property	Type	Description	Example
user_id	UUID	The ID of the end-user provided as part of the JWT from the Mosaic User Service.	8e980bcb-63db-4c65-8ede-d3d73cf1fa62
new_lifecycle_status	lifecycle status enum	The new lifecycle status of the subscription. See the table below for a full overview of the possible values.	CANCELLED
description	String	A short description of the reason for the status change.	The subscription was cancelled and will not be renewed.

Subscription lifecycle status

A subscription will go through multiple different stages from the initial desire to start a subscription until the subscription ends. This table shows the different lifecycle statuses, why the subscription can get into such a status, what should/may follow afterward, and if e.g. an Entitlement Service should interpret such a state as a currently valid subscription or not.

Table 4. Subscription lifecycle status
Lifecycle Status	Cause	Next	Treat Subscription as Active?
PENDING_ACTIVATION	The subscription is registered but the payment flow is not finished.	The end-user must first finish the payment flow.	No
PENDING_COMPLETION	The payment flow was finished correctly but the payment provider did not provide the final success or error information yet.	We are waiting for a callback from the payment provider to get the final confirmation.	Yes or No (depending on your business case you may see it as active for some grace period)
ACTIVE	The subscription is currently active. The next payment is planned.	This is the default status for an active subscription. It will normally continue to stay in this state until it gets cancelled.	Yes
ON_HOLD	The subscription has been put on hold due to a payment failure. Or the merchant manually paused the subscription in the corresponding payment provider portal (not supported by all payment providers).	When a subscription payment fails, the payment provider most often retries it a few times. If the payment does not succeed (funds or other payment methods are added) it will go to the ended status.	Yes or No (depending on your business case you may see it as active for some grace period)
CANCELLED	The subscription was cancelled by the subscriber or the merchant in the corresponding payment provider portal.	It will not renew and go to the end status at the next renewal date.	Yes (but will stop after the end date is reached)
ENDED	The initial payment process failed, the subscription was cancelled and ended, or the threshold for payment failures was reached.	The subscription has ended - the end-user must create a new subscription.	No

This state diagram shows the above table with a visual representation of how the subscription lifecycle states can go from one state into another:

Figure 2. Lifecycle state diagram

Subscription transaction

Every transaction that was made by a payment provider as part of a subscription is stored as a subscription transaction.

Subscription transaction properties

Table 5. Subscription transaction properties
Property	Type	Description	Example
user_id	UUID	The ID of the end-user provided as part of the JWT from the Mosaic User Service.	8e980bcb-63db-4c65-8ede-d3d73cf1fa62
payment_provider_reference	String	A reference value for the transaction handle on the payment provider side. This is generated by the payment provider for each transaction.	2TN74767D7324291Y
transaction_type	PAYMENT, REFUND, or PAYMENT_FAILED	The type of the transaction which is most of the time the initial or recurring PAYMENT. In case a refund is issued, this is tracked as a REFUND transaction. When a payment fails then this is tracked as a PAYMENT_FAILED transaction.	PAYMENT
total_price	Decimal with five digits after the decimal mark	The gross price if this was a payment (e.g. "9.99000"). The amount that was refunded to the end-user as a negative number (e.g. "-2.99000"). Zero if the payment failed ("0.00000").	9.99000
currency	String ⁽¹⁾	The currency of the payment, refund, or failed payment.	EUR
method	String	An optional payment provider specific identifier on how the payment was made. For PayPal this can be e.g. INSTANT_TRANSFER or DELAYED_TRANSFER.	INSTANT_TRANSFER
description	String	An optional description of this payment which was provided by the payment provider.	For PayPal this can be e.g. [sic.] “Payment completed for EUR 9.99 EUR“.
transaction_date	DateTime ⁽²⁾	The date when the transaction was finished.	2022-02-24T14:17:35+00:00
period_end_date	DateTime ⁽²⁾	If the transaction was a payment then this date reflects the new subscription period end date. Otherwise this field is empty.	2022-03-24T10:00:00+00:00

⁽¹⁾ ISO 4217 currency e.g. “EUR”, “CNY“ or “USD”
⁽²⁾ ISO 8601 date and time including time zone e.g. "2022-02-06T05:52:12.71219+00:00"

Payment provider

The payment providers that should be available must be activated and configured.

Payment provider properties

Table 6. Payment provider properties
Property	Type	Description	Example
key	String	The unique identifier of the payment provider.	PAYPAL
title	String	The text how the payment provider should be shown in the management system and potentially also on the end-user apps.	PayPal

Payment provider relations

The payment provider has relations to multiple other entities in the Billing Service.

Table 7. Payment provider relations
Entity	Description
Subscription	The subscription which an end-user purchased.
Subscription transaction	A transaction is always made through a specific payment provider. This relation shows which payment provider was used for which transaction.
Subscription plan provider config	If the payment provider is available for a subscription plan, it will have a reference to it through the subscription plan provider config. A payment provider specific product ID/external reference can be stored there as well.
Payment plan provider config	If the payment provider is available for a payment plan, it will have a reference to it through the payment plan provider config. A payment provider specific plan ID/external reference can be stored there as well.
Payment provider specific settings	If a payment provider requires specific settings then those settings are referenced as well.

Settings

General settings

The Billing Service has general settings that define the behavior of the Billing Service for your Mosaic environment.

Table 8. General settigns
Property	Type	Description	Example
success_redirect	String	If a redirect based purchase process is used, this setting defines the URL to which the end-user should be redirected in a successful payment process.	https://example.com/success
error_redirect	String	This is used in the same way as the success redirect but for error scenarios. This is an optional setting and the success redirect setting will be used if this is not configured or if the payment provider does not provide error information.	https://example.com/error
cancel_redirect	String	This is used in the same way as the success redirect but for scenarios where the end-user actively cancels the purchase process. This is an optional setting and the success redirect setting will be used if this is not configured or if the payment provider does not provide cancellation information.	https://example.com/cancel

Payment provider specific settings

Payment providers require specific settings for authorizing API or webhook calls and similar. Please check the provider-specific integration documentation about the available settings and how to configure them correctly.

Interfaces

The Billing Service provides programmatic interfaces for different scenarios.

GraphQL API - management

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

You can find the GraphiQL IDE with the GraphQL schema under this URL: https://billing-management.service.eu.axinom.net/graphiql

Table 9. Permissions
Permission	Description
PLAN_VIEW	Can query all subscription plans, payment plans, payment plan prices, provider configurations, and claim sets.
SUBSCRIPTION_VIEW	Can query all subscriptions, transactions, and lifecycle state changes.
SETTINGS_VIEW	Can query the general settings and payment providers with their settings (minus secret values).
SETTINGS_MANAGE	Can mutate the general settings and payment providers with their settings.
ADMIN	Combines all the above permissions.

GraphQL queries

The API provides a read-only interface to the full entity graph stored by the Billing Service. This includes all the entities that are described in the data model section with all the relations between the entities to query, filter, and sort. The management API exposes all the properties of the entities besides secret values.

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 a mutation for creating and configuring payment providers and their settings. This is used by the Admin Portal.

GraphQL mutations

The general Billing Service settings and any payment provider specific settings can be managed via GraphQL mutations.

The input parameters follow the entities that are described in the data model "Settings" section and in the corresponding payment provider specific documentation pages.

GraphQL subscriptions

Application integrations can use the Billing Service management GraphQL subscription to be notified on any subscription change. The subscriptionTypeMutated will send a message whenever some field on a subscription is changed and the event name for it. The available event names are SubscriptionCreated, SubscriptionCreated, and SubscriptionCreated. The client application can ask for specific subscription fields to be sent along.

Note	GraphQL subscriptions are a push notification implementation. When something on the server changes, connected clients can be informed of such a change. This must not be confused with Billing Service subscriptions where end-users use recurring payments to subscribe to some offer.

GraphQL subscriptions should only be used in application. There is no guarantee that all server messages will arrive on all the subscribed clients. It should not be used for any server-to-server integrations. Use message-bus based subscriptions instead.

GraphQL API - end-user

This API exposes all the required queries and mutations to implement the purchase flow for end-user applications. The end-user API does not provide the full graph and properties of all the entities but only those, that are relevant for end-user applications. You can find the GraphiQL IDE with the GraphQL schema under this URL: https://billing.service.eu.axinom.net/graphiql

This API requires a JWT that was issued by the Mosaic User Service. End-users have access to their own data (their current and past subscriptions and transactions). They can also query the available subscription plans, payment plans, and the payment provider names.

GraphQL queries

GraphQL offers the notion of queries. Those are entry points into the data graph that can be used to get data for the desired entities with exactly the properties and sub-entities which the end-user application requires.

subscription and subscriptions queries

Those two queries expose all the subscriptions that an end-user has. This includes a currently active one as well as subscriptions in other lifecycle states. With the usage of filters, it is possible to check if there is a currently active subscription or show all the past subscriptions.

subscription - get a single subscription by the ID of the subscription
subscriptions - get multiple subscriptions by applying filters, sorting, and paging

The subscription exposes relations to the associated subscription plan, payment plan, payment provider, transactions, and subscription lifecycle status changes that can be traversed.

subscriptionTransaction and subscriptionTransactions queries

The subscription transaction query can be used to get a list of all transactions for all subscriptions of an end-user. This can be used for example to display all the payments, refunds, and/or failed payments. If the data should be shown for a specific subscription only, it is suggested to use the subscription(s) queries and use the transactions relation to query them.

subscriptionTransaction - get a single transaction (payment, refund, or failed payment) by the transaction ID
subscriptionTransactions - get multiple transactions by applying filters, sorting, and paging

A subscription transaction has relations to the used payment provider and to its subscription.

subscriptionPlan and subscriptionPlans queries

Those queries are used to get the published subscription plans. Most of the time you should apply the “is_active” filter on the subscription plan and payment plan level to make sure they can be used. When the plans are shown to the end-user to decide which one to buy, you should include the payment plans of the subscription plus the payment plan pricing. The frontend application can apply filters in the query. E.g. on the pricing to receive the price information only for the current country of the user (a GEO IP service can be used to find the country).

subscriptionPlan - get a single subscription plan by the ID of the subscription plan
subscriptionPlans - get multiple subscription plans by applying filters, sorting, and paging.

paymentPlan and paymentPlans queries

Most likely those queries should rarely be used. The subscriptionPlan and subscriptionPlans are more beneficial in most scenarios.

paymentPlan - get a single payment plan by the ID of the payment plan
paymentPlans - get multiple payment plans by applying filters, sorting, and paging.

paymentProvider and paymentProviders queries

The paymentProviders query can be used to get a list of all supported payment providers. But most of the time you can traverse to the payment providers via relations from other entities.

paymentProvider - get a single payment plan by the ID of the payment plan
paymentProviders - get multiple payment plans by applying filters, sorting, and paging.

GraphQL mutations

GraphQL Mutations offer a way to change the state of the system. In the Billing Service end-user API, there are payment provider-specific mutations to start the subscription workflow and to activate a subscription. Please check the provider-specific integration documentations for descriptions on how to use them.

GraphQL subscriptions

The Billing Service offers a GraphQL subscription which is a websocket based server connection where the server can send updates to the client. This is a technical GraphQL term and should not be confused with the subscription an end-user can purchase.

subscriptionLifecycleStatusMutated This event is triggered when the lifecycle status of a subscription changes. This is especially useful when a subscription is created where the payment provider does not send in immediate feedback if the subscription was a success or not.

If the status of a subscription from the end-user changes, it sends the ID of the subscription as “id” along with the user ID, the old lifecycle status, and the new one.