# SOAP Reference Application Tutorial source: https://developer.mastercard.com/iccp/documentation/ref_app_tutorials/reference-application/index.md Execute the end to end flow of the In Control for Commercial Payments (ICCP) API using a Java application. The reference application creates purchase requests, adds invoice addenda records, and creates and retrieves reports for a virtual card number (VCN). You will also run tests to understand how each API call is structured and analyse the responses received for various tasks performed by the ICCP API. ## Tests and Supporting Classes {#tests-and-supporting-classes} | Type | Tasks Performed | |-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Setup Test | Verifies that your consumer key, certificate file and other settings are configured correctly, and you can connect to sandbox financial endpoint to make a request and receive a response. | | CreatePurchaseRequest class | * This is a base class for tests to call to create purchase requests, which generates a VCN and a purchase request ID that tests use to make subsequent calls. * The test classes inherit the submitPurchaseRequest method from the CreatePurchaseRequest class, which submits a Purchase Request (generates a VCN), and verifies that the purchase request was created successfully. * The submitPurchaseRequest method returns the details of the purchase request in the response. | | Purchase Request Test | * Creates a purchase request, which generates a VCN and then: * Gets the purchase request details. * Updates the purchase request details with a new description. * Emails the card image to the supplier. * Creates a new purchase request and cancels that purchase request and the associated VCN. | | Reports Test | Creates a VCN and then requests authorization and clearing reports on the VCN spending. | | Addenda Test | Creates a VCN and: * Adds invoice addenda records to the purchase request to aid reconciliation of the resulting payments. * Updates the details of existing invoice addenda records. * Deletes invoice addenda records. | ## Prerequisites {#prerequisites} Meet all prerequisites to successfully execute the reference application. 1. Working installations of the softwares: 2. Java 8 or 11 3. Maven 3 to build your application and to download dependencies 4. Optionally, an Integrated Development Environment (IDE) of your choice 5. Your Maven environment has permissions either locally or to a remote repository to download the open source libraries: * Mastercard Developer OAuth Signer v1.2.4 * OKHttp v4.2.2 * Junit v5.5.2 * jackson-core v2.10.1 * Assert-j v3.14.0 6. Ensure your Mastercard administrator has completed the setup provided in the [API Basics](https://developer.mastercard.com/iccp/documentation/api_basics/soap_api_basics/index.md#setting-up-your-configuration-in-iccp) section. * The tests require a purchase template configured with velocity and validity controls to pass. ## Step 1: Prepare the reference application {#step-1-prepare-the-reference-application} 1. To download, click [sd-commercial-iccp-openapi-java-client.zip](https://static.developer.mastercard.com/content/iccp/uploads/sd-commercial-iccp-openapi-java-client.zip) (56KB). 2. Extract the downloaded zip file to a folder of your choice. ## Step 2: Get credentials {#step-2-get-credentials} Get a consumer key and a sandbox.p12 file so that the ICCP API can authorize your API requests. To get credentials: 1. Complete the [Quick Start Guide](https://developer.mastercard.com/iccp/documentation/quick-start-guide/index.md) procedure to obtain a sandbox consumer key and a keystore file. 2. Go to the `[extracted-folder]/src/resources` location and add the *PKCS#12 keystore* file. 3. Share your consumer key with your Mastercard Representative and receive a confirmation that the key has been configured in the ICCP system. The tests will fail if your details are not configured in the ICCP system. ## Step 3: Update properties {#step-3-update-properties} Before running the tests, update the configuration properties with your credentials and an email address. To update properties: 1. Go to the `[extracted-folder]/src/test/java/com/mastercard/sd/utils` location and open the config.java file. 2. Update the following properties: | Properties | Description | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | consumerKey | Update the consumer key from [#Step 2](https://developer.mastercard.com/iccp/documentation/ref_app_tutorials/reference-application/index.md#step-2-get-credentials) | | signingKeyFilePath | Location of the keystore file from [#Step 2](https://developer.mastercard.com/iccp/documentation/ref_app_tutorials/reference-application/index.md#step-2-get-credentials) | | supplierEmail | Email address to receive the VCN details | ## Step 4: Build the Reference Application {#step-4-build-the-reference-application} To build the reference application: 1. Navigate to the folder where you extracted the reference application. 2. Import the extracted folder into your IDE with the pom file as the base for the project. OR, use Maven at the command line from the directory that has the project pom.xml file. 3. Run a Maven clean install of the project either through your IDE or by running `mvn clean install` from the command line to: * Generate the required classes from the WSDL and XSD files located at the `~/src/test/resources/wsdl` path. * Download the required dependencies listed in the [prerequisites](https://developer.mastercard.com/iccp/documentation/ref_app_tutorials/reference-application/index.md#prerequisites) section. * Build the application to run the tests. ## Step 5: Run the Tests {#step-5-run-the-tests} Run the `SetupTest` before running other tests to ensure the credentials are working as expected. This test retrieves the data source details attached to your consumer key including the `dataSourceId`. 1. Either run `SetupTest` directly in your IDE or navigate to the root project file and execute the command `mvn test -Dtest=com.mastercard.sd.SetupTest`. 2. After the `SetupTest` is completed successfully, right-click the `src` package and select `run → all` tests in your IDE or execute the command `mvn test`. The tests can also be run individually. ## Recap and Next Steps {#recap-and-next-steps} After completing this tutorial, you should have: * Gained access to a Mastercard sandbox environment. * Built the ICCP reference application and configured it for your environment. * Analyzed the construction of the ICCP API calls and their responses. * Ran all the application tests and made the ICCP API calls to perform various tasks. Next, you can create your own application using this reference application as a base.