{"id":28577473,"url":"https://github.com/mastercard/transaction-api-reference-app","last_synced_at":"2025-06-11T00:38:49.231Z","repository":{"id":95408408,"uuid":"556923324","full_name":"Mastercard/transaction-api-reference-app","owner":"Mastercard","description":"Demonstrates how the Mastercard Transaction API for Acquirers can be used for the supported operations to request and reply to transaction authorization, reversal, account inquiry, and financial clearing messages without needing a legacy MIP or edge device.","archived":false,"fork":false,"pushed_at":"2025-02-17T10:45:29.000Z","size":953,"stargazers_count":5,"open_issues_count":3,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-17T11:33:27.734Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2022-10-24T19:17:49.000Z","updated_at":"2025-02-17T10:45:25.000Z","dependencies_parsed_at":"2023-12-22T10:41:54.233Z","dependency_job_id":"abd55290-38ff-4637-8664-5703b66b7344","html_url":"https://github.com/Mastercard/transaction-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%2Ftransaction-api-reference-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Ftransaction-api-reference-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Ftransaction-api-reference-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Ftransaction-api-reference-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/transaction-api-reference-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Ftransaction-api-reference-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177332,"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:37:51.290Z","updated_at":"2025-06-11T00:38:49.211Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reference Implementation for Mastercard Transaction APIs for Acquirers\n\n[![](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/Mastercard/transaction-api-reference/blob/master/LICENSE)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_transaction-api-reference-app\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Mastercard_transaction-api-reference-app)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_transaction-api-reference-app\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=Mastercard_transaction-api-reference-app)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_transaction-api-reference-app\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Mastercard_transaction-api-reference-app)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_transaction-api-reference-app\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Mastercard_transaction-api-reference-app)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Mastercard_transaction-api-reference-app\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=Mastercard_transaction-api-reference-app)\n\n## Table of Contents\n- [Project Overview](#overview)\n    * [Compatibility](#compatibility)\n- [Usage](#usage)\n    * [Prerequisites](#prerequisites)\n    * [Security \u0026 Authentication](#security-and-authentication)\n- [Before You Start: Getting MTLS Client Certificates for Your Project](#before-you-start-getting-mtls-client-certificates-for-your-project)\n    * [Client Certificates and Environments](#client-certificates-and-environments)\n    * [Creating and Renewing Client Certificate](#creating-and-renewing-client-certificate)\n    * [Step-by-Step Guide on Requesting a Certificate](#step-by-step-guide-on-requesting-a-certificate)\n    * [Download the appropriate Client Certificate](#download-the-appropriate-client-certificate)\n    * [Configuration](#configuration)\n    * [Working with JKS instead of PKCS12](#working-with-jks-instead-of-pkcs12)\n- [Build and Execute](#build-and-execute)\n- [API Reference](#api-reference)\n- [About This Project](#about-this-project)\n  * [Integrating with OpenAPI Generator](#integrating-with-openapi-generator)\n- [Support](#support)\n- [License](#license)\n\n## Project Overview \u003ca name=\"overview\"\u003e\u003c/a\u003e\nThis is a reference application to demonstrate how the Mastercard Transaction API for Acquirers can be used for the supported operations. Please see here for details on the API: [Mastercard Developers](https://developer.mastercard.com/transaction-api-for-acquirers/documentation/). To call this API, a valid _Client Certificate_ file must be acquired and access provisioned as explained later in this documentation.\n\n### Compatibility \u003ca name=\"compatibility\"\u003e\u003c/a\u003e\n* [Java 11](http://www.oracle.com/technetwork/java/javase/downloads/index.html) or later\n\n## Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\n### Prerequisites \u003ca name=\"prerequisites\"\u003e\u003c/a\u003e\n* [Mastercard Developers Account](https://developer.mastercard.com/dashboard) with access to the Mastercard Transaction API for Acquirers\n* A text editor or IDE\n* [Spring Boot 2.7+](https://spring.io/projects/spring-boot)\n* [Apache Maven 3.3+](https://maven.apache.org/download.cgi)\n* Set up the `JAVA_HOME` environment variable to match the location of your Java installation.\n\n### Security and Authentication \u003ca name=\"security-and-authentication\"\u003e\u003c/a\u003e\n* [Using MTLS to access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-mtls-to-access-mastercard-apis/)\n\n## Before You Start: Getting MTLS Client Certificates for Your Project \u003ca name=\"before-you-start-getting-mtls-client-certificates-for-your-project\"\u003e\u003c/a\u003e\nThe client authentication side of the MTLS protocol involves a client certificate, a public key and a private key, known as a key pair. To use the key pair with Mastercard APIs, you will need to perform the onboarding steps detailed here.\n\n### Client Certificates and Environments \u003ca name=\"client-certificates-and-environments\"\u003e\u003c/a\u003e\nThere are two different types of MTLS client certificates, depending on the stage of your project:\n\n1. Sandbox MTLS certificates, which give access to an API sandbox that mimics a live Production environment (mtf.api.mastercard.net)\n2. Production MLTS certificates, which allow an application to access the Production environment (api.mastercard.net)\n*Domain/Server URL may vary depending on the API. Please check the API Reference section of the service documentation for the correct server URL.*\n\n### Creating and Renewing Client Certificate \u003ca name=\"creating-and-renewing-client-certificate\"\u003e\u003c/a\u003e\nThe [Key Management Portal (KMP)](https://www.mastercardconnect.com/-/store-plus/item-details/A/ckmp) is an application available in [Mastercard Connect](https://www.mastercardconnect.com/). KMP is a self-service portal for Mastercard customers, which allows them to request and exchange keys and certificates with Mastercard.\n\nThe portal provides guided workflows to create and manage requests for key and certificate exchange, as well as an inventory of all PKI for Business Partners keys and certificates that have been exchanged between Mastercard and customers using KMP.\n\nAccess the Key Management Portal application on [Mastercard Connect](https://www.mastercardconnect.com/) to obtain MTLS client certificates. You can access the user guide within the KMP application for instructions on how to use the application.\n\n### Step-by-Step Guide on Requesting a Certificate \u003ca name=\"step-by-step-guide-on-requesting-a-certificate\"\u003e\u003c/a\u003e\nVisit the [Mastercard Transaction APIs for Acquirers Tutorials \u0026 Guides](https://developer.mastercard.com/transaction-api-for-acquirers/documentation/tutorials-and-guides/) for a step-by-step guide on requesting an MTLS Certificate.\n\n### Download the appropriate Client Certificate \u003ca name=\"download-the-appropriate-client-certificate\"\u003e\u003c/a\u003e\nOnce you are notified that your Certificate Request is signed, you can access the client certificate in KMP.\n\nWhen accessing your certificate, you will see an option to download the certificate. Ensure that the following options are selected:\n\n1. Format PKCS #8\n2. Uncheck “Include Root Chain”\nThe certificate will be available to download. Save it to a safe location so that it can be uploaded to your project in Mastercard Developers or used within your client's run command.\n\n### Configuration \u003ca name=\"configuration\"\u003e\u003c/a\u003e\nWith the PKCS12 file downloaded from [KMP](https://www.mastercardconnect.com/-/store-plus/item-details/A/ckmp), configure the properties for your client application as explained below - \n\n* Open `${project.basedir}/src/main/resources/application.properties` and configure the below properties.\n\n  **The below properties will be required for authentication of API calls.**\n\n  \u003e**transaction-api.ssl.key-store**, this refers to the .p12 file with the signing key. Please place the .p12 file in the project folder and update this property with the name of the file.\n  \u003e If the key file is not present, you will receive this error:\n  \u003e ```markdown\n  \u003e java.io.FileNotFoundException: key.p12 (No such file or directory)\n  \n  \u003e**transaction-api.ssl.key-store-type**, for .p12 files, this is \"PKCS12\" (without quotes)\n  \n  \u003e**transaction-api.ssl.key-store-password**, this is the password for the .p12 file. If it is modified, use what was identified when creating CSR on [KMP](https://www.mastercardconnect.com/-/store-plus/item-details/A/ckmp)\n\n### Working with JKS instead of PKCS12 \u003ca name=\"working-with-jks-instead-of-pkcs12\"\u003e\u003c/a\u003e\n* If you received a different format of key file, change the property **transaction-api.ssl.key-store-type** accordingly. For example, provide **transaction-api.ssl.key-store-type=JKS** if you received the JKS file.\n* Alternatively you can convert that to `.p12` using the following command (provide input where necessary).\n```bash\nkeytool -importkeystore -srckeystore \u003cjks-file-location\u003e \\\n-destkeystore \u003cpkcs12-file-location\u003e \\\n-srcstoretype JKS \\\n-deststoretype PKCS12 \\\n-deststorepass \u003ckeystore-password\u003e\n```\n\n\n## Build and Execute \u003ca name=\"build-and-execute\"\u003e\u003c/a\u003e\nOnce you’ve added the correct properties, we can build the application. We can do this by navigating to the project’s base directory from the terminal and running the following command:\n\n`mvn clean install`\n\nWhen the project builds successfully you can then run the following command to start the project:\n\n```bash\njava -jar target/transaction-api-reference-application-2.0.0.jar\n```\n*** Note: the default environment is - `https://mtf.api.mastercard.net/transaction-api` ***\n\nSee also:\n* [OpenAPI Generator (Plugin for Maven)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin)\n* [OpenAPI Generator (executable)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-cli)\n* [CONFIG OPTIONS for Java](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/java.md)\n\n## API Reference \u003ca name=\"api-reference\"\u003e\u003c/a\u003e\nPlease consult the API documentation at the [API Reference](https://developer.mastercard.com/transaction-api-for-acquirers/documentation/api-reference/) page.\n\nThe OpenAPI specification file is also included in the project as `${project.basedir}/src/main/resources/transaction-api-openapi.yaml`.\n\nNote that the sample requests included in this project are for demo purposes only.\nPlease modify for your use cases and change to valid values before running this application.\n\n## About this Project \u003ca name=\"about-this-project\"\u003e\u003c/a\u003e\nThis project was created using the `OpenAPI Generator` for generating API client and SDK libraries, server stubs, documentation and configuration.\n\n### Integrating with the OpenAPI Generator \u003ca name=\"integrating-with-openapi-generator\"\u003e\u003c/a\u003e\n[The OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification).\nIt provides generators and library templates for supporting multiple languages and frameworks.\n\n## Support \u003ca name=\"support\"\u003e\u003c/a\u003e\nIf you would like further information, please send an email to apisupport@mastercard.com.\n\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\nCopyright 2022 Mastercard\n\nLicensed 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:\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\nUnless 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Ftransaction-api-reference-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Ftransaction-api-reference-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Ftransaction-api-reference-app/lists"}