Signed URLs

LaterPay’s APIs expect signed URLs. LaterPay can also redirect their users to merchant websites using signed URLs.

Merchants can sign URLs using their secret key.

When the signature is calculated using signing algorithm it is added to the url as hmac query parameter. For example if the signature for a HTTP GET request to http://example.net/abc?x=2 is fakesignature then following are valid signed URLs:

  • http://example.net/abc?x=2&hmac=fakesignature

  • http://example.net/abc?hmac=fakesignature&x=2

LaterPay provides a /validatesignature endpoint where merchants can test if their URL signing process and their credentials are correct.

Signing algorithm

LaterPay APIs use following algorithm to calculate the signature for incoming requests:

  1. Obtain the following:

    secret

    secret string used to sign the request. Example "fakesecret".

    base_url

    HTTP url consisting of scheme, host, path and without query and fragment parts. For example if a request went to http://example.net/p/ath?f=v#frag the base_url would be "http://example.net/p/ath"

    http_method

    HTTP method used in the request. Examples: "GET", "POST", "PUT", "DELETE". Must be uppercase.

    params

    a list of key value pairs constructed from URL’s query string. There can be multiple pairs with the same key. Example (("k2", "v1"), ("k1", "v2"), ("k1", "v1")) from http://example.net/p/ath?k2=v1&k1=v2&k1=v1

  2. Make sure http_method, base_url and all params (both keys and values) are UTF-8 encoded and percent encode them. For example:

    • http_method: "GET" becomes "GET".

    • base_url: "http://example.net/test" becomes "http%3A%2F%2Fexample.net%2Ftest"

    • params:

      (("kæy", "vąl"), ("safe?", "1 + 2 = 3"), ("k1", "v2"), ("k1", "v1"))

      becomes

      (("k%C3%A6y", "v%C4%85l"), ("safe%3F", "1%20%2B%202%20%3D%203"), ("k1", "v2"), ("k1", "v1"))

  3. Alphabetically sort params. First by key and if there are multiple pairs with the same key then by value as well. For example

    (("k%C3%A6y", "v%C4%85l"), ("safe%3F", "1%20%2B%202%20%3D%203"), ("k1", "v2"), ("k1", "v1"))

    should become

    (("k%C3%A6y", "v%C4%85l"), ("k1", "v1"), ("k1", "v2"), ("safe%3F", "1%20%2B%202%20%3D%203"))

  4. Join encoded and sorted params into one string by taking each key/value pair and joining it with "=" and then joining the resulting pairs with "&". For example:

    (("k%C3%A6y", "v%C4%85l"), ("k1", "v1"), ("k1", "v2"), ("safe%3F", "1%20%2B%202%20%3D%203"))

    becomes

    "k%C3%A6y=v%C4%85l&k1=v1&k1=v2&safe%3F=1%20%2B%202%20%3D%203"

  5. Now percent encode the params string. For example

    "k%C3%A6y=v%C4%85l&k1=v1&k1=v2&safe%3F=1%20%2B%202%20%3D%203"

    becomes

    "k%25C3%25A6y%3Dv%25C4%2585l%26k1%3Dv1%26k1%3Dv2%26safe%253F%3D1%2520%252B%25202%2520%253D%25203"

  6. Create the message for signing by joining http_method, base_url and params strings with "&". For example a message for a "GET" request to http://example.net/test?kæy=vąl&safe?=1 + 2 = 3&k1=v2&k1=v1 would be

    "GET&http%3A%2F%2Fexample.net%2Ftest&k%25C3%25A6y%3Dv%25C4%2585l%26k1%3Dv1%26k1%3Dv2%26safe%253F%3D1%2520%252B%25202%2520%253D%25203"

  7. Compute a HMAC using SHA-224 with secret and message. This value HEX encoded and in lowercase is the signature. Signature created using a "fakesecret" secret and our message:

    "GET&http%3A%2F%2Fexample.net%2Ftest&k%25C3%25A6y%3Dv%25C4%2585l%26k1%3Dv1%26k1%3Dv2%26safe%253F%3D1%2520%252B%25202%2520%253D%25203"

    is "cc4ddc63ed0bbea9d1cfad38e4a3f511608510713b33c4585bfa86dd".

Code Libraries

This is the list of code libraries implementing the signing scheme used by LaterPay: