# API Tutorial for Access Token based OAuth2.0
source: https://developer.mastercard.com/cross-border-services/documentation/tutorials/oauth2-api-sdk-tutorial-access-token/index.md

###### Time to complete: *20 minutes* {#time-to-complete-20-minutes}

If you are a Customer contracted with MTS EU or MTS UK, you must connect to the Mastercard Cross-Border Services APIs using [Access Token based OAuth2.0](https://developer.mastercard.com/cross-border-services/documentation/oauth2-access-token-based-authentication-details/index.md) for Balance APIs 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).   

## Introduction {#introduction}

This tutorial creates a simple Java program using Request Token based OAuth2.0 authentication mechanism to make an API call to the Mastercard Cross-Border Services **Balance API** ([EU specification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-balance-api/index.md)/ [UK specification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-balance-api/index.md)) in the Sandbox environment. The tutorial includes Access token based Mastercard Cross-Border Service APIs Specification.

During this tutorial, you will:

1. Add appropriate resources to your project
2. Add proper dependencies
3. Generate the API Client SDK
4. Make API Call

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

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

To complete this tutorial, you need:  

* Maven 3.6 or later
* JDK 1.8.0 or later
* IntelliJ IDEA (or any other IDE of your choice)
* [Mastercard Developers](https://developer.mastercard.com/dashboard) with access to Cross-Border Services API. (Click [here](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-create-project/index.md) for a step by step guide.)  
* Mastercard Cross-Border Services Open API specification (Retrieve by clicking on the expandable section on the **Balance API** ([EU specification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-balance-api/index.md)/ [UK specification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-balance-api/index.md)).
* Checkout the maven project of Token Generation Utility from : <https://github.com/Mastercard/send-util-crossborder-oauth2>. Build JAR file crossborder-oauth2-1.0-SNAPSHOT.jar and add this jar file in project as dependency.
* Generate the Access Token using the Auth Code/Consent, please refer [here](https://developer.mastercard.com/cross-border-services/documentation/oauth2-access-token-based-authentication-details/index.md).

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

In IntelliJ IDEA, create a new Maven project, which sets up your directory structure automatically.  
Provide ArtifactId and Project name.
Here we used the name 'cross_border_services_tutorial'. See below:

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

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

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

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

1. Add the Mastercard Cross-Border Services API specification to your Maven project's resources folder.(Retrieve by clicking on the expandable section on the Payment API)
2. Add the generated p12 file to your Maven project's resources folder. (Generated by creating Sandbox Signing Key within your project in [Mastercard Developers](https://developer.mastercard.com/dashboard)
3. Add the generated Encryption p12 file to your Maven project's resources folder. (Generated by creating Mastercard Encryption Key within your project in [Mastercard Developers](https://developer.mastercard.com/dashboard)
4. Add the generated pem file to your Maven project's resources folder. (Downloaded from Client Encryption Keys section).
5. Get the Access Token by following these steps [here](https://developer.mastercard.com/cross-border-services/documentation/oauth2-access-token-based-authentication-details/index.md)

Your Maven project directory should look as follows:

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

### d) Update pom.xml file {#d-update-pomxml-file}

1. Add the following plugin to your Maven project's pom.xml file to add OpenAPI Generator to your project.
   OpenAPI Generator generates API client libraries from OpenAPI Specifications (formerly known as Swagger files). OpenAPI Generator provides multiple generators and library templates to support multiple languages and frameworks. You will be using the java generator for this project.

   * Plugin

   ```xml
       <build>
       <plugins>
           <plugin>
               <groupId>org.openapitools</groupId>
               <artifactId>openapi-generator-maven-plugin</artifactId>
               <version>3.3.4</version>
               <executions>
                   <execution>
                       <id>Cross-Border Services REST Client</id>
                       <goals>
                           <goal>generate</goal>
                       </goals>
                       <configuration>
                           <inputSpec>${project.basedir}/src/main/resources/cross-border-swagger.yaml</inputSpec>
                           <generatorName>java</generatorName>
                           <configOptions>
                               <sourceFolder>src/gen/java/main</sourceFolder>
                               <hideGenerationTimestamp>true</hideGenerationTimestamp>
                           </configOptions>
                       </configuration>
                   </execution>
               </executions>
           </plugin>
       </plugins>
       </build>
       
   ```

2. Add the following dependencies to your pom.xml file to add dependencies for the API client library generation and the Mastercard OAuth2 Signer library.
   Mastercard offers OAuth2 Signer Libraries which offer code helpers targeting the HTTP clients used by the different OpenAPI Generator Library templates. The libraries are hosted here on [Github](https://github.com/Mastercard?utf8=%E2%9C%93&q=oauth1-signer&type=&language=).

* Dependencies

```xml
  <properties>
      <spring.version>5.2.20.RELEASE</spring.version>
      <slf4j.version>1.7.21</slf4j.version>
      <log4j2.version>2.17.2</log4j2.version>
      <jackson.version>2.13.1</jackson.version>
      <junit.version>4.12</junit.version>
      <javax.ws.rs.version>2.0.1</javax.ws.rs.version>
      <oauth1-signer-version>1.2.4</oauth1-signer-version>
      <apacheAuthZserver.version>1.0.3</apacheAuthZserver.version>
      <apacheAuthZserver.common.version>1.0.2</apacheAuthZserver.common.version>
      <nimbus-jwt>9.21</nimbus-jwt>
      <lombok.version>1.18.22</lombok.version>
      <javaxb-api-version>2.3.1</javaxb-api-version>
      <javaxb-impl-version>2.3.4</javaxb-impl-version>
      <javaxb-anntn-version>1.3.2</javaxb-anntn-version>
      <okhttp-version>2.7.5</okhttp-version>
      <jetty.version>9.4.19.v20190610</jetty.version>
      <httpclient-version>4.5</httpclient-version>
  </properties>
  <dependencies>
      <!-- Below are mandatory dependencies for executing cross border APIs-->
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-core</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-context</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <!-- Below dependencies are required for making REST calls -->
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-web</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>javax.ws.rs</groupId>
          <artifactId>javax.ws.rs-api</artifactId>
          <version>${javax.ws.rs.version}</version>
      </dependency>
      <!-- This dependency is used for authentication -->
      <dependency>
          <groupId>com.mastercard.developer</groupId>
          <artifactId>oauth1-signer</artifactId>
          <version>${oauth1-signer-version}</version>
      </dependency>
      <!-- Below dependencies are for executing use cases using JUnit-->
      <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-databind</artifactId>
          <version>${jackson.version}</version>
      </dependency>
      <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>${junit.version}</version>
          <scope>test</scope>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-test</artifactId>
          <version>${spring.version}</version>
          <scope>test</scope>
      </dependency>
      <!-- Below dependencies are used for logging of request and response -->
      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-api</artifactId>
          <version>${slf4j.version}</version>
      </dependency>
      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>jcl-over-slf4j</artifactId>
          <version>${slf4j.version}</version>
      </dependency>
      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>jul-to-slf4j</artifactId>
          <version>${slf4j.version}</version>
      </dependency>
      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>log4j-over-slf4j</artifactId>
          <version>${slf4j.version}</version>
      </dependency>
      <dependency>
          <groupId>org.apache.logging.log4j</groupId>
          <artifactId>log4j-slf4j-impl</artifactId>
          <version>${log4j2.version}</version>
      </dependency>
      <dependency>
          <groupId>com.nimbusds</groupId>
          <artifactId>nimbus-jose-jwt</artifactId>
          <version>${nimbus-jwt}</version>
      </dependency>
      <dependency>
          <groupId>org.projectlombok</groupId>
          <artifactId>lombok</artifactId>
          <version>${lombok.version}</version>
          <scope>provided</scope>
      </dependency>
      <dependency>
          <groupId>org.apache.oltu.oauth2</groupId>
          <artifactId>org.apache.oltu.oauth2.jwt</artifactId>
          <version>${apacheAuthZserver.version}</version>
      </dependency>
      <dependency>
          <groupId>org.apache.oltu.oauth2</groupId>
          <artifactId>org.apache.oltu.oauth2.common</artifactId>
          <version>${apacheAuthZserver.common.version}</version>
      </dependency>
      <dependency>
          <groupId>javax.annotation</groupId>
          <artifactId>javax.annotation-api</artifactId>
          <version>${javaxb-anntn-version}</version>
      </dependency>
      <dependency>
          <groupId>javax.xml.bind</groupId>
          <artifactId>jaxb-api</artifactId>
          <version>${javaxb-api-version}</version>
      </dependency>
      <dependency>
          <groupId>com.sun.xml.bind</groupId>
          <artifactId>jaxb-impl</artifactId>
          <version>${javaxb-impl-version}</version>
      </dependency>
      <dependency>
          <groupId>com.squareup.okhttp</groupId>
          <artifactId>logging-interceptor</artifactId>
          <version>${okhttp-version}</version>
      </dependency>
      <dependency>
          <groupId>com.squareup.okhttp</groupId>
          <artifactId>okhttp</artifactId>
          <version>${okhttp-version}</version>
      </dependency>
      <dependency>
          <groupId>org.eclipse.jetty</groupId>
          <artifactId>jetty-server</artifactId>
          <version>${jetty.version}</version>
      </dependency>
      <dependency>
          <groupId>org.eclipse.jetty</groupId>
          <artifactId>jetty-util</artifactId>
          <version>${jetty.version}</version>
      </dependency>
      <dependency>
          <groupId>org.apache.httpcomponents</groupId>
          <artifactId>httpclient</artifactId>
          <version>${httpclient-version}</version>
      </dependency>
  </dependencies>
```

When using OpenAPI Generator to generate the API client library, you have two options:

* Generate and use the source files on the fly
* Generate and deploy the source files to a Maven repository In this tutorial, you will be generating the API client library on the fly, so you include the dependencies that are needed to generate the library. (If you were deploying the source files to a Maven repository, you would only need to include the dependency for that repository.)

## Step 2: Generating the API Client SDK {#step-2-generating-the-api-client-sdk}

### a) Generate Sources {#a-generate-sources}

Now that you have all the dependencies you need, you can generate the sources.

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

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

### b) Generate the SDK {#b-generate-the-sdk}

You should now be ready to generate the API client library.

In the same menu, navigate to the commands ({Project name} \> Lifecycle), run clean and then compile. Alternatively, you can navigate to the root directory of the project within a terminal window and run mvn clean compile.

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

Afterwards, there should be a new folder named target, within your root directory, which contains classes generated for the schemas and API calls defined within the OpenAPI Specification. The generated classes can be found in target folder as shown below.

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

## Step 3: Making API Call (Encrypted payload) {#step-3-making-api-call-encrypted-payload}

Make sure you have below dependency added to your pom.xml file for Encryption.

        <dependency>
            <groupId>com.mastercard.developer</groupId>
            <artifactId>client-encryption</artifactId>
            <version>1.6.0</version>
        </dependency>

Create a Java file, called Main.java, at src/main/java/.

To make an API call with encrypted payload, you need to make your OAuth credentials and Encryption keys available to the program to use:
* Oauth

```Oauth
String token = "Bearer <your access token>";
client.addDefaultHeader("Authorization", token);

String decryptionKeyFilePath = "/path/to/your/key.p12";
String decryptionKeyAlias = "your decryption key alias";
String decryptionKeyPassword = "your decryption password";
PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(decryptionKeyFilePath, decryptionKeyAlias, decryptionKeyPassword)
String encryptionCertPath = "/path/to/your/CrossBorderServicesEnc.pem";
```

Next, you instantiate a client that you can set up to sign requests that you send with your authentication credentials.
* Client_Instantiation

```Client_Instantiation
ApiClient client = new ApiClient();
client.setBasePath("/path/to/your/domainURL");
client.setDebugging(true);
client.setReadTimeout(40000);

// for mTLS connection (For Sandbox EU/UK domain testing, do not keep below configurations)
KeyStore keystore = KeyStore.getInstance("PKCS12");
char[] password= "yourPfxPassword".toCharArray();

keystore.load((new FileInputStream("/path/to/your/pfxFile")),password);

SSLContextBuilder builder = new SSLContextBuilder();
builder.loadTrustMaterial(null, new TrustSelfSignedStrategy());
builder.loadKeyMaterial(keystore, "yourPfxPassword".toCharArray());
SSLContext sslContext = builder.build();

SSLSocketFactory sf = sslContext.getSocketFactory();
OkHttpClient httpClient = client.getHttpClient();
httpClient.setSslSocketFactory(sf);
client.addDefaultHeader("Content-Type", "application/json; charset=UTF-8");
client.setHttpClient(httpClient);

List<Interceptor> interceptors = client.getHttpClient().interceptors();

List<Interceptor> interceptors = client.getHttpClient().interceptors();
        interceptors.add(new ForceJsonResponseInterceptor());
        JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
                .withEncryptionCertificate(EncryptionUtils.
                        loadEncryptionCertificate("/path/to/your/.pem"))
                .withEncryptionPath("$", "$.encrypted_payload")
                .withEncryptedValueFieldName("data")
                .withDecryptionKey(EncryptionUtils.loadDecryptionKey("/path/to/your/encryption-key.p12"
                        , "yourKeyAlias", "yourPassword"))
                .withDecryptionPath("$.encrypted_payload.data", "$")
                .build();
        interceptors.add(OkHttp2JweInterceptor.from(config));
        client.addDefaultHeader("x-encrypted","true");
RetrieveAccountBalancesApi retrieveAccountBalancesApi = new RetrieveAccountBalancesApi(client);   
        
```

The interceptor that you use to sign requests is also provided by the Mastercard OAuth library.

With your environment set up, you can start to build a request.
Any nested objects within the Request Body have each been assigned a wrapper class, and so in order to build the request, you will be instantiating multiple objects and ultimately wrapping those with the main request object.
You make the Encrypted API call, parse the response payload and store it into a Response object.
Once you have the response stored, you have different options, but for this tutorial you can simply use toString to print the response body.  

To make it easy to understand, only the snippets needed to make the API call is shown above. The full content of Main.java is shown below.

## Content of Main.java {#content-of-mainjava}

* Main.Java

```Main.Java
package com.mastercard.test;

import com.mastercard.developer.encryption.JweConfig;
import com.mastercard.developer.encryption.JweConfigBuilder;
import com.mastercard.developer.interceptors.OkHttp2JweInterceptor;
import com.mastercard.developer.utils.EncryptionUtils;
import org.openapitools.client.api.RetrieveAccountBalancesApi;
import com.squareup.okhttp.Interceptor;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.logging.HttpLoggingInterceptor;
import org.apache.http.conn.ssl.TrustSelfSignedStrategy;
import org.apache.http.ssl.SSLContextBuilder;
import org.openapitools.client.ApiClient;
import org.openapitools.client.model.*;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLSocketFactory;
import java.io.FileInputStream;
import java.io.IOException;
import java.security.KeyStore;
import java.util.List;

public class AccesTokenBased {
    public static void main(String[] args) throws Exception {


        String partnerId = "PSD2_OI_Encrypt"; //"PSD2-OI-Payment"; //"SANDBOX_LISA"

        /*Payment API call*/
        RetrieveAccountBalancesApi retrieveAccountBalancesApi = new RetrieveAccountBalancesApi(getAccessTokenApiClientUnencrypted());
        System.out.println("Calling Get All Account Balances");
        Account lstAccounts = retrieveAccountBalancesApi.getAllAccountBalances(partnerId, "true");
        System.out.println("Get All Account Balances response : " + lstAccounts);

    }

    private static ApiClient getAccessTokenApiClientUnencrypted() throws Exception {

        client.setBasePath("/path/to/your/domainURL");
        // Set the Access Token generated using Auth Code
        String token = "Bearer <your access token>";
        client.addDefaultHeader("Authorization", token);
        client.setDebugging(true);
        client.setReadTimeout(40000);
        
        KeyStore keystore = KeyStore.getInstance("PKCS12");
        char[] password= "yourPFXPassword".toCharArray();
        keystore.load((new FileInputStream("/path/to/your/.pfx")),password);
        
        SSLContextBuilder builder = new SSLContextBuilder();
        builder.loadTrustMaterial(null, new TrustSelfSignedStrategy());
        builder.loadKeyMaterial(keystore, "yourPFXPassword".toCharArray());
        SSLContext sslContext = builder.build();

        SSLSocketFactory sf = sslContext.getSocketFactory();
        OkHttpClient httpClient = client.getHttpClient();
        httpClient.setSslSocketFactory(sf);
        client.addDefaultHeader("Content-Type", "application/json; charset=UTF-8");
        client.setHttpClient(httpClient);

        List<Interceptor> interceptors = client.getHttpClient().interceptors();
        HttpLoggingInterceptor logger = new HttpLoggingInterceptor();
        logger.setLevel(HttpLoggingInterceptor.Level.BODY);
        interceptors.add(logger);
        return client;
    }

    /**
     * Add "Format=JSON" to the request for the service/gateway to return a JSON response.
     */
    private static class ForceJsonResponseInterceptor implements Interceptor {
        @Override
        public Response intercept(Chain chain) throws IOException {
            Request originalRequest = chain.request();
            String withJsonFormatUrl = withJsonFormat(originalRequest.uri().toString());
            Request newRequest = originalRequest.newBuilder().url(withJsonFormatUrl).build();
            return chain.proceed(newRequest);
        }

        private String withJsonFormat(String uri) {
            StringBuilder newUri = new StringBuilder(uri);
            newUri.append(uri.contains("?") ? "&" : "?");
            newUri.append("Format=JSON");
            return newUri.toString();
        }
    }
}
```

Note: Well Done! 👏. You have successfully completed the tutorial on how to generate the SDK and connect to the Mastercard Cross-Border Payment API in sandbox using the SDK.

## 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).

* [OpenAPI Generator](https://openapi-generator.tech/)