# Reference Application Tutorial using OAuth1.0A
source: https://developer.mastercard.com/cross-border-services/documentation/ref-app/reference-app-tutorial/index.md

###### \> Time to complete: *20 minutes*

Alert: If you are a Customer contracted with MTS EU or MTS UK, you must connect using [OAuth2.0 Authorization Code flow](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-access-token-based-authentication-details/index.md) for Balance APIs and [OAuth2.0 Request Token based flow](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-request-token-based-authentication-details/index.md) for all APIs (except Balance API) as the authentication mechanism to ensure compliance with the relevant jurisdiction based Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2).   
Please proceed to [the Reference Tutorial for Authorization Code based OAuth2.0](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-reference-app-tutorial-access-token/index.md) and [Reference Tutorial for Request Token based OAuth2.0](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-reference-app-tutorial-request-token/index.md) to learn about connecting to Mastercard Cross-Border Services APIs.

## Introduction {#introduction}

This tutorial demonstrates how a simple web application can use the Cross-Border Service APIs to execute and manage the payment transactions. This includes making API calls with the use of Rest client to the following Cross-Border Service APIs in the sandbox environment:  

[Quotes API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/quotes-api/index.md)   

[Quote Confirmation APIs](https://developer.mastercard.com/cross-border-services/documentation/api-ref/quote-confirmation-apis/index.md)   

[Payment API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/payment-api/index.md)   

[Retrieve Payment API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/retrieve-payment-api/index.md)   

[Carded Rate Pull API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/carded-rate-api/index.md)   

[Cancel Payment API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/cancel-payment-api/index.md)   

[Balance API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/balance-api/index.md)   

[Update Request API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/update-request-api/index.md)   

[Upload Document API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/upload-document-api/index.md)   

[Download Document API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/download-document-api/index.md)   

[Retrieve Request API](https://developer.mastercard.com/cross-border-services/documentation/api-ref/rfi-apis/retrieve-request-api/index.md)   
Note: The application is built for reference purposes only. Feel free to extend this for any other Cross-Border Services APIs as well. Your production application does not need to function the same way.

During this tutorial, you will:

1. Setup the Reference application, you can download repository from [GitHub](https://github.com/Mastercard/crossborder-services-reference-application)
2. Set required keys for authentication
3. Execute use cases

## Step 1: Setting Up {#step-1-setting-up}

### a) Pre-requisites {#a-pre-requisites}

To complete this tutorial, you need:  

* Maven 3.5 or later
* JDK 1.8.0
* IntelliJ IDEA (or any other IDE of your choice)
* [Spring Framework](https://projects.spring.io/spring-framework/) 5.1.x is used to build this application.
* [Mastercard Developers Account](https://developer.mastercard.com/dashboard) with access to Mastercard Cross-Border Services API and the signing keys generated. You would require the .p12 file, consumer key, keyalias and password from this step to proceed with the below steps. (Click [here](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-create-project/index.md) for a step by step guide on account setup.)  

### b) Create a Maven Project {#b-create-a-maven-project}

In IntelliJ IDEA, create a new Maven project from Version control.   

* This will clone repository from GitHub and set up your directory structure automatically.

![clone-repository](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_tutorial_prj_1.png)

* Test connection before going ahead
  ![test-connection](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_tutorial_prj_2.png)

* Clicking on clone will start cloning the repository
  ![click-clone-repo](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_tutorial_prj_3.png)

* At the lower right corner in your IDE, you will be prompted to add this project as a maven Project. **Please add as a Maven project.**
  ![add-as-maven-project](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_tutorial_prj_mvn_4.png)
  You can also view this setting in the event log window, it can be opened from Tool windows in the View menu.  

### c) Add resources {#c-add-resources}

* As part of the [Mastercard Developers Account](https://developer.mastercard.com/dashboard) setup (as described in pre-requisites section above), Sandbox Signing Key will be generated within your project. Add the generated .p12 file to the resources folder.

### d) Update properties file {#d-update-properties-file}

* You can view directory structure of reference application in Project view.
  ![resources-view](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_tutorial_prj_config_1.png)  

* Open mastercard-api.properties in resources folder. This properties file defines default endpoint URL and partner for API calls. It also has some other fields which are required for authentication.

* As part of the [Mastercard Developers Account](https://developer.mastercard.com/dashboard) setup (as described in pre-requisites section above), you will also get the consumer key, keyalias and password. Set these values in mastercard-api.properties.   

* Example

```Example
mastercard.api.authentication.keystore.keyFile=classpath:key.p12

mastercard.api.authentication.consumerKey=YourConsumerKey

mastercard.api.authentication.keystore.keyalias=YourKeyAlias

mastercard.api.authentication.keystore.password=YourKeystorePassword
```

### e) Add dependencies {#e-add-dependencies}

* Open maven view in IDE and run maven clean and install. This will add dependencies to your project.

![project-dependencies](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_prj_maven_upd.png)  

## Step 2: Executing the use cases {#step-2-executing-the-use-cases}

* Open the README.md in the reference application and read through the use cases to understand Cross-Border Service API functionality.   
* To test Quotes API, open QuotesAPITest.java, right click on any of the use case and click on run. It will execute that use case.   
  Please note, input for every use case is setup in CrossBorderAPITestHelper.java. Cross-Border Service APIs supports both XML and Json.

![test-quotes-api](https://static.developer.mastercard.com/content/cross-border-services/documentation/images/ref_app_tutorial_prj_use_case.png)
You may similarly test all the APIs by executing the usecases listed in the respective xxxxTest.java file.  

### ++Encryption and Decryption:++ {#uencryption-and-decryptionu}

* Cross-Border Services application requires payload encryption. To know details about encryption, go through [Enabling encryption](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md). **You may contact [support](mailto:APISupport@mastercard.com) to get required keys and files for the same**   

To encrypt or decrypt request and response payloads, you must set the additional properties in mastercard-api.properties.   
* Example

```Example
mastercard.api.environment.runWithEncryptedPayload=true

mastercard.api.encryption.certificateFile=classpath:YourCertFile.crt 

mastercard.api.encryption.fingerPrint=YourFingerPrint 

mastercard.api.decryption.keyFile=classpath:YourKeyFile.key 

# decryption key file path
mastercard.api.decryption.keyFile=

## decryption key alias - the alias associated with the decryption keyfile
mastercard.api.decryption.keyAlias=

## decryption password - the password associated with the decryption keyfile
mastercard.api.decryption.password=


```

Note:   

**.crt file** must be extracted using the .pem file that can be downloaded from your [Project page](https://developer.mastercard.com/dashboard) by clicking on the project and using the **Actions \> Download Encryption Key** under the Client Encryption Keys section.   

**.key file** is the .p12 file downloaded at time of encryption key creation.

#### Some recommendations: {#some-recommendations}

These are just recommendations. You are not required to use open ssl but may use any favorable tool.

* Creating **.cert file** from **.pem file**:

  * Encryption_cert_generation

  ```Encryption_cert_generation
  openssl x509 -outform der -in ./MastercardSendCrossBorderClientEncxxxxxxxxxx.pem -out ./MastercardSendCrossBorderClientEncxxxxxxxxx.crt

  ```

  <br />

* Decrypting response payload using private key:

* Decryption_key_generation

```Decryption_key_generation
openssl pkcs12 -in keyalias-encryption-mc.p12 -nocerts -out <filename1>.key.pem --nodes
openssl rsa -in <filename1>.key.pem -out <filename2>.text.pem --text
openssl pkcs8 -topk8 -inform PEM -outform DER -in <filename2>.text.pem -out <filename3>.key --nocrypt

```

## Further Reading {#further-reading}

* [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/using-oauth-1a-to-access-mastercard-apis).
* [Before getting started](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-security/index.md)
* [Getting started with the APIs](https://developer.mastercard.com/cross-border-services/documentation/api-basics/getting-started-oauth1a/index.md)
* [Getting Started with APIs using OAuth2.0](https://developer.mastercard.com/cross-border-services/documentation/api-basics/getting-started-oauth2/index.md)