Authentication

In the Merchant API different authentication levels (auth levels) can be achieved depending on the authentication method being used. In Merchant API Reference the required level for each endpoint in the API is given. A list is given here of the auth levels in the Merchant API, ordered from lowest to highest level:

  1. OPEN (no authentication required)
  2. SECRET
  3. KEY

When authenticated with a particular auth level, the client is also authorized for endpoints requiring a lower auth level. E.g. if authenticated with auth level KEY, endpoints requiring SECRET or OPEN are also accessible.

Required request headers

Any request to the Merchant API requires the following request headers:

X-Mcash-Merchant:
 

This header should contain the mCASH ID of the merchant as returned in the id field of the merchant endpoint.

X-Mcash-User:

The ID (username) of the user/client doing the request on behalf of the merchant. Users are created by the merchant through the Self Service Portal or by the integrator using the user endpoint. Each user has is an ID locally unique for the merchant and is assigned a shared secret and/or a RSA public key that is used for authentication.

Authorization:

The value of this field depends on what kind of authentication scheme is being used. Currently the supported schemes are SECRET and RSA-SHA256. The general form of this header is:

Authorization: <auth_scheme> <auth_data>
X-Mcash-Integrator:
 

Only to be used by integrators acting as a proxy on behalf of merchant client, in which case it replaces the X-Mcash-User header. The value of this field is the ID issued to the integrator by mCASH. When this header is used only authentication using RSA signatures is allowed (not secret) and mCASH will check the signature against the public key of the integrator.

Note

When using the mCASH testbed environment, an X-Testbed-Token header is also required. The value of this header is the testbed token you received via email when activating your testbed account. It looks like:

s_Qu1gkYsZUvK-RvO43Ij02CYV-3wyMp5uUn1AodymQ

Note

The X-Mcash-Integrator header MUST NOT be used unless the merchant clients are communicating through a server, controlled by the integrator, acting as a proxy. If a client is using a direct connection to mCASH, even though the integrator owns the client and may control it through some other channel, it MUST use merchant user credentials and the X-Mcash-User header.

Authentication using secret

auth level:SECRET

Authentication using a shared secret is the simplest authentication method supported by mCASH. This method requires an authorization header on the following form:

Authorization: SECRET <secret>

Below is an example of a request where user "POS1" is doing an HTTP POST to http://sever.test/some/resource/ on behalf of a merchant whose ID is "T9oWAQ3FSl6oeITuR2ZGWA". The secret is "MySecretPassword" and the request body is {"text": "Hello world"}.

POST /some/resource/ HTTP/1.1
HOST: server.test
Accept: application/vnd.mcash.api.merchant.v1+json
Content-Type: application/json
X-Mcash-Merchant: T9oWAQ3FSl6oeITuR2ZGWA
X-Mcash-User: POS1
Authorization: SECRET MySecretPassword

{"text": "Hello world"}

Authentication using RSA signature

auth level:KEY

mCASH generates and validates according to the PKCS#1 v1.5 (a.k.a. RSASSA-PKCS1-v1_5) standard described in RFC 3447. The hash function used in the signing procedure is SHA256.

The RSA authentication method requires two extra headers:

X-Mcash-Timestamp:
 

The current UTC time. The time format is YYYY-MM-DD hh:mm:ss.

X-Mcash-Content-Digest:
 

The base64 encoded hash digest of the request body. If the body is empty, the hash should be computed on an empty string. The value of the header should be on the form <algorithm (uppercase)>=<digest value>. So, if the SHA256 hashing algorithm is used on a request with empty body, the header will be:

X-Mcash-Content-Digest: SHA256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

Currently only the SHA256 hashing algorithm is supported.

For RSA authentication the authorization header looks like this:

Authorization: RSA-SHA256 <rsa_signature>

The string that is to be signed (the signature message) is constructed from the request in the following manner:

<method>|<url>|<headers>

Here, method is the HTTP method used in the request, url is the full url including protocol and query component (the part after ?) but without fragment component (The part after #). The scheme name (typically https) and hostname components are always lowercase, while the rest of the url is case sensitive. The headers part is a querystring using header names and values as key-value pairs. So, the constructed string will be of the form:

name1=value1&name2=value2...

In addition the following requirements apply:

  1. Headers are sorted alphabetically.
  2. All header names must be made uppercase before constructing the string.
  3. Headers whose names don't start with "X-MCASH-" are excluded.

Reusing the example in the previous section, a typical HTTP request will look like this:

POST /some/resource/ HTTP/1.1
HOST: server.test
Accept: application/vnd.mcash.api.merchant.v1+json
Content-Type: application/json
X-Mcash-Merchant: T9oWAQ3FSl6oeITuR2ZGWA
X-Mcash-User: POS1
X-Mcash-Timestamp: 2013-10-05 21:33:46
X-Mcash-Content-Digest: SHA256=oWVxV3hhr8+LfVEYkv57XxW2R1wdhLsrfu3REAzmS7k=
Authorization: RSA-SHA256 p8+PdS5dDa6Ig46jNQhE8qQR+J8rRgX77cyXN3EIvUqpQ2lB8Cz1bcUF6lwvdVbz4NSUIQD/OCT8X2WtqRNbPW+5DDzGC1TytiV6p0EXiMOAl7s6kioHnVGaiCSHyfO6ZYB7ubtcMtUE0+7OEUcPeaqSHeL4wwUkO8W0+euwGsfwl9gOoQHBFIOh0bh8z3JNGhUeIZM8fvrk+8kj/s2A70IBvUOLwcFeP8uf6gTi1fz7BtgJ5rHmfvn9HvrsyO53/nx2mXZdAap4MfOZa6dp0ievZ5kU1vEfB2R6f4uPHzKLnaePlDOQMTk+uHlxU0ChkSqenbgJvpGuaOGiQekwsA==

{"text": "Hello world"}

In this case the header part of the signature message is:

X-MCASH-CONTENT-DIGEST=SHA256=oWVxV3hhr8+LfVEYkv57XxW2R1wdhLsrfu3REAzmS7k=&X-MCASH-MERCHANT=T9oWAQ3FSl6oeITuR2ZGWA&X-MCASH-TIMESTAMP=2013-10-05 21:33:46&X-MCASH-USER=POS1

and complete signature message is:

POST|http://server.test/some/resource/|X-MCASH-CONTENT-DIGEST=SHA256=oWVxV3hhr8+LfVEYkv57XxW2R1wdhLsrfu3REAzmS7k=&X-MCASH-MERCHANT=T9oWAQ3FSl6oeITuR2ZGWA&X-MCASH-TIMESTAMP=2013-10-05 21:33:46&X-MCASH-USER=POS1

The key-pair that was used for generating the signature in this example can be downloaded here: public, private

The Python script that was used for generating the signature and X-Mcash-Content-Digest header can be downloaded here

Verifying signatures from mCASH

Whenever mCASH is sending callbacks to the client over HTTPS the request from mCASH is signed using the same RSA method as described in the above section. The client should authenticate callbacks from mCASH by verifying the signature given by mCASH in the Authorization header of the request. The public key used by mCASH in test environments can be downloaded here. The public key for the production environment can be obtained by contacting mCASH.