Carbon Calculator Reference App

Table of Contents

• Overview
• Requirements
• 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 APIs can be used. To call these APIs, consumer key and .p12 file are required from your project on Mastercard Developers.

Requirements

• Java 17
• 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();

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. 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.
   • test.data.bin - Update this with one of your supported BINs

Use-Cases

1. Calculate Transaction Footprints
   Calculates carbon emission based on payment transactions.

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

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

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

5. View Historical Carbon Impact
   Fetches historical transactions and their footprints for a registered payment card.

6. View Aggregate Carbon Impact
   Fetches carbon score for registered payment card/s and aggregates the same on daily, weekly, monthly and yearly basis.

7. Get Service Provider
   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/test/java/com/mastercard/developers/carboncalculator/ folder.
      • Execute each test cases.
      • In PaymentCardServiceSIT.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 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
        - POST /demo/service-providers/payment-cards

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.

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.