Pin Flow (OTP)

The Pin Flow is constructed using API calls:

  1. PIN API
  2. Subscription API
  3. Send SMS

The PIN API will generate a unique PIN and send 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 manages all subsequent renewals setting http notifications informing a Merchant of successful and unsuccessful renewals. Renewals are retried in line with operator rules.

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.


Before requesting that a PIN is generated for a customer you should prompt the customer to enter their MSISDN. The PIN API will generate a unique PIN and send it via SMS to the specified MSISDN. The PIN length is generally 5 digits apart from 000000 in the sandbox environment

HTTP Request

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

Request Parameters

msisdnThe subscriber's 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
amountThe decimal amount the user will be chargedstringonly required for Zain KSA one-off charge
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 120 seconds.
    Please note when using Sandbox credentials, a dummy PIN (000000) will be generated.



    Please note that if the result of sending the PIN message fails for any reason the PIN message will NOT be sent.


    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.