# Consent Management UI implementation guide
source: https://developer.mastercard.com/consent-management/documentation/tutorials/auth-consent-ui/index.md

## Overview {#overview}

To launch the consent flow UI you will need to:

1. Include `https://consents.mastercard.com/js/ConsentUI.js` Javascript file,
2. Create a [JWT](https://developer.mastercard.com/consent-management/documentation/tutorials/auth-consent-ui/index.md#jwt-creation) and
3. Provide a callback function where your application will receive messages.

### Include ConsentUI.js {#include-consentuijs}

Below is the sample code how you can use ConsentUI in your code:
* Javascript

```javascript
<script type="text/javascript" src="https://consents.mastercard.com/js/ConsentUI.js"></script>
<script>
let consentUI = new ConsentUI({
    container: ".consent-ui",
    jwt: "eyJ0eXAiOiJKV1..",
    src: "https://consents.mastercard.com",
    callback: function (msg) {
       console.log("Consent UI message received:" + msg) 
    }
});
</script>
```

### JWT Creation {#jwt-creation}

You can use any JWT library to create and sign the JWT token. JWT token components must be in format mentioned below:

#### Header {#header}

Mandatory fields for the JWT header creation:

|   Name   |   Type   |                Description                |                 Notes                  |
|----------|----------|-------------------------------------------|----------------------------------------|
| **type** | `String` | The type of token.                        | **JWT** is the only available value.   |
| **alg**  | `String` | The Algorithm for securing the token.     | **RS256** is the only available value. |
| **kid**  | `String` | The Client ID from Mastercard Developers. |                                        |

* Json

```json
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "XXXXXXXXX!XXXXXXXXXXXXXXXXX0000000000000000"
}
```

#### Payload {#payload}

Mandatory fields for the JWT payload creation:

|          Name           |    Type     |                                  Description                                   |
|-------------------------|-------------|--------------------------------------------------------------------------------|
| **exp**                 | `Date Time` | Expiration Time claim. Must be within 15 minutes of starting the consent flow. |
| **iat**                 | `Date Time` | Issued At claim. The time the JWT was issued.                                  |
| **jti**                 | `String`    | JWT ID At claim. Unique id for jwt token.                                      |
| **nbf**                 | `Date Time` | Not Before. The time before which the JWT must not be accepted for processing. |
| **appdata**             | `Object`    | Client application data claim.                                                 |
| **appdata.callbackURL** | `String`    | The URL to receive messages from consent flow Iframe.                          |

* Json

```json
{
"exp": 1583760792,
"iat": 1583758992,
"jti": "cb",
"nbf": 1583758992,
"appdata": {
  "callbackURL": "https://fintech.com"
}
}
```

### Token Signing {#token-signing}

Sign the JWT using the secret key provided by Mastercard Developers.
* Java

```java
  String consumerKey = "consumerKey";                   // Consumer key from Mastercard Developers Project page
  PrivateKey privateKey = loadPrivateKey();             // Private key from Mastercard Developers
  String callbackUrl = "appname:redirectCardReference"; // Depends on the application type.

  HashMap<String,String> appData = new HashMap<>();
  appData.put("callbackURL", callbackUrl);
  
  long validityInMs = 1000*60*15;                       // 15 minutes

  Date now = new Date();
  Date validity = new Date(now.getTime() + validityInMs);

  Claims claims = Jwts.claims();
  claims.setIssuedAt(now);
  claims.setNotBefore(now);
  claims.setExpiration(validity);
  claims.setId("cb");
  claims.put("appdata",appData);

  String jwtToken = Jwts.builder()
          .setHeaderParam("typ","JWT")
          .setHeaderParam("kid", consumerKey)
          .setClaims(claims)
          .signWith(SignatureAlgorithm.RS256, privateKey)
          .compact();

```

Please refer to [jwt.io](https://jwt.io/) for more examples.

### Consent Flow Result {#consent-flow-result}

Throughout the UI flow, your application will be notified for below events on Mastercard Consent UI through callback function you have provided while ConsentUI object creation.

1. Every response user gets from Mastercard API,
2. Any error which is not handled by UI
3. Close or Cancel action on UI

The message received on callback function has two fields:

|   Name   |   Type    |                       Description                        |
|----------|-----------|----------------------------------------------------------|
| **type** | `String`  | Type of the message. (Close, Error, ApiResponse, Cancel) |
| **data** | `Object ` | Content of the message.                                  |

#### Sample event messages {#sample-event-messages}

Below is the sample message you will get when UI gets the response from mastercard server:
* Json

```json
{
    "type": "ApiResponse",
    "data": {
        "cardReference": "c851a2e6-1h6d-47f7-46d5-2489a8c29c86",
        "auth": {
            "status": "AUTH_IN_PROGRESS",
            "type": "THREEDS"
        }
    }
}
```

<br />

Below is the sample message you will get on successful enrolment:
* Json

```json
{
    "type": "Close",
    "data": {
        "status": "success",
        "cardReference": "c851a2e6-1h6d-47f7-46d5-2489a8c29c86",
        "expiryDate": null
    }
}
```

Below is the sample message you will get on error/failure in enrolment:
* Json

```json
{
    "type": "Error",
    "data": {
        "status": "error",
        "errorCode": "auth.failed",
        "errorMessage": "Authentication failed: Stolen card"
    }
}
```

Below is the sample message when user cancels flow by tapping on cancel button:
* Json

```json
{
    "type": "Cancel",
    "data": {
        "status": "cancelled"
    }
}
```

<br />

## Reference App {#reference-app}

Download the Authentication \& Consent Management UI reference app based on java from here:
[consent-java-ref-app.zip](https://static.developer.mastercard.com/content/consent-management/uploads/consent-java-ref-app.zip) (674KB)