https://github.com/mastercard/installments-bnpl-api-reference-app
Installments BNPL API Reference App
https://github.com/mastercard/installments-bnpl-api-reference-app
Last synced: about 1 year ago
JSON representation
Installments BNPL API Reference App
- Host: GitHub
- URL: https://github.com/mastercard/installments-bnpl-api-reference-app
- Owner: Mastercard
- License: apache-2.0
- Created: 2022-08-10T08:56:33.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-11T09:05:02.000Z (over 2 years ago)
- Last Synced: 2024-04-16T10:43:16.145Z (over 2 years ago)
- Language: Java
- Homepage:
- Size: 163 KB
- Stars: 2
- Watchers: 7
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Mastercard Installments Reference App
[](https://sonarcloud.io/summary/new_code?id=Mastercard_installments-bnpl-api-reference-app)
[](https://sonarcloud.io/summary/new_code?id=Mastercard_installments-bnpl-api-reference-app)
[](https://sonarcloud.io/summary/new_code?id=Mastercard_installments-bnpl-api-reference-app)
[](https://github.com/Mastercard/installments-bnpl-api-reference-app/blob/main/LICENSE)
## Table of Contents
- [Overview](#overview)
- [Requirements](#requirements)
- [Frameworks/Libraries](#frameworks)
- [Integrating with OpenAPI Generator](#OpenAPI_Generator)
- [Configuration](#configuration)
- [Use-Cases](#use-cases)
- [Execute the Use-Cases](#execute-the-use-cases)
- [Service Documentation](#documentation)
- [API Reference](#api-reference)
- [Support](#support)
- [License](#license)
## Overview
This is a reference application to demonstrate how Mastercard Installment APIs can be used.
To call the API, consumer key and .p12 file are required from your project on Mastercard Developers.
- 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](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) to know more about how to generate a simple API client for consuming APIs.
## Encryption and Decryption
The [Mastercard Encryption Library](https://github.com/Mastercard/client-encryption-java) provides interceptor class that you can use when configuring your API client. This class will take care of encrypting payload before sending the request and decrypting payload after receiving the response.
#### Loading Encryption Certificate
A `Certificate` object can be created from a file by calling `EncryptionUtils.loadEncryptionCertificate`:
```java
Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate("");
```
Supported certificate formats: PEM
##### From a PKCS#12 Key Store
A `PrivateKey` object can be created from a PKCS#12 key store by calling `EncryptionUtils.loadDecryptionKey` the following way:
```java
PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(
"",
"",
"");
```
## Configuring JWE Instance
```java
JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
.withEncryptionCertificate(encryptionCertificate)
.withDecryptionKey(decryptionKey)
.withEncryptionPath("$", "$")
.withDecryptionPath("$.consumer.encryptedData", "$.consumer")
.withEncryptedValueFieldName("cipher")
.build();
```
## Configuration
1. Create Your Account On [Mastercard Developers](https://developer.mastercard.com/) If You Don't Have Account Click On Create New Account.
2. Create A New Project Here & Add ***Mastercard Installments API*** To It & Click Continue.
3. Download Sandbox Signing Key, A ```.zip``` File Will Get Downloaded Click On Continue.
4. Create Encryption Keys - Mastercard Installments API - Sandbox Enter Keyalias & Password Of Your Choice, Note Down This Details You Will Need Them To Configure In Further Steps
5. Confirm Your Keystore Credentials Are Saved : Click on Confirm & Continue ```key-encryption-mc.p12``` File Will Get Downloaded
6. Extract The ```.zip``` File Downloaded In Step 3 & Copy The ```.p12``` From Extracted Folder Into ```src/main/resource```
7. Copy The Downloaded ```keyalias-encryption-mc.p12``` File To ```src/main/resource``` Folder
8. Go to My Project Section Click On Your Newly Created Project Click On ```Actions``` Under ```Client Encryption``` Section Click on Download Encryption Key ```.pem``` File Will Be Downloaded.
9. Copy The Downloaded ```.pem``` File To ```src/main/resources```.
10. Open ```src/main/resources/application.yml``` & Configure:
- ```mastercard.api.environment.base-path ``` - Refers To Sandbox Endpoint, It's A Static Field, Will Be Used As A Host To Make API Calls.
**Below properties will be required for authentication of API calls.**
- ```mastercard.api.authentication.key-file ``` - path to keystore (.p12) file, just change the name as per the downloaded file in step 3.
- ```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 a sandbox is ```keyalias```.
- ```mastercard.api.authentication.keystore-password``` - password of your Keystore. Default keystore password for sandbox project is ```keystorepassword```.
**Below properties will be required to encrypt and decrypt the request and response payloads**
- ```mastercard.api.encryption.key-file``` - Client Encryption File just change the name downloaded in step 9 ```client-encryption.pem```(this step will be used for approvals api).
- ```mastercard.api.decryption.key-file``` - Mastercard encryption key File name downloaded in step 7 ```keyalias-encryption-mc.p12```(this step will be used for plans api).
- ```mastercard.api.decryption.keystore-alias``` - alias of your mastercard encryption key set up by you in step 4 . ```keyalias```.
- ```mastercard.api.decryption.keystore-password``` - password of your mastercard encryption key set up by you in step 4.```keystorepassword```.
## Use-Cases
1. **Merchant Participation**
Provides ability for Acquirers to submit details on participating and non-participating MID merchants with mastercard installments. Also Acquirers will have ability to retrieve the effectuating status of the details shared with mastercard. IPP will have ability to retrieve MAID/MID based merchants participating information by territory with mastercard installments.
**Note**: For PII countries(like GBR) where we need to pass the JWE encrypted payload to Merchant Participation APIs, this reference app has capability to do JWE encryption before sending the request. If we are directly calling API, one may need to explicitly encrypt and send the request(Refer MerchantParticipationInterceptor class).
2. **Approvals API**
The approvals should be completed within 24 hours of initiation.
3. **Plans API**
Provides "get plan" capability to retrieve information about the consumer and merchant.
This operation returns a BNPL installment plan based on selected plan id provided in the request.
The API response contains an encrypted value for the Consumer object,
and the issuer needs to decrypt the response using Mastercard client encryption key.
More details can be found [here](https://developer.mastercard.com/installments-for-bnpl/documentation/use-cases/).
## 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/installments/bnpl/reference/application/controller/``` folder.
- Execute the test case.
2. Use REST API based Client (such as [Insomnia](https://insomnia.rest/download/core/) or [Postman](https://www.postman.com/downloads/))
- Run ```mvn spring-boot:run``` command to run the application.
- Use any REST API based Client to test the functionality. Below is the API exposed by this application:
- GET /demo/merchants-participations
- POST /demo/merchants-participations
- POST /demo/merchants/mids/searches
- POST /demo/approvals?sync=true
- POST /demo/approvals?sync=false
- GET /demo/approvals/{plan_id}
- GET /plans/{plan_id}
Mastercard Installments documentation can be found [here](https://developer.mastercard.com/installments-for-bnpl/documentation/).
## API Reference
The Swagger API specification can be found [here](https://developer.mastercard.com/installments-for-bnpl/documentation/api-reference/).
## Support
Please send an email to **apisupport@mastercard.com** with any questions or feedback you may have.
Copyright 2024 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.