Hosted Button Integration

The hosted button is a variation on checkout but instead of the MSISDN entry and pin entry screens being separate screens hosted by SLA these screens are presented within an Iframe. The screens are hosted by SLA.

Flow

The operation of Hosted Button varies according to the permitted flows for a service. Flow requirements should be discussed with SLA Digital in the initial service creation stage. The following are supported:

• PIN Flow (or OTP)
• Header Enrichment (HE)
• Two Click
• One off charges

A typical flow would be:

• User is directed to your landing page
• From the landing page an Iframe is opened
• Control is returned to the merchant page with a token via the slaCallback function
• The token should be used in a subscription create call instead of the MSISDN

Example API calls are shown below.

Within the Iframe the user is:

• prompted for their MSISDN if HE is not available
• prompted for their pin if the service is on Pin or OTP flow
• asked to confirm that they wish to subscribe to the service

Integration with your Landing or Payment Page

The payment page is typically the last screen on which the user confirms they wish to acquire the service.

The script handles the consent of the user by returning a TOKEN. Use the returned TOKEN in place of MSISDN, in the Subscription create call:

POST /v2.2/subscription/create?msisdn={msisdn}&pin={pin}&campaign={campaign}&merchant={merchant}&language={language}

The response to the subscription create call will include the user MSISDN.

You do not need to call the PIN API, as the script will handle this from capturing the MSISDN and validating the PIN.

📘

Note

Your payment page must use http and not https to use this method otherwise any services with HE will not work

Include our javascript in the head section of your payment page.

<script src="http://checkout.sla-alacrity.com/sla.js"></script>

In your page where you would like the button to appear include the following empty div.

<div id="paymentButton"></div>

Include the following javascript immediately before the closing body tag of your page.

<script>
    function slaCallback(e) {
      if ( e.origin === 'http://checkout.sla-alacrity.com' ||
           e.origin === 'https://checkout.sla-alacrity.com' ) {
        var data = e.data;
        if (data['status'] === 'error') {
          //Add your custom error handling code
          //data['message'] will contain the error reason
        }
        if (data['status'] === 'success') {
          //data['token'] will contain the TOKEN that can be used with the subscription/create API
        }
      }
    }
    window.addEventListener('message', slaCallback, false);
    
    (function() {
      var credentials = {
        merchant: '<your partner uri>',
        service:  '<your campaign uri>'
      };
      var custom = {
        
      };
      const sla = new Sla(credentials, custom);
      sla.showButton();
    })();
  </script>

📘

Info

Make sure only to only inject one iFrame on a page. From the same payment page you should not inject multiple iFrames such as one for each service frequency, i.e. daily, weekly

Edit Javascript

Edit the credentials variable use your partner uri and campaign uri available via the Alacrity portal.

Add your own custom javascript code to handle success and error callbacks from SLA. If the status is success then there will be a token returned and you can use the token to create the subscription using our subscription/create API.

If the status is error then message will contain the reason for the error. Some possible values for message can be seen here.

Customisation

You can customise certain css attributes of the button by passing them in the custom variable. This is a list of all available customisations (if you leave any of them out the default value will be used).

Below is an example of adding these customisation options to the custom variable.

var custom = {
  width: '200px',
  height: '60px',
  background_color: '#00BC01',
  font_color: '#FFFFFF',
  font_size: '22px',
  border_radius: '15px',
  instruction_font_color: '#000000'
};

Using the default values the button will appear like this.

❗️

Error

If you get an error button_integration_not_allowed then you need to contact SLA to enable this flow for your service.

❗️

Error

If you get an error message blocked then the fraud prevention mechanism has blocked access to the service from this MSISDN. This can occur, for example, if the phone is outside of the country.

Example flow

All HTTP request parameters should be passed in URL Query String - query_params.

1. Direct the user to your Landing or Payment Page
   On the Landing page display the Iframe as shown above.

2. A TOKEN is made available accessed via the slaCallback function - shown above.

📘

Info

A token is only valid for two minutes.

3. Create a subscription (or call one off api) using returned TOKEN in place of MSISDN, you will not need the PIN parameter with TOKEN:

POST /v2.2/subscription/create?msisdn=TOKEN:2891333c-xxxx-4f3c-ab57-xxxxxxxx&campaign={campaign}&merchant={merchant}&language={language}

The response will contain the MSISDN. See more detail on the Subscription Create API guide. (Note the difference with Create Trial. The example above does not show the free trial parameters.)

For a One Off charge service then instead of Subscription create you use https://docs.sla-alacrity.com/docs/one-off-charge

4. Send welcome SMS

After a customer subscribes it is required that a merchant send a welcome SMS with the details of how to access a service. This reduces the likelihood of a customer losing access to the service thereby reducing customer complaints.

Please review the Send SMS API usage page for details.