Pin Flow with Header Enrichment

The Pin flow with Header Enrichment (HE) consists of API calls:

  1. HE API
  2. Pin API
  3. Subscription API
  4. Send welcome SMS

Alacrity provides an API for you to retrieve the customers MSISDN via Header Enrichment (if it is available).

The PIN API will generate a unique PIN and sends it via SMS to the specified MSISDN. The PIN must then be included in the Subscription creation request or One Off Charge API calls. The PIN is used to verify that the customer has opted in to a service.

The Subscription API creates a service subscription for a specified MSISDN. The subscription API includes an option to allow free trials. Once a subscription is created then Alacrity manage all subsequent renewals setting http notifications informing a merchant of successful and unsuccessful renewals. Renewals are typically re-tried for up to 30 days but the rules vary by operator.

The Send SMS is used to send a welcome message to the customer and provide a secondary way for the customer to access the service content.

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

Header Enrichment

This is a two step process:
1 Redirect the user to Alacrity where we will attempt to obtain the MSISDN.
2 Retrieve the MSISDN via the API.

Please review the Header Enrichment usage page for details. If the Header Enrichment call does not return a MSISDN then you should prompt the customer to enter their MSISDN.


Generate a unique PIN and send via SMS to the specified MSISDN using the PIN API.

HTTP Request

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

Request Parameters

msisdnThe subscribers MSISDN that you want to send the PIN to.stringmandatory
campaignThe Alacrity service uri that identifies the service that this transaction belongs to.stringmandatory
merchantThe Alacrity merchant uri that identifies which merchant this transaction belongs to.stringmandatory
templateThe template to be used which will determine the content of the SMS message. Below is a list of the valid options:
  • charge (default)
  • subscription
  • stringoptional
    languageThe language code as defined in ISO639-1. The chosen language will be used in the SMS message. Below is a list of current supported languages.
  • en for English,
  • ar for Arabic
  • stringoptional
    POST /v2.2/pin?
    language=en HTTP/1.1
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Accept: application/json
    HTTP/1.1 200 OK
    Content-Type: application/json
      "success": true
    HTTP/1.1 200 OK
    Content-Type: application/json
        "category": "PIN API",
        "cdoe": "3001",
        "message": "PIN sending failed"



    The generated PIN will be invalid after 300 seconds.
    Please note when using Sandbox credentials, a dummy PIN (000000) will be generated.


    After a customer has been sent the PIN code in an SMS then they should be invited to enter the PIN code on the merchant's service. This PIN code can then be used by the Merchant to call the Subscription API. Please review the Subscription API usage page for details.



    You do not receive a HTTP notification for a create call success or failure. That detail is in the create call response.

    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.



    Alacrity sends an SMS on a successful subscription to inform the customer of the service they have subscribed to and the cost.