Skip to main content
Also known as the Associate Account Process, this Process associates an external billing account to a Storefront Gateway User. Storefront Gateway retrieves account information from the billing system, and then uses that data to provision a Storefront Gateway Account entity. The full operation is technically executed by two distinct but directly related Storefront Gateway Processes. See below for more details.

​
Multiple Process Orchestration

Most user journeys are facilitated by a single Process. Conversely, there are some cases where Storefront Gateway orchestrates and links two or more distinct Processes to complete a given journey. The Process Start API invokes the Associate Billing Account Process to start the user journey. That Process consumes a mobile number, queries the external system with that number, and (if successful) discovers external account data. Storefront Gateway then issues an action token and delivers it as a short, custom One-time Passcode (OTP) to that mobile number over SMS. The Process ends at this point, and the client application prompts the user to supply that OTP. The user then retrieves the OTP from their phone, and supplies it to the client application. The client application then supplies that OTP to the Session Token API, and that API initializes the Complete Account Association Process to complete the operation. That secondary Process uses the external account data to provision the Storefront Gateway Account entity in our data store.

​
AuthN ID Creation

If the user supplies a mobile number is not already one of their registered, activated authentication identifiers (authN IDs), then this Process automatically adds and activates the mobile number to the User ID (i.e., to the user’s corresponding Storefront Gateway User entity) at the very end of the user journey. This is because they are, in effect, verifying their ownership of the mobile through OTP verification. In some cases, the user might supply a mobile that is already registered as one of their activated authN IDs. They will still need to receive the OTP and supply it back to Storefront Gateway to complete the account association.

​
External Account Discovery

This Process consumes metadata provided by the user to search for and discover the external account. Currently, the only acceptable data type is a mobile number. Note: Support for this Process to accept email addresses and external account numbers is roadmapped for a future release.

​
Storefront Gateway Account Provisioning

If the external system returns an account record to Storefront Gateway, Storefront Gateway then sends an OTP to the user to verify the account ownership. Once the OTP is verified, the Process provisions an equivalent Storefront Gateway Account entity. The Account’s attributes are populated with details from the external B/OSS record data. Account and subscription data will differ architecturally from external service to service. How the account data maps to the Storefront Gateway Account (and or Storefront Gateway Subscriptions and Features, if any) depends on an integration between Storefront Gateway and the external B/OSS. Storefront Gateway’s flexible data model maps external account details to a standard Storefront Gateway Account entity according to a pre-defined template based on the service-specific business requirements. These templates are defined as a part of the onboarding and integration between your business and Storefront Gateway. Note: If your organization is an OTT service provider, and is integrated with MarketONE Subscribe/Partner, then this Process can pull data from the account/subscriptions to create the Storefront Gateway equivalent of those Accounts/Subscriptions/Features.

​
Account Association

Once Storefront Gateway provisions a Storefront Gateway Account, the Process then associates the Account entity to the Storefront Gateway User entity (or user ID / user profile, from the front-end user’s perspective). The Process also associates the Account to a Storefront Gateway Group entity.
  • If the user is a Primary User of a Group, then Storefront Gateway associates the Account (and any Subscriptions/Features under the Account) to that Group.
  • If the user does not yet have a Group, then Storefront Gateway creates a Group and associates the Account (and Subscriptions/Features) to the Group.
About Storefront Gateway Accounts and Associations In the Storefront Gateway Data Model, all primary Storefront Gateway Entities exist independent of each other, and are then associated to one another. Associations are defined by secondary association entities, and each association has its own attributes and permission flags that define the relationship between two primary Storefront Gateway entities. For example, a given user and the device they use to sign into an application are represented in by a Storefront Gateway User entity and an associated Storefront Gateway Runtime entity, respectively, in the Storefront Gateway data store. These entities exist independent of each other first, and are connected by associations thereafter. The exception to this rule is that a Storefront Gateway Account can (and often does) contain an array Storefront Gateway Subscription entities, and each individual Storefront Gateway Subscription entity can contain its own array of Storefront Gateway Feature entities. In other words:
  • A Storefront Gateway Feature cannot exist independent of a parent Storefront Gateway Subscription
  • A Storefront Gateway Subscription cannot exist independent of a parent Storefront Gateway Account
Therefore, when a Storefront Gateway Account is provisioned, it may also involve the provisioning of Subscriptions and Features that belong to the Account. Mapping of data across the Account / Subscription / Feature (A/S/F) hierarchy depends on integration between your organization’s back end billing and records system and Storefront Gateway. See the next two sections for more details on what a Storefront Gateway A/S/F entity hierarchy looks like, and how Storefront Gateway Groups are leveraged for account and service sharing.

​
Mapping External Service Data

When a customer’s account records or service subscriptions are provisioned in Storefront Gateway, that data is mapped across an entity hierarchy that consists of a parent Storefront Gateway Account entity, the Storefront Gateway Subscription(s) owned by the Account, and any Storefront Gateway Features that belong to each individual Storefront Gateway Subscription (if any). The Storefront Gateway Account entity represents the B/OSS billing account. Subscription entities represent subscriptions or services under the account, and Feature entities represent specific functionalities under a service, if necessary. The Account object will vary in terms of how many Subscriptions and Features are present (if at all) based on the integration between the external billing system and Storefront Gateway, the nature of your business and the services you offer, and the services to which a given customer subscribes. MarketONE’s technical resources will work your team to help define the A/S/F mapping during your organization’s onboarding phase with Storefront Gateway.

​
Service Sharing with Group Association

