benjaminchodroff / carbon-calculator-reference-app

Carbon Calculator Reference Application

Carbon Calculator Reference App

Table of Contents

• Overview
• Prerequisites
• Frameworks/Libraries
• Integrating with OpenAPI Generator
• Configuration
• Use-Cases
• Execute the Use-Cases
• Service Documentation
• API Reference
• Support
• License

Overview

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

Prerequisites

• 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 API.

Configuring Payload Encryption

The Mastercard Encryption Library provides an interceptor class that you can use when configuring your API client. This interceptor will encrypt the 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();

See also:

• Securing Sensitive Data Using Payload Encryption.

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 to it and click continue.
3. Download Sandbox Signing Key, a .p12 file will be downloaded.
4. 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.
5. Copy the downloaded .p12 and .pem files to src/main/resources folder in your code.
6. Open src/main/resources/application.yml and configure:
   • 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. The default key alias for sandbox is keyalias.
   • mastercard.api.authentication.keystore-password - Password of your Keystore. The 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.
   • test.data.bin - Update this with one of your supported BINs

Use-Cases

1. Transaction Footprints Calculation
   Calculates carbon emission and water usage based on payment transactions.

2. Get Supported Currencies Provides a list of Currencies supported by the application.

3. Get Supported Merchant Categories
   Provides a list of Merchant Category Code (MCC) supported by the application.

4. Add Payment Card
   Allows a registered Service Provider to add a new Payment Card under its profile.

5. View Historical Transaction Footprints
   Fetches historical transactions and their footprints for a registered payment card.

6. View Aggregate Transaction Footprints
   Fetches carbon score for registered payment cards and aggregates the same on daily, weekly, monthly, and yearly basis.

7. View Service Provider Details
   Fetches service provider details.

8. Update Service Provider
   Allows a registered Service Provider to update its configuration on the server. A Service Provider should mandatorily call this API first after their successful project creation on Mastercard Developers Platform before they can successfully call other APIs.

9. Delete FPAN
   Allows a registered Service Provider to delete one or more Payment Cards from its profile. Any data associated with a requested paymentCardId will also be deleted permanently.

10. Bulk Enroll FPAN
    Allows a registered Service Provider to add list of new Payment Cards under its profile

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):

      • Go to src/main/java/com/mastercard/developer/carboncalculator/usecases folder.
      • Execute each test case.
      • In PaymentCardServiceTest.java, note that a random FPAN is generated starting with your BIN while adding a new payment card and the paymentCardId of this card is used while executing the other two test-cases.

   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:
        - POST /demo/transaction-footprints
        - GET /demo/supported-mccs
        - GET /demo/supported-currencies
        - POST /demo/payment-cards
        - POST /demo/aggregate-transaction-footprints
        - GET /demo/historical/{paymentcard_id}/transaction-footprints
        - GET /demo/service-providers
        - POST /demo/payment-card-enrolments
        - PUT /demo/service-providers
        - POST /demo/payment-card-deletions

Service Documentation

Carbon Calculator documentation can be found here.

API Reference

The Swagger API specification can be found here.

Support

Please send an email to [email protected] with any questions or feedback you may have.
Contact the Customer Implementation Support (CIS) representative for any query to integrate Carbon Calculator APIs.

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.