{"id":28577643,"url":"https://github.com/mastercard/installments-bnpl-api-reference-app","last_synced_at":"2025-06-11T00:39:03.302Z","repository":{"id":55885857,"uuid":"523270368","full_name":"Mastercard/installments-bnpl-api-reference-app","owner":"Mastercard","description":"Installments BNPL API Reference App","archived":false,"fork":false,"pushed_at":"2024-04-11T09:05:02.000Z","size":167,"stargazers_count":2,"open_issues_count":2,"forks_count":12,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-04-16T10:43:16.145Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mastercard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-08-10T08:56:33.000Z","updated_at":"2022-12-19T01:05:10.000Z","dependencies_parsed_at":"2024-04-11T10:26:18.732Z","dependency_job_id":"0f3815b0-23b0-4687-b637-e0ef89eef774","html_url":"https://github.com/Mastercard/installments-bnpl-api-reference-app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Finstallments-bnpl-api-reference-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Finstallments-bnpl-api-reference-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Finstallments-bnpl-api-reference-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Finstallments-bnpl-api-reference-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/installments-bnpl-api-reference-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Finstallments-bnpl-api-reference-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177341,"owners_count":22817349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-11T00:38:47.558Z","updated_at":"2025-06-11T00:39:03.281Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mastercard Installments Reference App\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_installments-bnpl-api-reference-app\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Mastercard_installments-bnpl-api-reference-app)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_installments-bnpl-api-reference-app\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=Mastercard_installments-bnpl-api-reference-app)\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_installments-bnpl-api-reference-app\u0026metric=code_smells)](https://sonarcloud.io/summary/new_code?id=Mastercard_installments-bnpl-api-reference-app)\n[![](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/Mastercard/installments-bnpl-api-reference-app/blob/main/LICENSE)\n## Table of Contents\n- [Overview](#overview)\n- [Requirements](#requirements)\n- [Frameworks/Libraries](#frameworks)\n- [Integrating with OpenAPI Generator](#OpenAPI_Generator)\n- [Configuration](#configuration)\n- [Use-Cases](#use-cases)\n- [Execute the Use-Cases](#execute-the-use-cases)\n- [Service Documentation](#documentation)\n- [API Reference](#api-reference)\n- [Support](#support)\n- [License](#license)\n\n## Overview  \u003ca name=\"overview\"\u003e\u003c/a\u003e\nThis is a reference application to demonstrate how Mastercard Installment APIs can be used.\nTo call the API, consumer key and .p12 file are required from your project on Mastercard Developers.\n\n## Requirements  \u003ca name=\"requirements\"\u003e\u003c/a\u003e\n\n- Java 11\n- IntelliJ IDEA (or any other IDE)\n\n## Frameworks/Libraries \u003ca name=\"frameworks\"\u003e\u003c/a\u003e\n- Spring Boot\n- Apache Maven\n- OpenAPI Generator\n\n## Integrating with OpenAPI Generator \u003ca name=\"OpenAPI_Generator\"\u003e\u003c/a\u003e\n\nOpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.  \nCheck [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.\u003c/a\u003e\n\n## Encryption and Decryption\u003c/a\u003e\nThe [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.\n\n#### Loading Encryption Certificate \u003ca name=\"loading-encryption-certificate\"\u003e\u003c/a\u003e\n\nA `Certificate` object can be created from a file by calling `EncryptionUtils.loadEncryptionCertificate`:\n```java\nCertificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(\"\u003cinsert certificate file path\u003e\");\n```\nSupported certificate formats: PEM\n\n#### Loading Decryption Key \u003ca name=\"loading-decryption-key\"\u003e\u003c/a\u003e\n\n##### From a PKCS#12 Key Store\n\nA `PrivateKey` object can be created from a PKCS#12 key store by calling `EncryptionUtils.loadDecryptionKey` the following way:\n```java\nPrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(\n                                    \"\u003cinsert PKCS#12 key file path\u003e\", \n                                    \"\u003cinsert key alias\u003e\", \n                                    \"\u003cinsert key password\u003e\");\n```\n## Configuring JWE Instance \u003c/a\u003e\n```java\nJweConfig config = JweConfigBuilder.aJweEncryptionConfig()\n                                       .withEncryptionCertificate(encryptionCertificate)\n                                       .withDecryptionKey(decryptionKey)\n                                       .withEncryptionPath(\"$\", \"$\")\n                                       .withDecryptionPath(\"$.consumer.encryptedData\", \"$.consumer\")\n                                       .withEncryptedValueFieldName(\"cipher\")\n                                       .build();\n```\n## Configuration \u003ca name=\"configuration\"\u003e\u003c/a\u003e\n1. Create Your Account On [Mastercard Developers](https://developer.mastercard.com/) If You Don't Have Account Click On Create New Account.\n2. Create A New Project Here \u0026 Add ***Mastercard Installments API*** To It \u0026 Click Continue.\n3. Download Sandbox Signing Key, A ```.zip``` File Will Get Downloaded Click On Continue.\n4. Create Encryption Keys - Mastercard Installments API - Sandbox Enter Keyalias \u0026 Password Of Your Choice, Note Down This Details You Will Need Them To Configure In Further Steps\n5. Confirm Your Keystore Credentials Are Saved : Click on Confirm \u0026 Continue ```key-encryption-mc.p12``` File Will Get Downloaded\n6. Extract The ```.zip``` File Downloaded In Step 3 \u0026 Copy The ```.p12``` From Extracted Folder Into ```src/main/resource```\n7. Copy The Downloaded ```keyalias-encryption-mc.p12``` File To ```src/main/resource``` Folder\n8. 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.\n9. Copy The Downloaded ```.pem``` File To ```src/main/resources```.\n10. Open ```src/main/resources/application.yml``` \u0026 Configure:\n       - ```mastercard.api.environment.base-path ``` - Refers To Sandbox Endpoint, It's A Static Field, Will Be Used As A Host To Make API Calls.\n    \n    **Below properties will be required for authentication of API calls.**\n    \n    - ```mastercard.api.authentication.key-file ``` - path to keystore (.p12) file, just change the name as per the downloaded file in step 3. \n    - ```mastercard.api.authentication.consumer-key``` - copy the Consumer key from \"Sandbox/Production Keys\" section on your project page.\n    - ```mastercard.api.authentication.keystore-alias``` - alias of your key. Default key alias for a sandbox is ```keyalias```.\n    - ```mastercard.api.authentication.keystore-password``` - password of your Keystore. Default keystore password for sandbox project is ```keystorepassword```.\n    \n    **Below properties will be required to encrypt and decrypt the request and response payloads**\n    \n    - ```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).\n    - ```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).\n    - ```mastercard.api.decryption.keystore-alias``` - alias of your mastercard encryption key set up by you in step 4 . ```keyalias```.\n    - ```mastercard.api.decryption.keystore-password``` - password of your mastercard encryption key set up by you in step 4.```keystorepassword```.\n\n## Use-Cases \u003ca name=\"use-cases\"\u003e\u003c/a\u003e\n1. **Merchant Participation**   \nProvides 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.\n\n**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).  \n\n2. **Approvals API**   \nThe approvals should be completed within 24 hours of initiation.\n\n3. **Plans API**   \nProvides \"get plan\" capability to retrieve information about the consumer and merchant. \nThis operation returns a BNPL installment plan based on selected plan id provided in the request. \nThe API response contains an encrypted value for the Consumer object, \nand the issuer needs to decrypt the response using Mastercard client encryption key.\n\nMore details can be found [here](https://developer.mastercard.com/installments-for-bnpl/documentation/use-cases/).    \n\n## Execute the Use-Cases   \u003ca name=\"execute-the-use-cases\"\u003e\u003c/a\u003e\n1. Run ```mvn clean install``` from the root of the project directory.\n2. There are two ways to execute the use-cases:\n    1. Execute the use-cases (test cases):  \n        - Go to ```src/test/java/com/mastercard/installments/bnpl/reference/application/controller/``` folder.  \n        - Execute the test case.\n    \n    2. Use REST API based Client (such as [Insomnia](https://insomnia.rest/download/core/) or [Postman](https://www.postman.com/downloads/))  \n        - Run ```mvn spring-boot:run``` command to run the application.  \n        - Use any REST API based Client to test the functionality. Below is the API exposed by this application:       \n\n                - GET \u003cHost\u003e/demo/merchants-participations\n                - POST \u003cHost\u003e/demo/merchants-participations\n                - POST \u003cHost\u003e/demo/merchants/mids/searches\n                - POST \u003cHost\u003e/demo/approvals?sync=true\n                - POST \u003cHost\u003e/demo/approvals?sync=false\n                - GET \u003cHost\u003e/demo/approvals/{plan_id}\n                - GET \u003cHost\u003e/plans/{plan_id}\n\n                                                      \n## Service Documentation \u003ca name=\"documentation\"\u003e\u003c/a\u003e\n\nMastercard Installments documentation can be found [here](https://developer.mastercard.com/installments-for-bnpl/documentation/).  \n\n\n## API Reference \u003ca name=\"api-reference\"\u003e\u003c/a\u003e\nThe Swagger API specification can be found [here](https://developer.mastercard.com/installments-for-bnpl/documentation/api-reference/).  \n\n## Support \u003ca name=\"support\"\u003e\u003c/a\u003e\nPlease send an email to **apisupport@mastercard.com** with any questions or feedback you may have.  \n\n\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\n\u003cp\u003eCopyright 2024 Mastercard\u003c/p\u003e\n\u003cp\u003eLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with\nthe License. You may obtain a copy of the License at:\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e   http://www.apache.org/licenses/LICENSE-2.0\n\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on\nan \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the\nspecific language governing permissions and limitations under the License.\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Finstallments-bnpl-api-reference-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Finstallments-bnpl-api-reference-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Finstallments-bnpl-api-reference-app/lists"}