/carbon-calculator-experience-reference-app

Reference application for Carbon Calculator Experience APIs

Primary LanguageJavaApache License 2.0Apache-2.0

Carbon Calculator Experience Reference App

Quality Gate Status Coverage Code Smells

Table of Contents

Overview

This is a reference application to demonstrate how Carbon Calculator Experience APIs can be used. To call these APIs, consumer key and .p12 file are required from your project on Mastercard Developers.

Requirements

  • Java 11
  • IntelliJ IDEA (or any other IDE)

Frameworks/Libraries

  • Spring Boot
  • Apache Maven
  • OpenAPI Generator

Integrating with OpenAPI Generator

OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks. Check Generating and Configuring a Mastercard API Client to know more about how to generate a simple API client for consuming APIs.

Configuring Payload Encryption

The Mastercard Encryption Library provides interceptor class that you can use when configuring your API client. This interceptor will encrypt payload before sending the request.

Encryption Config

FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder
                    .aFieldLevelEncryptionConfig()
                    .withEncryptionCertificate(cert)
                    .withEncryptionPath("$", "$")
                    .withEncryptedValueFieldName("encryptedData")
                    .withEncryptedKeyFieldName("encryptedKey")
                    .withOaepPaddingDigestAlgorithmFieldName("oaepHashingAlgorithm")
                    .withOaepPaddingDigestAlgorithm("SHA-256")
                    .withEncryptionKeyFingerprintFieldName("publicKeyFingerprint")
                    .withIvFieldName("iv")
                    .withFieldValueEncoding(FieldLevelEncryptionConfig.FieldValueEncoding.HEX)
                    .build();

Configuring Response Decryption

The Mastercard Encryption Library provides interceptor class that you can use when configuring your API client. This interceptor will decrypt payload received in response.

Decryption Config

FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
                    .withDecryptionKey(<<mc.p12>>)
                    .withDecryptionPath("$", "$")
                    .withOaepPaddingDigestAlgorithm("SHA-256")
                    .withEncryptedValueFieldName("encryptedValue")
                    .withEncryptedKeyFieldName("encryptedKey")
                    .withIvFieldName("iv")
                    .withFieldValueEncoding(FieldValueEncoding.HEX)
                    .build();

See also:

Configuration

  1. Create your account on Mastercard Developers if you don't have it already.
  2. Create a new project here and add Carbon Calculator Experience to it and click continue.
  3. Download Sandbox Signing Key, a .p12 file will be downloaded. Use this file for payload encryption.
  4. Download mastercard Signing Key, a mc.p12 file will be downloaded. Use this file for payload decryption.
  5. In the Client Encryption Keys section of the dashboard, click on the Actions dropdown and download the client encryption key, a .pem file will be downloaded.
  6. Copy the downloaded .p12 , mc.p12 and .pem files to src/main/resources folder in your code.
  7. Open src/main/resources/application.yml and configure:
    • mastercard.api.environment.basepath - Path to sandbox endpoint,for example for Sandbox https://sandbox.api.mastercard.com/cts
    • mastercard.api.environment.key-file - Path to keystore (.p12) file, just change the name as per the downloaded file in step 5.
    • mastercard.api.authentication.consumer-key - Copy the Consumer key from "Sandbox/Production Keys" section on your project page
    • mastercard.api.authentication.keystore-alias - Alias of your key. Default key alias for sandbox is keyalias.
    • mastercard.api.authentication.keystore-password - Password of your Keystore. Default keystore password for sandbox project is keystorepassword.
    • mastercard.api.encryption.key-file - Path to encryption key (.pem) file, just change the name as per the downloaded file in step 5. mastercard.api.encryption.fingerprint - Fingerprint, copy the fingerprint from Client Encryption Keys section. If you have multiple client encryption keys then copy the fingerprint of the key which you want to use.

Use-Cases

  1. Get Webview URL
    endpoint "/issuers/users/{userid}/dashboards"
    Use this endpoint to get a new token with expiry specified. Language code "lang=en-US" can be passed as query parameter (Not mandatory). Supported lang "en-US,es-419,sv,es-CL,es-CR,pl-PL,ms-MY". Default is "en-US".

  2. Get Current Months Carbon Score
    endpoint "/issuers/users/{userid}/aggregate-carbon-scores"
    Use this endpoint to display the current months' carbon score, to provide a snapshot of their score prior to opening the dashboard.

  3. Enroll User
    endpoint "/issuers/users"
    Use this endpoint to enrol their customers onto Carbon Calculator Experience platform. Donate feature toggle, which allows the issuer to disable the donate feature during onboarding. If the issuer has opted for the Donation feature then the fields - name, billing address, email, locale, cardholder name, card number, card base currency and card expiry date fields are mandatory in the payload.

  4. Get Issuer
    endpoint "/issuers"
    Use this endpoint to fetch issuer details onboarded to Carbon Calculator Experience platform.

  5. Delete User
    endpoint "/issuers/user-deletions"
    Use this endpoint to delete user registered to Carbon Calculator Experience platform.

  6. Update Issuer
    endpoint "/issuers"
    Use this endpoint to update issuer details onboarded to Carbon Calculator Experience Platform. This endpoint is not supported when the Donate feature for your bank is disabled.

More details can be found here.

Execute the Use-Cases

  1. Run mvn clean install from the root of the project directory.
  2. There are two ways to execute the use-cases:

    1. Execute the use-cases(test cases):

      • Run mvn clean install from the root of the project directory.
      • When the project builds successfully, you can run the following command to start the project: java -jar target/carbon-tracker-0.0.1-SNAPSHOT.jar
      • Above command will start the application and execute all the use cases mentioned in readme file

    2. Use REST API based Client( such as Insomnia or Postman)

      • Run mvn spring-boot:run command to run the application.
      • Use any REST API based Client to test the functionality. Below are the APIs exposed by this application ,use locahost:8080 as the Host:
        • GET {HOST}/cts/issuers/users/{userid}/dashboards
        • GET {HOST}/cts/issuers/users/{userid}/aggregate-carbon-scores
        • GET {HOST}/cts/issuers
        • POST {HOST}/cts/issuers/users
        • PUT {HOST}/cts/issuers
        • POST {HOST}/cts/issuers/user-deletions

Service Documentation

Carbon Calculator Experience documentation can be found here.

API Reference

The Swagger API specification can be found here.

Support

Please send an email to apisupport@mastercard.com with any questions or feedback you may have.

License

Copyright 2021 Mastercard

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.