Checkout (including Two Click)

Alacrity Checkout provides a complete customer purchase experience. Redirect your customers to our Checkout page and we will authenticate them, confirm their purchase and return a unique token to you which you can use with our Subscription and Charge APIs. Alacrity Checkout can manage Pin Flow, Header Enrichment and Two Click with SLA hosting the complete customer capture process.

There are two variations of Checkout:

  1. The checkout screens described here and on our Checkout usage guide
  2. A hosted button version which is available as an Iframe described here. This version also works with Mobile Apps.

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

Subscription

Redirect the customer to http://checkout.sla-alacrity.com/purchase

For Zain operators use http://msisdn.sla-alacrity.com/purchase

📘

Info

Please ensure you use http

Include the following parameters in the query string:

NameDescriptionTypeUsage
merchantThe merchant URI that identifies your merchant and can be obtained via the Alacrity portal.stringmandatory
serviceThe unique URI for your service which can be obtained via the Alacrity portal.stringmandatory
redirect_urlYour URL that we will automatically redirect the customer back to after checkout.stringmandatory
localeThe language code as defined in ISO639-1. The chosen language will be used to display the UI.stringoptional
correlatorA unique string for this transaction.stringoptional (mandatory only for Telenor, Axiata, UK)

If any of the above parameters are missing you will be returned to your redirect url as below (except if redirect_url is missing).

Example Request

http://checkout.sla-alacrity.com/purchase?merchant={merchant_uri}&service={service_uri}&redirect_url={url}&correlator={correlator}

or

For Zain operators http://msisdn.sla-alacrity.com/purchase?merchant={merchant_uri}&service={service_uri}&correlator={correlator}&redirect_url={url}

http://msisdn.sla-alacrity.com/purchase?
merchant=partner:4e3f654ed86dbb113bb472be07630b3cb6ad0859&
service=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0
&correlator=123XYZ
&redirect_url=http://test.com/api/callback/123?transaction_id=XXXXXXXX
http://test.com/api/callback/123?
transaction_id=XXXXXXXX&
correlator=123XYZ&
status=success&
token=TOKEN:1c86724f-b09b-4bed-be8f-4683se8efs34&
auth_method=sms_pin`

Once you receive a token you can make a Subscription Create call followed by sending a welcome SMS API.

📘

Info

A token is valid for 120 seconds.

One Off Charge

Redirect the customer to http://checkout.sla-alacrity.com/purchase

or

For Zain operators: http://msisdn.sla-alacrity.com/purchase

Include the following parameters in the query string:

NameDescriptionTypeUsage
merchantThe merchant URI that identifies your merchant and can be obtained via the Alacrity portal.stringmandatory
serviceThe unique URI for your service which can be obtained via the Alacrity portal.stringmandatory
redirect_urlYour URL that we will automatically redirect the customer back to after checkout.stringmandatory
priceThe decimal amount that you want to charge.numericmandatory
localeThe language code as defined in ISO639-1. The chosen language will be used to display the UI.stringoptional
correlatorA unique string for this transaction.stringoptional (mandatory only for Telenor, Axiata, UK)

If any of the above parameters are missing you will be returned to your redirect URL as below (except if redirect_url is missing).

Example Request
http://checkout.sla-alacrity.com/purchase?merchant={merchant_uri}&service={service_uri}&redirect_url={url}&price={price}&correlator={correlator}

or

For Zain operators: http://msisdn.sla-alacrity.com/purchase?merchant={merchant_uri}&service={service_uri}&redirect_url={url}&price={price}&correlator={correlator}

Example Response

Success

If the process is successfully finished you will receive the following via http redirect callback:

http://your-redirect-url?status=success&token={token}&auth_method=[method]

You can then use this token in a One Off charge call.

Possible Auth Method values

ValueMeaning
civilidUser is being authenticated via checkout flow by detecting their MSISDN in the header, and a verification of a Civil ID
header_enrichmentUser is being authenticated via checkout flow by detecting their MSISDN in the header
header_enrichment_csmsUser is authenticated via checkout flow by sending a confirmation SMS
header_enrichment_pinUser is being authenticated via checkout flow by detecting their MSISDN in the header, and a verification of a PIN
operatorUser is being authenticated by operator
sms_pinUser is being authenticated via checkout flow by entering their MSISDN, and a verification of a PIN
sms_pin_csmsUser is authenticated via checkout by pin flow and by sending a confirmation SMS
two_clickUser is being authenticated via two click flow by detecting their MSISDN in the header

Errors

Other errors will be returned to your redirect url and will have the following format:

http://your-redirect-url/?status=error&transaction_id={transaction_id}&message={reason_for_the_error}&auth_method=[value]

Possible Error Messages

Use of Token with API calls

Use the token returned to your callback redirect URL to call the Alacrity API's. Usually, you would need to provide a MSISDN AND pin when calling the Alacrity API's. If you have a token obtained from Checkout you can send this value in the MSISDN field and omit the pin.

For example if you subscribe with Token TOKEN:XXXX then you have to use the same Token TOKEN:XXXX to unsubscribe with the delete API.

Example Subscription Create Request

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

Example flow

From your service landing page replace {API} with
For Zain operators use msisdn.sla-alacrity.com
For Non-Zain operators use checkout.sla-alacrity.com

Call Checkout

  1. Redirect from your landing page: http://{API}/purchase?merchant={merchant_uri}&service={service_uri}&redirect_url={url}&correlator={string}
http://{API}/purchase?merchant=partner:4e3f654ed86dbb113bb472be07630b3cb6ad0859&
service=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
correlator=123XYZ
&redirect_url=http://test.com/api/callback/123?transaction_id=XXXXXXXX
  1. Return from checkout: http://your-redirect-url?status=success&token={token}
http://test.com/api/callback/123?
transaction_id=XXXXXXXX&
status=success&
token=TOKEN:1c86724f-b09b-4bed-be8f-4683se8efs34&
auth_method=sms_pin

📘

Info

A token is only valid for two minutes.

  1. Using returned TOKEN in place of MSISDN, you will not need the PIN parameter with TOKEN

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

POST /v2.2/subscription/create?
msisdn=TOKEN:1c86724f-b09b-4bed-be8f-4683se8efs34&
campaign=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
merchant=partner:4e3f654ed86dbb113bb472be07630b3cb3ad0859&
trial=1&
lanauge=ar HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

The response will contain the msisdn as per the usual subscription create call response.

📘

Info

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

If you subscribe with Token TOKEN:XXXX then you have to use the same Token TOKEN:XXXX to unsubscribe with the delete API.

  1. 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.


What’s Next