Mpulse supports Direct Carrier Billing for the following mobile network operators in Luxembourg:

• POST Luxembourg
• Tango / Proximus
• Orange Luxembourg

Content and service providers can apply for an account with Mpulse to gain access to these mobile networks and bill users for their content or services.

The Direct Carrier Billing interface allows creating single transactions and subscriptions. More information about how this works can be found in the following sections.

The OpenAPI v3 specifications of the Direct Carrier Billing APIs can be used to generate API clients automatically by using one of the tools below (among many others):

• Swagger Editor: https://editor-next.swagger.io/
• OpenAPI generator: https://github.com/OpenAPITools/openapi-generator

Creating an account

Before starting to use the Direct Carrier Billing APIs, you need to open an account and request credentials. Please contact [email protected] if you're interested in distributing your services on the Luxembourg market.

Once the account is created, you will receive API credentials that you can use to retrieve an access token using an OAuth2 password grant flow as described in the Authentication section.

Registering services

Before distributing your services to the consumers, the details of these services must be shared with your Mpulse account manager and approved for sale.

For each product or service you would like to distribute, the following information needs to be provided:

• Name of the service: something short and easy to remember
• Description: a more detailed description of what the service is and where the consumer can find additional information about the service.
• Support email: the email address of the consumer support of the service provider
• Service logo URL: a URL pointing to a service logo that will be displayed on the transaction or subscription confirmation page
• Recurrence: how often the service is invoiced to the consumer. The following options are available:
  • One-time: used for one-off transactions, e.g. donations, when there is no subscription
  • Daily: the subscription is renewed daily
  • Weekly: the subscription is renewed weekly
  • Bi-weekly: the subscription is renewed every 2 weeks
  • Monthly: the subscription is renewed monthly
  • Quarterly: the subscription is renewed every 3 months
  • Yearly: the subscription is renewed yearly
• Price: the price of the subscription (if applicable)
• Redirect URL: the service provider's URL to which the user is redirected in the browser when the payment or subscription process is completed
• Callback base URL (optional): the service provider can optionally subscribe to callbacks following the Callback API specifications to receive real-time notifications about subscription status changes or transaction executions.

Only once the information provided is approved, the service is added to your account, and transactions and subscriptions can be created. You can see which services are currently available for use on your account, you can use the Services API.

Single transactions

Service providers can use the Transactions API to initiate one-time payment transactions. This requires an existing service with one-time recurrence to be defined (see above)

The user is redirected to the Direct Carrier Billing payment page, where he validates (or rejects) the payment and is then redirected back to the service provider's portal.

Subscriptions

Service providers can use the Subscriptions API to initiate recurring subscriptions. This requires an existing service to be defined with the corresponding recurrence and amount. If you want to distribute the same product or service with different amounts and/or recurrences, a separate service needs to be created for each of those combinations.

The user is redirected to the Direct Carrier Billing payment page, where he validates (or rejects) the subscription and is then redirected back to the service provider's portal.

The service provider can define a free trial period for using the service by specifying a subscription start date during subscription creation.

Once the subscription for a user is created, Mpulse will automatically bill the user at the renewal date and update the subscription status accordingly. If the user's operator returns a temporary billing error (e.g. missing prepaid credits), the billing operation will be retried the following day.

Aliases

The Direct Carrier Billing API does not expose the user's MSISDN but uses an alias instead. The alias remains stable per user and per service, so the service provider will know whether the same user wants to subscribe to the same service multiple times.

If the user is using his mobile network internet connection at the time of validating a payment or a subscription, he is automatically and transparently recognized by the operator and no additional identification steps need to be taken by the service provider or the user.

If the user however uses a Wi-Fi connection, he is automatically redirected to a SMS Link flow. This requires him to enter his MSISDN into a web form, after which he will receive a one-time link via SMS. Clicking on that link will validate the user's identity and forward him to the payment or subscription confirmation page.

This entire process is automated from the service provider's perspective.

Event callbacks (web hooks)

The service provider can optionally subscribe to callbacks whenever a subscription is created or cancelled, or if a transaction is executed. This can be used for real-time tracking of subscription statuses, without having to query them one by one on a regular basis.

Please consult the Callbacks API documentation for further details.

Sending SMS messages

Service providers might want to send SMS messages with specific credentials or subscription reminders or any other useful information to users. Since the MSISDN of the subscribers are not directly exposed through the Subscriptions or Transactions APIs, service providers can use the Messages API to send SMS messages to Direct Carrier Billing users.

Identifying returning users

Once a user has successfully created his subscription, the service provider will typically use a cookie in his browser to identify him as a returning user to the content or service portal. Many also provide credentials (username and/or password) in case the session expires, the user has a new phone, or the cookie gets otherwise lost.

If all this goes wrong, service providers can use the User Identification API and corresponding flow to identify an unknown user. The flow will recognize the user automatically if he's using his mobile network internet connection or ask him to enter his MSISDN after which he will receive a SMS with a link to click.