Storefront Gateway enables service sharing by way of user groups. When the Process associates a billing account (and any services/subscriptions under that account) to a Storefront Gateway User ID, the Process also associates the Account entity to a Storefront Gateway user Group entity to which the user is a Primary user. The Primary user of a group can then add other Storefront Gateway users to the same group in order to grant those users conditional access to either the whole Account, or to only specific services under the account. Note: Only a Group’s Primary User can add more accounts or services the existing Group. If the user does not have a Group during an account association, then the Process automatically creates a new Group entity on the back end and assigns the user the “Primary User” role for the that Group to the end user. Once a user adds their Account to a Group (again, this will likely happen automatically), Storefront Gateway also automatically associates the Storefront Gateway Group entity to the entire Account/Subscription/Feature hierarchy. A Group’s Primary User can add other Users to the group, grant each additional User “Admin” or “Regular” User permissions for the Group, and assign specific service entitlements on a granular per-User, per-service basis. This means one Regular user’s User entity will be associated to the Group and only the specific Subscription(s) or Feature(s) that the Primary wishes to share with that individual. A separate User in the Group may have their User entity associated to the Group and other Subscriptions or Features. Account or service sharing is facilitated by the Share Account or Service Process. In most cases, multiple accounts and services are all added to a single Group that is owned and maintained by the Group Primary, who usually owns/pays for the Account with the service provider. A common use case would be the head of a household pays for a variety of services under a single account bill. That user associates their billing account to their User ID, and to a User Group (and again, this user is the Group’s Primary User by default). The Primary User then adds other household members to the group, and gives them conditional Group User types, including:
  • Admin User access to their spouse. A Group Admin User can access all A/S/F entities in the Group, and add/remove Regular Users from the Group.
  • Regular User access to their teenagers. A Group Regular User can only access specific services or features, determined by a Primary or Admin User. They cannot manage any entities or set permissions for other Group Users.
Note: There can only be a maximum of 10 users in a group (or 10 User entities that can be associated to a Group entity). This limit is controlled by an internal Group Size Limit setting. When a Group Primary or Admin User attempts to add another user to a Group, Storefront Gateway checks this setting to see if the Group is at its limit before proceeding. Your organization can self-manage the Group limit as needed from the Admin console. User Groups as a Concept A user can associate multiple accounts and services to a single Storefront Gateway Group, or they can keep multiple accounts separate in separate Storefront Gateway Groups, if desired. How this plays out on the user experience level is up to you and how you build out your application user interface. Groups are an essential component of account association and service sharing, but they do not necessarily need to be an explicit concept built into your UI. You can silently enforce a single group underneath the UI, and simply provide the user with a page for managing all their associated accounts and services. This maintains simple and straightforward user experience. By default, the maximum number of Storefront Gateway Users that can be associated to a given Storefront Gateway Account, Subscription, or Feature is 5 Users, including the Primary User. This means that a Primary can add as many users as they desire to their user Group, but each individual service can only be shared with up to four other Storefront Gateway Users.

​
Process Flow

This flow describes the Process at a high level. Preconditions
  • The user is currently authenticated in Storefront Gateway
  • The user has at least one billing account or subscription in the external BSS/OSS.
Basic Flow
  1. The user selects to associate (or “link”) an external account.
  2. The UI prompts the user to provide a unique account identifier (i.e., mobile number).
  3. The user provides their mobile number, and the client passes it to Storefront Gateway.
    • Before it the Process continues, Storefront Gateway first performs a backend check on the user-supplied mobile number.
      • If the mobile number is registered to another Storefront Gateway User entity, then the Process returns an error.
      • If the mobile number is registered to the current Storefront Gateway User, then the Process continues.
      • If the mobile number is not yet registered in Storefront Gateway at all, then the Process continues.
  4. Storefront Gateway calls the external system, and requests account data for the user-supplied number.
  5. The BSS responds, and Storefront Gateway inspects the response.
    • If the external account maps to an existing Storefront Gateway Account of another Storefront Gateway User, then the Process returns an error.
    • If the external account maps to an existing Storefront Gateway Account of the current Storefront Gateway User, then the Process returns an error.
    • If the external account does not map to an existing Storefront Gateway Account, then the Process continues.
  6. Storefront Gateway issues and sends One-time Passcode (OTP) to the user, and the client prompts them for that OTP.
  7. The user retrieves that OTP from their SMS, and provides it to the client application (and the client passes it back to Storefront Gateway).
  8. Storefront Gateway takes the external account data and creates the Storefront Gateway Account (including Subscriptions and Features, if any).
  9. Storefront Gateway associates the Account to the corresponding User entity, and the back end Group entity.
Post-conditions
  • The user’s external account is now provisioned and linked in Storefront Gateway.
  • The external account details are mapped to the Storefront Gateway Account (and Subscriptions and Features, if any).
  • (Conditional) The mobile number is added to the User profile as an authN ID, and activated (if it wasn’t already prior to the Process).
Possible or Common Errors
  • Invalid account identifier (i.e., not a valid mobile number format)
  • No matching account details found in the operator’s external system.
  • The Account is already associated to another Storefront Gateway User entity.
  • The Account is already associated to the current User entity.

​
App Settings

Certain aspects of the Process’ behavior are controlled by configurable system or app settings. Your organization can manage these and other settings in the Admin console. This Process is affected by the following settings:

​
User Journey Diagram

This flow diagram illustrates the complete user journey using the Associate Billing Account Process (that calls the external system and issues the OTP), and the Complete Account Association Process (that redeems the OTP and associates the account). This diagram shows the Process as invoked by the user. As alternative, the UI could also automatically invoke the Associate Account Process when the user first onboards and authenticates.

​
Use Cases

The following use cases provide guided API walkthoughs of this Process for client developers: Parent topic:Account Association & Management Processes