# Getting Started with the APIs using OAuth2.0
source: https://developer.mastercard.com/cross-border-services/documentation/api-basics/getting-started-oauth2/index.md

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

Please follow the below step by step instructions to connect to the Mastercard Cross-Border Services APIs.

## Step 1: Create Project and Project Keys {#step-1-create-project-and-project-keys}

To start using the Cross-Border Service APIs, you must create a [Mastercard Developers account](https://developer.mastercard.com/account/sign-up) and then create a project choosing the **Mastercard Cross-Border Services** API service. The project will generate the project keys required to use the APIs in each of the environments.
The [Quick Start Guide](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-create-project/index.md) provides detailed information about creating a project and downloading the project keys.
In case, if you have an existing project, refer [Adding a new service to an existing project](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-create-project/#adding-a-new-service-to-an-existing-project).
Note:   

* The Quick Start Guide referred above steps through the OAuth1.0A key creation. Please follow the same steps since we will be using the same keys for this flow as well.

* Project keys are subject to **annual** renewal. Mastercard recommends that you use a group email address when creating your project to ensure that team members can access the Mastercard Developers account used for testing and production.
  For more details, see [Project Keys](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-security/index.md#project-keys)

## Step 2: Exchange Certificates to enable mTLS {#step-2-exchange-certificates-to-enable-mtls}

To be able to make a successful Cross-Border Services API call, you will first require to establish MTLS connectivity between your application and Mastercard's Cross-Border Services APIs.
For more details, refer the [Instructions for MTLS setup](https://developer.mastercard.com/cross-border-services/documentation/api-basics/oauth2-mtls-setup/index.md) section.

If you have already setup the MTLS certificate via Mastercard's Key Management Portal (KMP) tool and need to renew your certificates, refer the [Instructions for MTLS certificate renewal](https://developer.mastercard.com/cross-border-services/documentation/api-basics/oauth2-mtls-cert-renewal/index.md) section.
Note:   

* For Sandbox EU/UK domain testing, mTLS certificate is not needed. APIs can be directly accessed using REQUEST and ACCESS Token.

## Step 3: Connect to the Mastercard Cross-Border Services APIs {#step-3-connect-to-the-mastercard-cross-border-services-apis}

You start connecting to the API in the **sandbox** environment, where you access API stubs that return simulated, static responses. See [Mastercard Environments](https://developer.mastercard.com/cross-border-services/documentation/api-basics/environments/index.md) for details.

The Cross-Border Service APIs are RESTful APIs with OAuth security in conformity with Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2).

### a) Authentication: {#a-authentication}

Generate the OAuth 2.0 Authorization Header using the appropriate token flows as follows:

|                             |                                                                                                                                                                                  |
|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| All APIs except Balance API | [Use OAuth2.0 Request Token based flow](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-request-token-based-authentication-details/index.md) |
| Balance API                 | [Use OAuth2.0 Authorization Code flow](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-access-token-based-authentication-details/index.md)   |

Note: Host header must be passed with every API request. It should refer to the mtf.api.xbs.mastercard.eu/uk in case of MTF and sandbox.api.xbs.mastercard.eu/uk in case of sandbox.

### b) Encryption: {#b-encryption}

All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the response payload sent by Mastercard. For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md).   

**NOTE**: API error responses are not encrypted.

### c) Connection: {#c-connection}

Connect to Cross-Border Service API using any of the below two options:

#### Option 1: Direct Integration with APIs (using any REST client) {#option-1-direct-integration-with-apis-using-any-rest-client}

For your convenience, we have created a Reference application that demonstrates how to connect to the various Cross-Border Service APIs using a REST client. You may download the [OAuth2.0 Authorization Code flow sample reference](https://github.com/Mastercard/crossborder-services-reference-app-oauth2) and [OAuth2.0 Request Token based flow sample reference](https://github.com/Mastercard/crossborder-services-reference-app-oauth2).   

**Note** : The application built is for reference purposes only. Your production application does not need to function the same way.

Look at the [OAuth2.0 Authorization Code flow Reference Tutorial](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-reference-app-tutorial-access-token/index.md) and [OAuth2.0 Request Token based flow Reference Tutorial](https://developer.mastercard.com/cross-border-services/documentation/ref-app/oauth2-reference-app-tutorial-request-token/index.md) for step by step instructions.

#### Option 2: Generate SDK to integrate with APIs {#option-2-generate-sdk-to-integrate-with-apis}

Another way is to generate a simple client using the [OpenAPI Generator](https://openapi-generator.tech/docs/integrations/) along with the [Mastercard libraries for authentication](https://github.com/Mastercard?utf8=%E2%9C%93&q=oauth)) and use the client to connect to the Mastercard Cross-Border Services APIs.  

Take a look at the API Tutorial for [OAuth2.0 Request Token based flow](https://developer.mastercard.com/cross-border-services/documentation/tutorials/oauth2-api-sdk-tutorial-request-token/index.md) that shows a simple example on how to make an API call by generating client SDK to connect to the Cross-Border Service API.

## Next Steps {#next-steps}

1. Once you have successfully connected to the Cross-Border Service APIs, you will be able to test the APIs in the sandbox environment. Please refer to the respective APIs under [API Reference](https://developer.mastercard.com/cross-border-services/documentation/api-ref/index.md) for the sandbox test cases and sample request/ response.

2. Prior to the next phase of testing, a project should be opened to properly assign resources. Mastercard will ensure eligibility requirements are met.

<!-- -->

3. When you are ready to test with the full APIs and have met the eligibility requirements, you can ask your Mastercard representative for access to the MTF environment as shown in this [MTF Access Guide](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-mtf-access/index.md).

4. For MTF testing, your assigned Mastercard implementation manager will provide you a **Partner ID** assigned to your organization, a detailed test plan and test cases specific to your program requirements and the destination endpoints you have selected.

5. Once you have successfully made test requests and your application has appropriately handled the responses, you will be provided a detailed **Technical Endpoint Guide** unique to your program requirements that will include specific information about the fields required vs. optional based on the destination endpoints you have selected. It is required that you perform development against these specifications prior to the next phase of testing.

6. Once MTF testing is complete, you can request Production access for your project (refer [step-by-step guide](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-move-to-production/index.md) ), which requires approval from Mastercard and assistance from the Mastercard's Customer Implementation Services (CIS) Team.