Authentication
Note: All requests must be sent via the https transport protocol.
To use the Smobilpay S3P API each request must be authenticated according to the S3P Authorization Standard. This method ensures that each request is:
secure
unique
protected against malicious or unintentional duplication and/or replay requests
The core principle of the standard consists of the creation of a complex authentication string composed of multiple authentication elements, most notably a signature calculated from parts of the URL and request body. This authentication string is unique for every request and needs to be provided in the default Authorization header.
Example:
Authorization: s3pAuth,s3pAuth_nonce="634968823463411609",s3pAuth_signature="V5F+YLj2vQNTfZrmg3OYPFZJ4hw=",s3pAuth_signature_method="HMAC-SHA1",s3pAuth_timestamp="1361281946",s3pAuth_token="xvz1evFS4wEEPTGEFPHBog"
Thus, the Authorization header value is a single string of authorization parameter key/value pairs joined by:
The signature domain “s3pAuth”
Parameter key followed by an
=character (ASCII code 61) and a double quote"character (ASCII code 34)Parameter value followed by a double quote
"character (ASCII code 34)Repeat 2+3 for all key/pairs, separating them with a comma character (ASCII code 44)
Credentials
Credentials are provided in form of a Public access token and access secret - provided as a pair and bound to an API user account in Smobilpay. This account is created and managed by the collector company administrator. The token and secret are displayed in the "APIs Access Details" section of the user profile after login. Both can and should be regularly regenerated. It is very important to note that this data is incredibly sensitive and should never be shared with anyone.
Authorization Header Elements
The Authorization is made up of the following elements
Element | Type | Description | Source |
s3pAuth_nonce | String | The s3pAuth_nonce parameter requires a random unique string token to be generated for each request. S3P API will use this value to determine whether a request has been submitted multiple times. Using the same nonce in subsequent requests will result in an error. | Generated per request by client |
s3pAuth_signature | String | The s3pAuth_signature is obtained as the result of the cryptographic signature using the s3pAuth_signature_method algorithm.
| CALCULATED per request by client |
s3pAuth_signature_method | String | The s3pAuth_signature_method used by S3P API is the Keyed-Hash Message Authentication Code (HMAC). | Fixed Value |
s3pAuth_timestamp | Integer | The s3pAuth_timestamp parameter indicates when the request was created in UTC. This value needs to be a standard UNIX timestamp (number of seconds since the Unix epoch) at the point the request is generated, S3P API will reject requests which were created too far in the past (older than 300 seconds/5 Minutes) | Generated per request by client |
s3pAuth_token | String | The s3pAuth_token parameter contains the public access token of the user sending the request. Provided by Smobilpay company administrator. | Fixed Value per API User |
Generate Authorization header
In order to generate the s3pAuth_signature signature, the following steps are necessary:
Combine the http verb of the request endpoint you are calling, the endpoint FQDN, the alphabetically ordered authorization and request parameter keys and their corresponding values into a single string.
percentage encode the resulting string to form the encoded string
Calculate signature using the access secret
The following section demonstrates step-by-step how to generate the signature. NOTE: The URL used in the examples (https://dev.smobilpay.com) is for illustrations only - and not a valid S3P API URL.
Request Examples
Example for POST request | Example for GET request | |
|---|---|---|
API User Credentials (Public access token and access secret) | Public: Secret: | Public: Secret: |
Scenario | Client wants to request a quote for a payment collection worth | Client wants to search for a bill by bill number “ |
URL of Endpoint to call |
|
|
HTTP Method API endpoint |
|
|
Request Body |
| n/a (no body in GET requests) |
s3pAuth_nonce | 634968823463411609 | 634968823463411611 |
s3pAuth_signature_method | HMAC-SHA1 | HMAC-SHA1 |
s3pAuth_timestamp | 1361281946 | 1361281946 |
s3pAuth_token | xvz1evFS4wEEPTGEFPHBog | xvz1evFS4wEEPTGEFPHBog |
Signature Calculation | ||
Step 1: Generate parameter string by joining all components in alphabetical order (Note that for POST requests the parameters are taken from the BODY while for GET requests the parameters are taken from the query URL) |
|
|
Step 2: Assemble Base String by joining in the HTTP Verb + FQDN and percentage encoding the entire string |
|
|
Step 3: Calculate Signature (hmac + access secret) |
|
|
Resulting |
|
|
Hints
Step 1: Generating string by joining alphabetically ordered parameters
Parameter keys and values are case sensitive
Key and value are separated by the '=' character
Separate key/value pairs with the '&' character
Make sure white spaces are trimmed
Make sure all parameters are sorted alphabetically (see http://www.asciitable.com) by the parameter keys (a,b,c…). Consider that uppercase values are smaller than lowercase values. Failing to do so will result in a wrong signature being computed
Alphabetical sorting example:
Parameter keys unsorted | Parameter Keys sorted in alphabetical order |
|
|
Step 2: Assembling the base string
In this step, the three values collected so far (HTTP method, FQDN, Parameter string from step 1) must be joined to create a single string, from which the signature will be generated:
Convert the HTTP Method to uppercase
Append the '&' character
Append the Percentage encoded FQDN
Append the '&' character
Append the Percentage encoded parameter string from step 1
For more on Percentage coding (URL encoding), refer to the following RFC: (http://tools.ietf.org/html/rfc3986.html)
Most programming languages offer functions to perform this task. For example:
PHP: rawurlencode() (http://php.net/manual/en/function.rawurlencode.php)
Python: urllib.parse
Step 3: Signature calculation
The actual signature is calculated by passing the base string created in Step 2 and the access secret into the HMAC-SHA1 hashing algorithm. The details of the algorithm are explained in depth here http://en.wikipedia.org/wiki/HMAC.
Some support tools:
PHP has the hash_hmac() function (http://php.net/manual/en/function.hash-hmac.php) to generate this signature.
Online tool for verification: https://www.liavaag.org/English/SHA-Generator/HMAC/
Feel free to test the base strings created in this document to verify the output signature
The output of the HMAC signing function is a binary string which must be base64 encoded to produce the final signature string to be used as the parameter value in "s3pAuth_signature".
Example
Base String: POST&https%3A%2F%2Fdev.smobilpay.com%2Fs3p%2Fv2%2Fquotestd&amount%3D1000%26payItemId%3DSPAY-DEV-958-AES-100013333-10010%26s3pAuth_nonce%3D634968823463411609%26s3pAuth_signature_method%3DHMAC-SHA1%26s3pAuth_timestamp%3D1361281946%26s3pAuth_token%3Dxvz1evFS4wEEPTGEFPHBog
Secret: MySecretKey
Signatur (base64): 1CLm+TQLwelkE+5Za+Vi+7G5M8U=