Billing Service Technical Specification
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.
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
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 (1) | The date at which the subscription was activated for the first time. | 2022-02-24T14:17:35+00:00 |
| period_end_date | DateTime (1) | 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 (2) | 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 |
(1) ISO 8601 date and time including time zone e.g. "2022-02-06T05:52:12.71219+00:00"
(2) 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.
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.
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.
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:
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
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 (1) | 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 (2) | The date when the transaction was finished. | 2022-02-24T14:17:35+00:00 |
| period_end_date | DateTime (2) | 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 |
(1) ISO 4217 currency e.g. “EUR”, “CNY“ or “USD”
(2) 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
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.
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.
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 Identity Service.
You can find the GraphiQL IDE with the GraphQL schema under this URL: https://billing-management.service.eu.axinom.net/graphiql
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 microfrontend 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.
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 subscriptionsubscriptions- 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 IDsubscriptionTransactions- 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 plansubscriptionPlans- 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 planpaymentPlans- 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 planpaymentProviders- 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.