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 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();
See also:
Configuration
- Create your account on Mastercard Developers if you don't have it already.
- Create a new project here and add Carbon Calculator to it and click continue.
- Download Sandbox Signing Key, a
.p12
file will be downloaded. - 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. - Copy the downloaded
.p12
and.pem
files tosrc/main/resources
folder in your code. - 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 pagemastercard.api.authentication.keystore-alias
- Alias of your key. Default key alias for sandbox iskeyalias
.mastercard.api.authentication.keystore-password
- Password of your Keystore. Default keystore password for sandbox project iskeystorepassword
.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
-
Calculate Transaction Footprints
Calculates carbon emission and water usage based on payment transactions. -
Supported Currencies
Provides a list of Currencies supported by the application. -
Supported Merchant Categories Provides a list of Merchant Category Code (MCC) supported by the application.
-
Enroll FPAN
Allows a registered Service Provider to add a new Payment Card under its profile. -
View Historical Carbon Impact
Fetches historical transactions and their footprints for a registered payment card. -
View Aggregate Carbon Impact
Fetches carbon score for registered payment card/s and aggregates the same on daily, weekly, monthly and yearly basis. -
Get Service Provider
Fetches service provider details. -
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. -
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. -
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
- Run
mvn clean install
from the root of the project directory. - There are two ways to execute the use-cases:
-
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.
- Go to
-
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
- Run
-
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 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.