Using your own receiving server

We have implemented our own receiving servers: One for receiving and processing SMS and another for receiving and processing emails. The job of that receiving server is to handle the incoming webhook from either the SMS gateway we use or the incoming webhook from our email system that handles. Our receiving servers removes the originator ID (either phone number in case of SMS or the email address of the user) The receiving server in question will never pass that on to our main authentication server. Instead only a hash is sent to us (It is called a "proxy") But some merchants may want to use their own receiving server. Why so? Because they may have a use case where they indeed want to collect the user's phone number (or the user's email address) when the user enters their website for the first time. In such case, you will also have to register that receiving server with us. And also sign a document with us that you will not misuse the phone numbers/email address so collected. We'll then explain here what JSON data should POST to our own authentication server. NOTE 1: When such a customized receiving server is used, we will be informing that merchant's users that their phone number/email address could get used, when the user starts the authentication process. NOTE 2: It is quite easy to achieve the same end goal without resorting to an additional server, actually. The merchant can always ask for the user's originator ID (phone number or email address; as the case may be) as an additional step at the merchant's end after the user enters the merchant's website using Simply Sign In. The merchant can then also easily check whether the user used the same phone number (or email address) as the one that was used when the Simply Sign In process was initiated. Hence, in such a case, a separate customized receiving server is not needed. The only drawback (if you can really call it that) is that the user has to type his originator ID twice: Once at the beginning and once at the end.

Code for Receiving Server

If you do use your own receiving server to handle either the user's SMS or the user's email address, you would need to setup the configuration for such a server with us. This configuration is needed:

  1. A Receiving server ID has to be set. Make this quite complex (like a password) and never reveal it to anyone else ... If it gets revealed, then some other merchant may use your Receiving server to process their SMS -- which may lead to losses at your end.

  2. A shared secret (RS_SECRET) will be set for this receiving server by us. Store that in a safe place and keep it a secret!

  3. Set a keyword for the Prepend field. For e.g. In our SMS receiving server, the prepend field is "3RXY9" That is the keyword which must be present at the start of the SMS.

  4. Set the destination phone number to which the SMS server is to be sent. In India, the SMS system is quite restricted. So we have given two fields for two phone numbers which the user has to send the SMS to. One is for India and one is for outside India. If you are not implementing an SMS receiver, but it is an email receiver; then specify the email address in both those above fields.

  5. NOTE: To finally save the configuration, you would be asked to sign an agreement so that we are reasonably sure that the data you collect from your users do not violate our own legal terms and conditions.

  6. Lastly, a prompt needs to be set for this receiving server: It should give a pithy explanation on what the user should do so that the data goes to that receiving server. For example:

 <br><br>
<b>Just send us one simple SMS (text) from your mobile phone.</b>
<br>
<i>Your phone number is used only in this browser!</i>
<br>It is never sent to any server. Not even ours!
<br> 
Read <a href='https://docs.simplysign.in' target='docs' title='opens in a new tab'>our documentation</a> on how this works.</i>

Once you have setup a receiving server; there is only one piece of code that such a server has to execute.

Once the SMS (or the email) sent by the user reaches your end you must send an http request with POST method to our end point. We will announce the URL to which the POST data has to go into when your configuration is accepted (It would be different for each of the receiving servers' configuration that we have saved)

The data for that POST is a JSON structure as shown below 

data = {
    prox: <prox>, //the proxy of the number/email the user had sent here
    totp: <totp>, //the totp that the user had sent here
    theMerchant: <merch>, //The merchant id obtained from the SMS or email SUBJECT
    merchid_h: <merchid_h>, //the hashed merchid 
    signed:  <Signature>,  //This tells SSI that the data sent to it is genuine
    r_id: <receiver_id>  //The ID of this receiving server. 
    }

The values for the above fields are created as follows:

<prox>: SHA256 of the origination ID (either the user's no or email address)
<totp>: the totp that the user had sent here in the SMS or email SUBJECT
<merch>: The merchant id from the SMS or email SUBJECT
<merchid_h>: the hashed merchid. (SHA256 of  <merch> + <RS_SECRET>)
<Signature>: SHA256 of (<merchid_h> + <totp> + <prox1> + <RS_SECRET>)
<receiver_id>: The ID of this receiving server. 
 

NOTE <RS_SECRET> is the shared secret that was given by us when 
the receiving server was setup

PreviousFAQ: Frequently Asked QuestionsNextUsing textlocal.in

Last updated