# API Basics
source: https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md

## API Security {#api-security}

## Authentication {#authentication}

Mastercard Installments API uses OAuth 1.0a for authenticating client applications. For detailed information, refer to [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/).
Note: Consider the following key points:

* Request with a body must be additionally signed using the [Google Request Body Hash](https://datatracker.ietf.org/doc/id/draft-eaton-oauth-bodyhash-00.html) extension for OAuth.
* OAuth keys for your project can be set up in your [Mastercard Developers](https://developer.mastercard.com/account/log-in?referral_path=%2Fdashboard) dashboard.
* Client authentication libraries in several programming languages can be found [here](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries).

## Encryption {#encryption}

The transport between client applications and Mastercard is secured using [TLS / SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is encrypted by default when transmitted across networks.

Additionally, any PCI sensitive and Personally Identifiable Information (PII) data must be encrypted while consuming the Mastercard Installments API. Mastercard Installments API uses the JSON Web Encryption (JWE) scheme for encryption and decryption of sensitive data in the request and response payload as necessary, which is described in [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/).

Mastercard has abstracted the encryption scheme in the [client encryption libraries](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/) available in most commonly used development languages. We highly recommend utilizing these libraries to encrypt the sensitive data used by this service.

Following table describes the encryption requirements for each Mastercard Installments API endpoint. You can refer to [Mastercard Installments API specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md) to view plain and encrypted request/response payload examples for each API endpoint.

### Group #1 {#group-1}

|              API endpoint              |        Request Payload encryption         |        Response Payload Encryption        |
|----------------------------------------|-------------------------------------------|-------------------------------------------|
| `POST /offers`                         | Client needs to do field level encryption | N/A                                       |
| `POST /plans`                          | Client needs to do field level encryption | N/A                                       |
| `POST /consumers/pans/registrations`   | Client needs to do field level encryption | Client needs to do field level decryption |
| `POST /consumers/pans/deregistrations` | Client needs to do field level encryption | Client needs to do field level decryption |

All above API endpoints use the following JWE configuration:
* Java

```java
JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withDecryptionKey(decryptionKey)
    .withEncryptionPath("$.sensitiveData",
"$")
    .withDecryptionPath("$.encryptedValue",
"$.sensitiveData")
    .withEncryptedValueFieldName("encryptedValue")
    .build();
```

### Group #2 {#group-2}

|               API endpoint               |        Request Payload encryption         | Response Payload Encryption |
|------------------------------------------|-------------------------------------------|-----------------------------|
| `POST /notifications` (Hosted by Client) | Client needs to do field level decryption | N/A                         |

The above API endpoint uses the following JWE configuration:
* Java

```java
JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
          .withDecryptionKey(decryptionKey)
          .withDecryptionPath("$.encryptedValue",
"$.sensitiveData")
          .build();
```

### Group #3 {#group-3}

|   API endpoint    |         Request Payload encryption         | Response Payload Encryption |
|-------------------|--------------------------------------------|-----------------------------|
| `POST /approvals` | Client needs to do full payload encryption | N/A                         |

The above API endpoint uses the following JWE configuration:
* Java

```java
JweConfig config = JweConfigBuilder.aJweEncryptionConfig()
	.withEncryptionCertificate(encryptionCertificate)
	.withDecryptionKey(decryptionKey)
	.withEncryptionPath("$",
"$")
	.withDecryptionPath("$.consumer.encryptedData",
"$.consumer")
	.withEncryptedValueFieldName("cipher")
	.build();
```

### Group #4 {#group-4}

|           API endpoint           | Request Payload encryption | Response Payload Encryption |
|----------------------------------|----------------------------|-----------------------------|
| `POST /merchants/participations` | N/A                        | N/A                         |
| `GET /merchants/participations`  | N/A                        | N/A                         |
| `POST /merchants/searches`       | N/A                        | N/A                         |
| `POST /merchants/mids/searches`  | N/A                        | N/A                         |
| `GET /approvals/{plan_id}`       | N/A                        | N/A                         |

The above endpoints do not require JWE encryption of the request or response payload.

## How to Consume the Mastercard Installments API? {#how-to-consume-the-mastercard-installments-api}

### Option 1: Generating your own Mastercard Installments API client (Recommended) {#option-1-generating-your-own-mastercard-installments-api-client-recommended}

Create a customizable API client from the Mastercard Installments API specification and let Mastercard open-source client libraries handle the authentication and encryption for you. This approach offers more flexibility and is strongly recommended.

For this, follow [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/generating-and-configuring-a-mastercard-api-client/) with the following considerations:

* In Step 2, use [Mastercard Installments API](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md) specification.
* In Step 7, use the JWE configuration as explained in [Encryption](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md#encryption) .

Considering the above documentation is generic, we have prepared a step-by-step documentation a sample Java based Mastercard Installments API client setup and configuration in this [tutorial](https://developer.mastercard.com/unified-installments/tutorial/integration-and-testing/step7/index.md).

In addition, we have also developed a [reference application](https://developer.mastercard.com/unified-installments/documentation/reference-app/index.md) which shows a Java based implementation of the Mastercard Installments API. We strongly recommend customers to refer to this application to understand the usage of Mastercard provided authentic and client encryption libraries along with JWE configurations for every API endpoint.

### Option 2: Using a method of your choice {#option-2-using-a-method-of-your-choice}

The Mastercard Installments API exposes a REST [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md). You are free to use any REST/HTTP client of your choice and can still use the Mastercard open-source [client authentication](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) and [client encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries) libraries for signing your requests and performing payload encryption and decryption.

## Environments {#environments}

The following table describes the different environments that are available:

|             **Environment**              |                                                                                                                  **Description**                                                                                                                  |
|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox - Mastercard Test Facility (MTF) | The pre-Production test environment contains the latest pre-release or released version of the API, intended for full integration testing before moving to Production. At this stage, use the Sandbox keys generated during the project creation. |
| Production                               | The Production environment contains the latest Production API release. You can request approval to obtain the production keys. Once approved, you can proceed to complete testing in the production environment before launching your solution.   |

## Next Steps {#next-steps}

1. Review the [Mastercard Installments API specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md) and identify the endpoints relevant to your use case.
2. Review [reference application](https://developer.mastercard.com/unified-installments/documentation/reference-app/index.md) to understand how to build and configure an API client.