Pin Flow (OTP)
The Pin Flow is constructed using API calls:
- PIN API
- Subscription API
- 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.
PIN
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
| Name | Description | Type | Usage |
|---|---|---|---|
| msisdn | The subscriber's MSISDN that you want to send the PIN to. | string | mandatory |
| campaign | The Alacrity service URI that identifies the service that this transaction belongs to. | string | mandatory |
| merchant | The Alacrity merchant URI that identifies which merchant this transaction belongs to. | string | mandatory |
| amount | The decimal amount the user will be charged | string | only required for Zain KSA one-off charge |
| template | The template to be used which will determine the content of the SMS message. Below is a list of the valid options: | string | optional |
| language | The 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. | string | optional |
| fraud_token | For Ireland, Libyana and Almadar operators this will be the token retrieved from loading the fraud script on your first page. | string | Only required for Subscription services with Ireland, Libyana and Almadar Operators |
POST /v2.2/pin?
msisdn=965987654321&
campaign=campaign:56yhws-87e376-yuio43-45yhh7&
merchant=partner:00ow34-al6g67-12o6hh-00ff66&
template=subscription&
language=en HTTP/1.1
Host: api.sla-alacrity.com
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
{
"error":
{
"category": "PIN API",
"cdoe": "3001",
"message": "PIN sending failed"
}
}
Info
The generated PIN will be invalid after 120 seconds.
Please note when using Sandbox credentials, a dummy PIN (000000) will be generated.
Warning
Please note that if the result of sending the PIN message fails for any reason the PIN message will NOT be sent.
Subscription
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.
Info
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.
Info
Alacrity sends an SMS on a successful subscription to inform the customer of the service they have subscribed to and the cost.
Updated 2 months ago