Consumer Product Enrollment Reference Application

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Access to sandbox
  • Onboarding and configuration
  • Integrating with Open API Generator
  • Build and Execute
• Use Cases
• API Reference
  • Authorization
  • Request Examples
• Support

Overview

The Consumer Product Enrollment(CPE) API was formerly the Bundle Profile API.

This is a product enrollment service that allows a user to enroll with Mastercard solutions. The Mastercard solutions are preconfigured bundles comprised of multiple products and services. This API user enables the simultaneous user enrollment into the products within the solutions using optional consents and payment card accounts, and also provides the ability to optionally store consumer information with Mastercard Consumer Lifecycle Services domain.

Consumer Product Enrollment enables:

• New consumer enrollment into products and solutions
• View and update consumer enrollment details
• Update the product and solution enrollment details

This Reference application is a guide for using CPE APIs for product and solution enrollments. Please visit Mastercard Developer portal for more details about the API: Mastercard Developers.

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 "MastercardON" API
• A text editor or IDE
• Java 8
• Apache Maven 3.3+

Access to sandbox

The Sandbox environment allows you to experiment with the API using a reference application prior to formal onboarding and adoption of the CPE API.

Onboarding and Configuration

• Clone the project - git clone https://github.com/Mastercard/bundle-client-ref.git.

• Sign up to create a Mastercard Developers account. In case you already have an account, login and follow the below steps.

• Create a new project in your account and add BundleEnablement API to your project.

• Check for the approved status in mastercard Developer portal post which approved client can access the API.

• Configure project and download your sandbox signing keys. It will download a zip file.

• Unzip the downloaded key and select .p12 file(certificate) from zip and copy it to src/main/resources in the project folder.

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

  mastercard.bundle.client.api.base.path=https://sandbox.api.mastercard.com, it is a static field, for making the API calls.

  mastercard.bundle.client.p12.path=BundleProfile.p12, this refers to the p12 file name obtained from the aforementioned steps.

  mastercard.bundle.client.ref.app.consumer.key=Abcdfefgjhilklmnopqrstuvwxyz-dxcq_zD7IiPa0df175e!22a7fddba56e800000000000000000, this refers to your consumer key you obtain when you create a project under API.

  mastercard.bundle.client.ref.app.keystore.password=pwd, this refers to the password you obtain when you create the p12 key.

Integrating with OpenAPI Generator

You may refer to Open API Generator used by "bundle-client-ref" that generates the API client libraries from Open API Specs. It provides generators and library templates for supporting multiple languages and frameworks. (Note: This section is informational and developer who integrates need not perform these steps.)

Also see:

• Open API Generator (maven Plugin)
• CONFIG OPTIONS for java

OpenAPI Generator Plugin Configuration

• maven plugin to build modules from Open API - Generator from the swagger given.

<!-- 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/bundle-profile.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/main/java</sourceFolder>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Build and Execute

Once you have added the correct properties, you are ready to build the application. You can do this by navigating to the project’s base directory from the terminal and then by running the following command.

mvn clean install

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

java -jar target/bundle_client-1.0.0.jar <argument as below> Example: java -jar target/bundle_client-1.0.0.jar createUser

Argument: An argument defines the feature an executor can use to run through the command line. If you don’t specify this argument, it will run all the features (create User, Read User, Update User (product / account)) one after the other. createUser, readUser, etc mentioned below are the arguments.

* createUser - Provides initial enrollment of a user into products and solutions.
* readUser   - Provides read-only view into the enrolled products of a given user.
* addProduct - Adds product enrollment for the user.
* replaceUser - Updates user's personal information across products.
* addAccount - Provides addition of a payment account to a user.
* removeAccount - Removes the payment account tagged with enrolled products. 
* replaceAccount - Update user payment account on all products tied to the existing primary account number.

Use Cases

Case 1: Enroll User

• Provides initial enrollment of a user into products and solutions. This operation is used to complete the first user enrollment.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  /users	POST	BundleUser	BundleUserResponse

