In order to make Access API requests, merchants
can use an
lptoken (a token identifying a LaterPay user). Merchants are
advised to store this token for use in subsequent
Access API requests after they have obtained the token
for a user.
On a website, the easiest way to store an
lptoken for a user is to
store it in a tamper-proof cookie or in a user session (data tied to a user
identified by the merchant’s website). When storing the
lptoken in a
cookie it is advised that the cookie fulfills these requirements:
It should be digitally signed so you can detect attempts by the user to change its value.
It should be tied to user’s session, IP address, user-id or other secondary attribute of a user on your website. This way you can prevent users from sharing their tokens, thereby pretending to be the same LaterPay user.
Tokens can become invalid in a number of cases. For example when a user logs in or out, or if the token expired. In this case, the /access API call will return the following JSON response:
In this case, merchant should delete their stored token and behave exactly as if they didn’t have any token.
In a case when a token was obtained for a user who was logged out of LaterPay
and then that user has logged in, then the response from
/access to a call using this token will reflect the
logged in user’s access status and will contain an additional
field. Merchant should replace their existing token for that user with the value
of that field for later use. This saves the merchant from having to obtain the
token for the logged in user again.
Receiving User Tokens¶
You can ask LaterPay to return user tokens to you by
LaterPay will do so in a signed URL. The URL is signed using the same signature algorithms and the same secret key used for communicating with LaterPay. It’s really important that you verify the signature on a returned token, otherwise users will be able to inject random data into the conversation between you and LaterPay.
Three url parameters will be added by LaterPay to url provided by the service consumer:
lptoken- the identifier which allows LaterPay and service consumer to refer to the same user, browser or device which is currently visiting the service consumer’s website.
ts- token creation time as number of seconds from unix epoch.
hmac- signature created using the same signature algorithms and shared secret used by service consumer to communicate with LaterPay API.
If above parameters appear in original
redir url, they’ll be removed and
replaced by ones provided by LaterPay so that the resulting url will contain
only one of each of these parameters.
Other url parameters present in original url will appear in the url along with the LaterPay provided parameters.
If the original url contains a url
#fragment, it will be appended to
the resulting url.
The signature (
hmac parameter’s value) will be based on:
LaterPay provided parameters:
Parameters from original url.
Base url based on the original url -
URLas described in signing section.
GETas HTTP method
#fragment if present, does not play any role in creation of
An example interaction with /gettoken assuming merchant’s id is
merchantsIdFake and merchant’s shared secret is
merchantsSecretFake looks like this:
Merchant creates a /gettoken url (with
http://merchants-site/hello?id=3#fragment). Resulting url looks like this:
Merchant redirects the user to the above url, user is identified, and a new
lptokenis created. Let’s assume the value of the new
User is redirected to:
After receiving a request containing an
lptoken parameter and validating
and saving it for later use for a user, it is a good practice to redirect the
user to the original target of the request but without
hmac parameters. In our example above, user would be redirected to
http://merchants-site/hello?id=3#fragment. That way, users can safely
share or bookmark the original link (without LaterPay provided parameters).
A common “mistake” is to check for a user token before doing URL path matching, and redirecting to /gettoken regardless of whether or not the path would “resolve”.
This violates the Principle of Least Astonishment,
GET /this/is/totally/bogus gets responses of 302 (to /gettoken) rather than 404.
So for example in Django you would probably not want to check and redirect in a Django Middleware’s process_request because that would be called before the URL matching. Instead you might use class-based views, the code for which will be hit after URL matching, so only for “valid” URLs.