SBS Purchases

Carrier Billing Purchases

If your app allows subscriptions to be created over SMS for example, everything will be under Kiwi control, since we do not need to integrate with Hermes to create this subscription.

The next steps shows how to configure Hermes and Kiwi to achieve Carrier Billing

Configuring Kiwi for SBS Carrier Billing

We assume for this manual that your application is already configured on SBS. This step should be performed prior to configuring Kiwi. We will only go through the interface settings.

If you are unsure about the configuration parameters you can contact the SBS team on Jira and request them the configured parameters on SBS.

If this is a new application, you should have received the parameters to be configured from the Product Team or the person responsible for the negotiation with the carrier.

1. Access your application on Kiwi Admin

2. On Monetization, check if you have SBS configured and click on "New Subscription Platform" if needed.

3. Edit the SBS plarform configuration and enter the informations asked. (Sku script chooser can be left blank).

   • Monetization Platform: Choose SBS.

   • Origin: Represents the channel whose your subscriptions will be created. You can choose between GADGET or APP.

4. In the Carrier configurations, create an entry for each carrier your app will work with.

   • A form will appear for each carrier you select, fill the fields for each one:

     • Carrier: Choose the carrier you are configuring.

     • Application Id: Is the applicationId field configured in SBS, it represents your application's record.

     • Restore large account: Is the short code to be used when the user is restoring a subscription (when a subscribed user reinstall it's app).

     • Restore optin message: The message to be sent to the user when restoring a subscription (this message contains the pincode that the user will use to authenticate.). Note: inside the message, use %pincode% as a placeholder that will be overridden with the pincode.

5. Click "Save" to complete this part of the process.

6. On the platform listing click on "SKU Configurations" on the actions column for SBS

7. Click "New Configuration"

8. Enter a SKU name to be used by the application.

9. Select the Share Type.

   • SHARE_NOTHING the subscription is not shared.

   • SHARE_ACROSS_PRODUCT the subscription can be shared between apps of the same product.

10. Select the renew period.

11. Select if the SKU has a trial period and enter the trial period in days.

12. Select the currency code for this SKU and enter the price.

13. Enter the reference id for this SKU provided by the SBS team.

14. In the Carrier Configurations, create an entry for each carrier you want this sku to be available to (Generic configuration may be added)

    • A form will appear for each carrier configured. For every one of them , fill the fields:

      • Carrier: Chose the carrier you are configuring

      • ChargeId: Enter the chargeId configured in SBS (this is the numeric field SBS returns on profile request)

      • Charge: Enter the charge configured in SBS (it is the name of the package, used in a bill request, for example).

      • Use Local Authentication: When this is true, Kiwi will send a sms to the user itself. When it is false, the carrier will handle this flow.

      • External Authentication Parameters (localAuthentication=false)If you won't use local authentication, put the carrier's specific parameters (Ask SBS team) into the External Authentication Parameters field.

      • Large Account: Put the shortcode you will use to perform the authentication process.

      • Optin Message: Put the optin message that will be sent to the user when subscribing (this message contains the pincode that the user will use to authenticate.). Note: inside the message, use %pincode% as a placeholder that will be overridden with the pincode.

15. Click "Save" to complete the process.

Subscription callbacks (action listeners)

Kiwi is capable of handling SBS's action listeners and perform specific actions based on them. The following are available:

Automatic account linking by MSISDN

Supported app platforms: WEB only

This callback checks for the existence of an account by MSISDN with the phone number used to subscribe on SBS. If not found, it creates a new one. Then, the subscription is automatically linked to the account. The user can perform sign in to access its subscription seamlessly. This callback should be configured for subscribe events.

URL to be configured:

https://tools.kwsdk.io/external/1.0/sbs/callback/create_account?kiwiApplicationId=YOUR_KIWI_APPLICATION_ID&sbsSubscriptionId=$subscriptionId$&sbsApplicationId=$app$&chargeId=$chargeId$&phone=$phone$&referenceId=$reference$&carrierId=$carrierId$

Remember to replace YOUR_KIWI_APPLICATION_ID with your application id when configuring the action listener on SBS. Otherwise, the calls to Kiwi may fail or (even worse) assign the subscription to the wrong application. The other placeholders (e.g. $app$) are used by SBS and should be left as is.

One more reminder: Kiwi relies on the chargeId to determine a subscription's SKU. You need to ensure that the subscription is being created with the correct charge and that the charges used by your app are configured on Kiwi, otherwise the register process will fail.