Case 2: View Enrolled Products

• Provides read-only view into the enrolled products of a given user. This operation is used to confirm enrollment status in concert with the POST enrollments and PATCH updates.

  URL	Method	Request	Response
  /users/{userid}	GET	NA	BundleUserResponse

Case 3: Add Product

• Adds product enrollment for the user. This operation occurs only after the initial user enrollment (POST) and applies to solution journeys that gradually add product capabilities as the user incrementally interacts with the solution.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  /users/{userid}/patches	POST	BundleUserPatch	BundleUserResponse

Case 4: Update User

• Updates user information across products. This operation is called when a user’s personal information is refreshed as part of a profile update.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  /users/{userid}/patches	POST	BundleUserPatch	BundleUserResponse

Case 5: Add Payment Account

• Provides addition of a payment account to a user. This operation is called when a user’s payment information is refreshed as part of a profile update.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  /users/{userid}/patches	POST	BundleUserPatch	BundleUserResponse

Case 6: Remove Payment Account

• Removes the payment account tagged with enrolled products. This operation is called when a user’s payment information is refreshed as part of a profile update.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  /users/{userid}/patches	POST	BundleUserPatch	BundleUserResponse

Case 7: Replace Payment Account

• Update user payment account on all products tied to the existing primary account number. This operation is called when a user’s payment information is refreshed as part of a profile update.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  /users/{userid}/patches	POST	BundleUserPatch	BundleUserResponse

Case 8: Enroll User

• Provides initial enrollment of a user into Consumer Lifecycle Services. This operation is used to complete the first user enrollment or registration.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users	POST	EnrollmentUser	EnrollmentResponse

Case 9: View User

• Provides retrieval of enrollment details of a user enrolled to Consumer Lifecycle Services.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users/{userid}	GET	NA	EnrollmentUserResponse

Case 10: Remove User

• Provides deletion or removal of a user's enrollment from Consumer Lifecycle Services.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users/{userid}	DELETE	NA	EnrollmentUserResponse

Case 11: Update User

• Provides update capability for enrollment details of a user enrolled to Consumer Lifecycle Services.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users/{userid}	PUT	EnrollmentUser	EnrollmentUserResponse

Case 12: Partially Add User’s Details

• Provides partial update capability of enrollment details by addition of fields for a user enrolled to Consumer Lifecycle Services.

• Allows addition of user data without requiring other enrollment details to be passed in the request.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users/{userid}	PATCH	DiscretePatchesRequest	EnrollmentUserResponse

Case 13: Partially Revise User’s Details

• Provides partial update capability of enrollment details by replacing field values for a user enrolled to Consumer Lifecycle Services.

• Allows replacing of user data without requiring other enrollment details to be passed in the request.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users/{userid}	PATCH	DiscretePatchesRequest	EnrollmentUserResponse

Case 14: Partally Remove User’s Details

• Provides partial update capability of enrollment details by removing field values for a user enrolled to Consumer Lifecycle Services.

• Allows removal of user data without requiring other enrollment details to be passed in the request.

• For field level information, refer to model classes.

  URL	Method	Request	Response
  enrollment/users/{userid}	PATCH	DiscretePatchesRequest	EnrollmentUserResponse

Authorization

For configuring your API client, the com.mastercard.developer.interceptors package provides you some request interceptor classes. 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 the src/main/resources/templates for POST and UPDATE Use case. {userid} field is editable in the RequestHelper.java class. Below are the static User ID values configured for the Consumer Product Enrollment Reference Application. You may pass the below User IDs for GET operation to retrieve information on user’s enrolled products.

• For Products (airport, Wi-Fi), User ID - user234 is supported
• For Products (rewards, benefits, offers), User ID - user1235 is supported
• For Product: specialpay (Note: This is a test product), User ID - specialpayUser is supported

Support

For any clarifications, please reach out to [email protected].