.. raw:: html

:doc:`← Back <index>`

.. contents::
   :local:
   :depth: 1
   :class: this-will-duplicate-information-and-it-is-still-useful-here



.. _payment-api-jwt-middleware:

Payment API JWT MiddleWare Implementation
=========================================

In order to be able to use the Payment API endpoints every request except those to GetWidget and the Webhook endpoints will require JWT
token authorization.

There are going to be two tokens used through out the API.

**1. The JWT token on GetWidget endpoint (user not logged in)**

Most of our partner use the endpoint `GetWidget` to get the widget html. The html will contain the jwt-token inside the HTML as it currently contains the data-apikey.
Below we can see a sample of how the widget html looks with the jwt-token attribute:

.. code-block:: html

   <style id="mobilum-widget-css"></style>
   <link
     href="https://widget-static.nightly.mobilum.m.xcard.io/css/app.css"
     rel="stylesheet"
   >
   <div
     id="mobilum-widget"
     data-apikey="a7cc0318-66f0-494d-8ee4-0d0dbc612988"
     jwt-token="eyJhbGciOiJIUzM4NCJ9.eyJuYmYiOiIxNjc0MTMxNjM4Iiwic2l0ZVVVSUQiOiI5MzdiNGMzZi1kOTc5LTQxMzMtYjgyOS01Mjg4NzViM2MwZGUiLCJleHAiOiIxNjc0MTUzMjM4IiwiaWF0IjoiMTY3NDEzMTYzOCJ9.nq0kZbf4L_shBXS0Jbje17SRZIVSw_oNhWU4fudFRd-soBh7HdHpcaZwwsJh-If-"
   >
     <div id="userUUid" style="display:none"></div>
     <div
       id="widgetUuid"
       style="display:none"
     >d4c595e3-253c-432c-a279-aa008a2fdf27</div>
   </div>
   <script
     src="https://widget-static.nightly.mobilum.m.xcard.io/js/app.js"
   ></script>


So in the front-end there should be developed a feature so that on every request that they send to the Payment API they should send the token.
An example of a request sent with together with token is as below:

.. code-block:: javascript

   // Verify code via Fetch API
   fetch(
     'https://localhost:5002/Widget/VerifyAnyCode?code=988959&email=vonare2600%40prolug.com',
     {
       method: 'GET',
       headers: {
         accept: 'text/plain',
         apikey: 'a7cc0318-66f0-494d-8ee4-0d0dbc612988',
         Authorization:
           'eyJhbGciOiJIUzM4NCJ9.eyJuYmYiOiIxNjc0MTMxNjM4Iiwic2l0ZVVVSUQiOiI5MzdiNGMzZi1kOTc5LTQxMzMtYjgyOS01Mjg4NzViM2MwZGUiLCJleHAiOiIxNjc0MTUzMjM4IiwiaWF0IjoiMTY3NDEzMTYzOCJ9.nq0kZbf4L_shBXS0Jbje17SRZIVSw_oNhWU4fudFRd-soBh7HdHpcaZwwsJh-If-'
       }
     }
   )
     .then(response => response.text())
     .then(data => console.log(data))
     .catch(err => console.error(err))


At the endpoint ` GetWidget
` if the site calling this endpoint is a fiat-only site then it will automatically receive the JWT token with the permission
that the user passed the log-in because they manage the login on their side, other wise the token will lack of that permission.
The return of unauthorized call is as below:

.. code-block:: json

   {
     "success": false,
     "result": null,
     "text": null,
     "errors": [
       {
         "message": "No session or session is expired!",
         "code": 98
       }
     ]
   }


**2. The JWT token on GetWidget endpoint (user logged in)**

When the user logs in through the OTP verification, on that event so when the widget calls the endpoint `widget/VerifyAnyCode`
on the becakend if the OTP passess successfully the response will be as below: 

.. code-block:: json

   {
     "redirectUrl": "Profile",
     "responseType": null,
     "followUrl": null,
     "success": true,
     "result": {
       "name": "Gentian",
       "surname": "Strana",
       "country": "Canada",
       "dob": "1999-08-26T00:00:00",
       "kycVerified": true,
       "kycInProgress": false,
       "kycFailed": false,
       "userUuid": "2146f970-95ba-4940-b4bd-761b221ec804",
       "JwtToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzaXRlVVVJZCI6ImQ1Mjg4YTcyLWNlNGItNGNhZi04ZjAxLWJjOTljZjY5MTAwYiIsInVzZXJVVUlkIjoiZTg2YTg1ZjItNzE2Ny00NGJlLTljM2ItZDIxNjQ1ZDY1ZTlhIiwicGVybWlzc2lvbnMiOiJVc2VyTXVzdEJlTG9nZ2VkSW4iLCJuYmYiOjE2NzQxMzE4NjgsImV4cCI6MTY3NDE1MzQ2OCwiaWF0IjoxNjc0MTMxODY4fQ.JvjfYJjOF2rULzj4pGWhVlXSrrKyrxBaNHJVYkhBTjBv3xhOC0OnelRg3IbJjQD5Zlr-chIa5v93Dz-hr7QEyw"
     },
     "text": null,
     "errors": []
   }


So now we see that under the result JwtToken
attribute there is a new property which contains the permission that user passed logging in.
The existing token even though it might still be valid on it’s life span should now on be replaced with this new one because most of the endpoints
that are called after the OTP login require the extra permission that is on this new token. It is to be developed on the frontend this switch of jwt
tokens to be handled.

Below we will show the difference of the two tokens:

.. image:: /_static/widget/payment-api-authentication/getwidget-jwt-token.png
   :alt: Image of JWT token getting decoded
   :width: 600px
   :align: center


**3. Partners that only use Payment API Public**

For these partners they should adapt to call the endpoint ` GetWidget` and from there to get the token and then use it in the further HTTTP-calls.

For a smooth transition to production and partners adaptation, the token usage enforcement is configurable per site so for each partner we can decide if we want to enforce the usage of JWT token.

.. include:: /wallet/authentication.rst

**HMAC Implementation example in Java**

.. code-block:: java

   import javax.crypto.Mac;
   import javax.crypto.spec.SecretKeySpec;
   import java.nio.charset.StandardCharsets;
   import java.util.Base64;

   // Your data and secret key
   String data = "string-to-encode";
   String secretKey = "your-secret-key";

   // Encode the data and secret key as bytes
   byte[] dataBytes = data.getBytes(StandardCharsets.UTF_8);
   byte[] secretKeyBytes = Base64.getDecoder().decode(secretKey);

   // Create an HMAC-SHA256 key specification
   SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, "HmacSHA256");

   // Initialize the HMAC-SHA256 algorithm
   Mac hmacSha256 = Mac.getInstance("HmacSHA256");
   hmacSha256.init(secretKeySpec);

   // Compute the HMAC-SHA256 signature
   byte[] signatureBytes = hmacSha256.doFinal(dataBytes);

   // Encode the signature as a Base64 string
   String serverSignature = Base64.getEncoder().encodeToString(signatureBytes);

.. include:: /authentication/jwt.rst