Reference Implementation for Mastercard Biller Management Service

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Configuration
  • Integrating with OpenAPI Generator
  • Build and Execute
  • Install as Dependency
• Use Cases
• API Reference
  • Authorization
  • Request Examples
  • Request and Response Models
  • Recommendation
• Author
• Support
• License

Overview

This is a reference application to demonstrate how Biller Management API can be used for the supported operations. Please see here for details on the API: Mastercard Developers. This application illustrates connecting to the Biller Management API. To call these APIs, consumer key and .p12 files are required from your Mastercard Developers project.

Compatibility

• Java 8 or later

References

• Mastercard’s OAuth Signer library
• Using OAuth 1.0a to Access Mastercard APIs

Usage

Prerequisites

• Mastercard Developers Account with access to Biller Management API
• A text editor or IDE
• Spring Boot 2.2+
• Apache Maven 3.3+
• Set up the JAVA_HOME environment variable to match the location of your Java installation.

Configuration

• Create an account at Mastercard Developers.

• Create a new project and add Biller Management API to your project.

• Configure project and download signing key. It will download the zip file.

• Select .p12 files from zip and copy it to src/main/resources in the project folder.

• Open ${project.basedir}/src/main/resources/application.properties and configure below parameters.

• Update the following keys in application.properties file.

  • mastercard.api.consumer-key: This can be found in the project you created on developerZone
  • mastercard.api.key-file: Path where you saved your certs i.e., .p12 file you received while creating a project
  • mastercard.api.keystore-password: This is the password you get with Sandbox cert.
  • mastercard.api.keystore-alias: This is the alias you get with Sandbox cert.

• Example:

	mastercard.benefits.ref.app.url=https://sandbox.api.mastercard.com/billpay-exchange/biller-management
	mastercard.api.consumer-key=Abcdfefgjhilklmnopqrstuvwxyz-dxcq_zD7IiPa0df175e!22a7fddba5
	mastercard.api.key-file=C:\path\provided.p12
	mastercard.api.keystore-password=pwd
	mastercard.api.keystore-alias=alias

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.

See also:

• OpenAPI Generator (maven Plugin)
• OpenAPI Generator (executable)
• CONFIG OPTIONS for java

OpenAPI Generator Plugin Configuration

<!-- https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin -->
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi-generator.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/biller-management-service.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

For more information on how this client generator works please consult the official Github repository

Generating The API Client Sources

Now that you have all the dependencies you need, you can generate the sources. To do this, use one of the following two methods:

Using IDE

• Method 1
  In IntelliJ IDEA, open the Maven window (View > Tool Windows > Maven). Click the icons Reimport All Maven Projects and Generate Sources and Update Folders for All Projects

• Method 2
  In the same menu, navigate to the commands ({Project name} > Lifecycle), select clean and compile then click the icon Run Maven Build.

Using Terminal

• Navigate to the root directory of the project within a terminal window and execute mvn clean compile command.

Build and Execute

Once 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

mvn clean install

When the project builds successfully you can then run the following command to start the project

java -jar target/biller-management-client-1.0.0.jar

Install as Dependency

To use this API client as dependency library in your own project:

• Maven users
  Add this dependency to your project's POM:

  <dependency>
    <groupId>com.mastercard.developer</groupId>
    <artifactId>biller-management-client</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
  </dependency>

• Gradle users
  Add this dependency to your project's build file:

  compile "org.openapitools:biller-management-client:1.0.0"

• Others
  At first generate the JAR by executing:

  mvn clean package

  Then manually install the following JARs:

  • target/biller-management-client-1.0.0.jar
  • target/lib/*.jar

Use Cases

Case 1: Onboard new Billers

• Biller Service Providers (BSP) can add their new billers into Billpay Exchange via the Biller Management API.
• Sample request payload can be found: Add Billers
• Request "action" field will be "add"
• Command line examples java -jar target/biller-management-client-1.0.0.jar Add.

Case 2: Edit Existing Billers

• Biller Service Providers (BSP) can edit billers that belong to their profile via the Biller Management API.
• Sample request payload can be found: Update Billers
• Request "action" field will be "update"
• Command line examples java -jar target/biller-management-client-1.0.0.jar Update.

Case 3: Deactivate Existing Billers

• Biller Service Providers (BSP) can deactivate billers that belong to their profile via the Biller Management API.
• Sample request payload can be found: Deactivate Billers
• Request "action" field will be "deactivate"
• Command line examples java -jar target/biller-management-client-1.0.0.jar Deactivate.

Case 4: Multiple Biller Changes

• Biller Service Providers (BSP) can add, update and deactivate billers that belong to their profile in single request via the Biller Management API.
• Sample request payload can be found: Multiple Billers
• Request "action" field value varies
• Command line examples java -jar target/biller-management-client-1.0.0.jar. No args needed.

Case 5: Error Handling

• The operation can fail for various reasons like formatting, field length exceeds, etc.
• This use case just shows one of the example of such failures.
• For the complete list of application specific error codes, refer to Application Error Codes.
• Also refer to model class Errors for field level information.

API Reference

To develop a client application that consumes a RESTful Biller Management API with Spring Boot, refer below documentation.

Class	URL Endpoint	HTTP Method	Request	Response	Description
BillerManagementControllerApi	/billers	POST	BillerManagementRequest	BillerManagementResponse	Add, edit or deactivate one or multiple Billers in Biller Pay Exchange

Authorization

The com.mastercard.developer.interceptors package will provide you with some request interceptor classes you can use when configuring your API client. These classes will take care of adding the correct Authorization header before sending the request.

Request Examples

You can change the default input passed to APIs, modify values in following files,

• Add Billers
• Update Billers
• Deactivate Billers
• Multiple Billers

Request and Response Models

• BillerManagementRequest
• BillerManagementResponse
• CardPaymentModel
• ConsumerAuthenticationModel
• ConvenienceFeeModel
• DeactivationModel
• ErrorDetail
• Errors
• ErrorsList
• GeneralModel
• ServiceAreaModel
• ServiceRelationshipModel
• UserErrorModel

Recommendation

It is recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

Bill_Pay_Development_Support@mastercard.com

Support

If you would like further information, please send an email to apisupport@mastercard.com

License

Copyright 2020 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.