This handbook demonstrates how a Mobile Virtual Network Operator (MVNO) can configure in PortaBilling the charging of SMS (Short Message Service).
To send and deliver SMS messages, MVNOs typically rely on the infrastructure of Mobile Network Operators (MNOs), which includes the Short Message Service Center (SMSC) as the core component responsible for receiving and delivering SMS messages.
The SMSC communicates with PortaBilling via the Diameter (Ro) interface for real-time authorization (AAA) and charging for outgoing SMS messages.
Example
MVNO offers a bundle “1000 minutes of domestic voice calls, 5 GB of wireless data, and 200 domestic SMS for $19.
Preparation
Before you proceed with the configuration steps, coordinate with your MNO on the following:
- If you have not enabled billing via the Diameter protocol yet, you need to decide on the “host” and “realm” values that will be used as your system identifiers in the mobile network, e.g., ocs.company-domain.com as “host” and company-domain.com as “realm.” The MNO’s network equipment should be configured with these identifiers, for the equipment to “know” where to send the Diameter requests (these values will be specified in the Destination-Host and Destination-Realm attribute-value pairs). These values should also be set on the Configuration server web interface within the Origin-Host and Origin-Realm options.
Enabling the Diameter module using these identifiers is a common step for configuring LTE, voice calls, and SMS. If you have already configured LTE service or voice calls, you can skip this step. For SMS, billing via Diameter Ro should be separately enabled (see configuration step 1.3).
- Obtain the MNO’s SMSC identifiers to further specify them in the node settings. These identifiers are sent in the Origin-Host (e.g., ucn1.epc.3gppnetwork.org) and Origin-Realm (e.g., epc.3gppnetwork.org) AVPs (attribute-value pairs) in the Diameter requests sent from the mobile network to PortaBilling. This way, PortaBilling will be able to “understand” which piece of network equipment it’s interacting with.
In case of roaming, prices will depend on the operator tier. Therefore, it will be necessary to create separate tariffs depending on the pricing tier. This depends on various factors, including your circumstances and your roaming hub provider. For more details, please contact our support team.
Skip this step if your MNO uses the same piece of equipment for both voice calls and SMS, and if you have already configured the node during the setup of the voice call service.
Configuration overview
- Setup on the Configuration server web interface
- Enable the external systems provisioning framework
- Create a node
- Create a service policy
- Configure MNO as a vendor:
- Set up the service package:
- Enter SIM cards into the SIM card inventory
- Configure a mobile Internet subscriber:
1. Setup on the Configuration server web interface
To set up the messaging service, ensure that the corresponding service type is enabled in the system. Also, allow the PortaBilling server to exchange packages with the mobile network via the Diameter Ro protocol.
For this, log in to the Configuration server web interface and perform the following steps:
1.1 To enable the messaging service type, set the MessagingService_Enabled option to Yes.
1.2 To allow billing via the Diameter protocol, go to BillingEngine > Diameter group and configure the following global options:
- Enabled – set to Yes.
- Origin_Host – specify the “host” value that is configured as your system identifier on the MNO’s network equipment, e.g., ocs.company-domain.com (on the MNO’s side, it’s the Destination-Host value).
- Origin_Realm – specify the “realm” value that is configured as your system identifier on the MNO’s network equipment, e.g., company-domain.com (on the MNO’s side, it’s the Destination-Realm value).
Leave the default values for other fields.
1.3 To enable billing via the Diameter Ro, set the GW_Adaptors.Ro_enabled option to Yes.
2. Enable the External Systems Provisioning Framework
PortaBilling uses the External Systems Provisioning Framework (ESPF) to automatically notify the mobile core network when a new SIM card should be activated for a specific account and which policy rule to apply. The ESPF captures changes in the account configuration within PortaBilling and sends provisioning events, such as “SIM card has been assigned to an account” or “account product has changed,” to the mobile core network. Then, a code written by PortaOne or a third party translates those events into changes in the mobile core network, such as creation of a new record representing a SIM card with a specific IMSI in HLR/HSS.
For the step-by-step instruction on how to configure ESPF handlers and enable sending the needed events to the mobile core network, refer to the ESPF configuration handbook.
You can find the list of supported events here.
3. Create a node
You need to add the MNO’s SMSC as a node to enable it to exchange charging requests with PortaBilling.
3.1 To add a node:
- Navigate to Infrastructure > Nodes.
- Click Add and fill in the node details:
- Name – a short descriptive name for this node (e.g., “SMS Node”).
- Node ID – specify the “host” value identifying the MNO’s equipment (on the MNO’s side it’s specified in the Origin-Host AVP, e.g., ucn1.epc.3gppnetwork.org).
- IP – specify the IP address of the MNO’s equipment. Since the node will be identified solely by the Node ID, the IP address is used solely for information purposes.
- Manufacturer – select PortaOne.
- Type – select Generic.
3.2 Enable the communication with PortaBilling via the Diameter protocol:
- Go to Node > Communication with billing.
- Turn on the Enable the communication with billing toggle.
4. Create a service policy
PortaBilling is designed to calculate revenue and cost for each transaction to avoid revenue leaks. Therefore, regardless of the service provided, both “customer” and “vendor” entities have to be involved in each charging request. The MNO is configured as a “vendor.”
For the “vendor” entity a connection should be defined. Whenever charging for a messaging service via Diameter Ro protocol is configured in PortaBilling, the system requires a connection of the messaging type (the simplest one to create is an SMPP connection) with a service policy attached to it by design.
To create a service policy in PortaBilling, follow these steps:
- Navigate to Service catalog > Service policies.
- Click Add and fill in the details:
5. Configure MNO as a vendor
A tariff needs to be specified for a vendor in PortaBilling to store the corresponding xDRs (extended Detail Records). This makes it possible to calculate the costs for messages transmitted via the network, which can be used for reconciliation.
The vendor tariff also allows you to calculate the costs incurred for utilizing the MNO’s network resources.
5.1 Create a vendor tariff
- Navigate to Service catalog > Tariff.
- Click Add and fill in the tariff details:
- Name – specify a descriptive name for the tariff, e.g., “Vendor SMS tariff,” which will be used within the system.
- Currency – choose the currency in which the vendor charges you.
The currency for the tariff may be chosen only once and cannot be changed later.
- Service – select Messaging service.
- Format – select E.164.
- Applied to – choose Vendor.
- Routing – leave this toggle disabled.
- Open the Rates tab in the “Vendor SMS tariff.”
To add a rate, you need a destination. Make sure that the needed destinations have been added to the system. See more detail on how to create destinations in the Initial configuration of PortaBilling handbook.
You can add rates one by one or upload them from a file. To download the file sample with all the required columns, click Rate download on the toolbar, then open the notifications tab and click download. To add a rate manually, click Add and fill in the rate details:
5.2 Create a vendor
- Navigate to Infrastructure > Vendors.
- Click Add and fill in the vendor details:
- Name – specify a descriptive name for the vendor (e.g., “LTE Vendor”).
- Currency – leave the base currency.
- Opening balance – this option is usually used when you migrate a vendor from a legacy system to PortaSwitch. Leave “0” here.
- Billing period – choose a billing period for the vendor. A billing period defines how often the vendor will bill you, e.g., monthly.
5.3 Define a vendor connection
By design, a connection needs to be defined for the “vendor” entity in PortaBilling. Since SMS messages are routed by the MNO and you only calculate charges for them, you can create a “dummy” connection:
- Open Vendor > Connections.
- Click Add and fill in the connection details:
- Description – type in a short description for this connection (e.g., “SMS”).
- Service type – select “Messaging service”.
- Type of connections – select SMPP.
- Tariff – select the vendor tariff that you created at step 5.1.
- Active – leave this toggle disabled.
- Internal – leave this toggle disabled.
- Gateway ID – specify the “RO” value here.
- Port – leave the default port (“2775”).
- Service policy – select the service policy created at step 4.
6. Set up the service package
To provide SMS service to your customers as described in the example, you need to create a Product that includes:
- A Bundle that includes 200 SMS.
- A Tariff for messaging service with at least one rate, as it should always be included in any main product in PortaBilling.
6.1 Create a customer tariff
- Navigate to Service catalog > Tariffs.
- Click Add and fill in the tariff details:
- Name – type in a short name for the customer tariff; this name will be shown within the system.
- Currency – select the currency in which you will charge your customers.
- Service – select Messaging service.
- Applied to – select Customer as this tariff will be used to charge your customers.
- Managed by – select Administrator only here.
- Open the Rates tab in the “Customer SMS tariff” tariff.
To add a rate, you need a destination. Make sure that the needed destinations have been added to the system. See more details on how to create destinations in the Initial configuration of PortaBilling handbook.
You can add rates one by one or upload them from a file. To download the file sample with all the required columns, click Rate download on the toolbar, then open the notifications tab and click download. To add a rate manually, click Add and fill in the rate details:
6.2 Create a destination group set and a destination group
In PortaBilling, a bundle (step 6.3) always incorporates a destination group set, which must consist of at least one destination group. A destination group may include phone prefixes (e.g., 1206) and/or special destinations used for the services provided within the bundle.
To create a destination group set and a destination group:
- Navigate to Service catalog > Destination group sets.
- Click Add and fill in the required information:
- Open the created Destination group set.
- Click Add and fill in the Destination group name and description, e.g., “Spain”.
- Click Save to save the destination group.
- To add the phone prefixes to the created destination group:
- On the Destination group page, click the default All destinations group.
- On the Destination search panel, specify the parameters (e.g., format, prefix, country) to find the required destination in the list and click Apply filters.
- On the Destination list panel select the prefix you want to include in the destination group and click Assign to group.
- Select the destination group (“Spain”) and click Assign. The selected prefixes will be added automatically to the destination group.
6.3 Create a bundle and define the SMS quota
The SMS quota (e.g., 200 SMS) that has auto-renewal for a defined renewal fee (e.g., $19) can be provided within a prepaid bundle.
To configure a bundle with the quota:
- Navigate to Service catalog > Bundles.
- Click Add and fill in the bundle details:
- Name – specify a unique bundle name (e.g., “5GB-1000min-200SMS”).
- Currency – select the currency in which you charge your customers.
- Destination group set – select the destination group set created at step 6.2.
- Managed by – select “Administrator only”.
- Apply bundle if a destination is found that – leave the default option “Matches the rate exactly”.
- Bundle type – select “Repeated use with renewal”.
- Automatic renewal – select “On sufficient fund” to automatically renew the bundle if the customer has enough ($19) on their balance.
- Bundle lifetime, days – specify the value, e.g., 30 days.
- Renewal fee – specify $19.
- Description – optionally, you can add a short description for this bundle.
- Click Save.
- Open the created Bundle and go to Bundle items.
- Click Add and fill in the bundle item details:
- Service – select the Messaging service.
- Destination group – select the destination group configured at step 6.2.
- Measured as – select Service used.
- Service volume – specify 200 messages.
- Click Save (you will be redirected to the Bundle item panel).
- Go to Bundle item > Configuration and set up the bundle item according to the given example:
- Go to Bundle item > Notifications to configure notifications that will be sent to customers:
- Click Save.
6.4 Create a product
Create a product which will be assigned to accounts for service provisioning:
- Navigate to Service catalog > Products.
- Click Add and fill in the product details:
- Name – type in a short name for the product; this name will be used within the system.
- Name visible to end users – specify the name of the product that your customers will see on their self-care web interface.
- Product type – select Main product here.
- Currency – choose a currency the product will be priced in.
- Managed by – select Administrator only here, since we are setting up a service without the involvement of resellers.
- Account default ACL – choose an Access Control List (ACL) for accounts with this product assigned. ACLs control which objects end users can access and which actions they can perform.
- Account role – select Mobile to associate this product with mobile subscribers.
- Click Save.
- Go to Product > Services and click Add to select services included in the product. To provide messaging service, you need to include two services: Mobile network provisioning (the default one, used for provisioning) and the Messaging service.
To provide other services within this product, e.g., voice calls, include them in the list too.
- Configure general info:
- Go to Product > Charges > General info and fill in the details:
- Overdraft protection – leave the toggle turned on (turning off the overdraft protection is not recommended for general use).
- Default bundle – select the bundle created at step 6.3.
- Click Save.
- Configure usage charges:
The rating list has two functions: it defines permitted access points (nodes and access numbers), and specifies which tariff should be used for billing in each of these points.
- On your product’s panel, click Charges, then click Usage charges.
- On the Usage charges panel, click Add.
- Fill in the required information:
- Service – select Messaging service.
- Node – select the SMS node created at step 3.
- Access code – leave this field empty.
- Tariff – select the tariff that applies to your customers when they use the messaging service.
- Overdraft protection – to configure overdraft protection for this product, consult the Overdraft protection configuration handbook. In short, overdraft protection locks a certain amount of resources for each session. This enables the simultaneous consumption of the same quota across different sessions on various devices. Although it’s typically not a concern for basic LTE service, where customers generally use only one SIM card, it’s a good practice to leave the overdraft protection turned on.
- Click Save.
7. Enter SIM cards into the SIM card inventory
Refer to the Enter SIM Cards into the SIM Card Inventory section of the MVNO service provisioning handbook to find out how to add SIM cards into the SIM card inventory.
8. Configure a mobile Internet subscriber:
8.1 Create a customer
A customer is an owner of accounts. Customer contact information is used for distributing account usage information, Internet access statistics, invoices, etc. You usually need to create one customer per each retail prepaid user.
- On the navigation menu, select Sales, then select Customers.
- On the Create customer panel, fill in the customer details:
- Name – type a short name for the customer object; this will be used on the web interface.
- Balance control – select Prepaid in this field.
- Currency – choose the currency in which this customer will be billed.
- Available funds – the amount of funds available for the customer to spend on services (e.g., $19 for bundle activation). If the customer has a debit account, the account’s funds will be used.
- Business model – a business model defines what type of service is to be provided to the customer. Select Mobile for this customer.
- Customer class – customer class allows you to define a policy for automated payment collection. By choosing a specific class here the customer will automatically inherit all of the class properties (grace period, invoice template, etc.). Select the previously created customer class.
- Billing period – choose a billing period for the customer.
- Billing period time zone – choose a time zone in which the customer’s billing period will be closed and invoices will be generated.
- Click Save.
8.2 Create an account
Create an account for each device that has a unique SIM card.
- On your customer’s panel, click Accounts.
- On the Create an account panel, specify the account’s details:
- ID – you can type in the user’s mobile phone number manually or provision it from the DID inventory.
- Account role – select Mobile.
- IMSI – click on IMSI icon and select one of the available SIM cards from the SIM Card Inventory dialog box.
- Product – select the “LTE Product” here.
- Activation date – the date from which the account is usable.
- Type – select Credit.
- Balance control – select Subordinate from the list (the account doesn’t have a separate balance – the customer’s prepaid balance will be used).
- Click Save to create an account.