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

## Overview {#overview}

The Mastercard Processing APIs follow Representational State Transfer (REST) principles. The APIs:

* Have predictable resource-oriented URLs
* Accept JavaScript Object Notation ([JSON](https://www.json.org/json-en.html)) request bodies
* Return JSON-encoded responses
* Use standard Hypertext Transfer Protocol (HTTP) response codes, authentication, and verbs  

The Mastercard Processing APIs use HTTPS to ensure data privacy, but HTTPS with TLS versions below v1.2 is not supported. All requests must include the header `Content-Type` of `application/json;charset=utf-8`, and the body for all requests must be a valid JSON object.

## Client authentication {#client-authentication}

Warning: **Key Expiry:** Mastercard Processing API keys expire after 13 months. You have to generate a new set of keys when they expire. To generate it, go to your project dashboard and under **API Keys** , select **Add Key**.

|          Authentication Protocol           |                                                                                                                                     Details                                                                                                                                      |
|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [OAuth 1.0a](https://oauth.net/core/1.0a/) | Mastercard Processing uses OAuth 1.0a with a body hash extension for authenticating the API clients. OAuth 1.0a is an authentication and authorization protocol that guarantees the integrity and authenticity of incoming API calls and allows for non-repudiation of requests. |

OAuth requires every request that you send to Mastercard to be signed with an RSA private key. A private-public RSA key pair must be generated consisting of:

1. A **private key** for the OAuth signature for API requests. It is recommended to keep the private key in a password-protected or hardware keystore. The private key is used to encrypt the signature base string hash, and is decrypted using the public key at the server.
2. A **public key** is shared with Mastercard during the project setup process through either a Certificate Signing Request (CSR) or an API Key Generator. Mastercard uses the public key to verify the OAuth signature that is provided on every API call.
   * Requests with a body must be signed using the [Google Request Body Hash](https://datatracker.ietf.org/doc/id/draft-eaton-oauth-bodyhash-00.html) extension for OAuth.
   * The OAuth keys are created during the process of project creation on Mastercard Developers. Additionally, you can add new OAuth keys inside your project dashboard, if needed.

Tip: Do you want to learn more about the authentication scheme Mastercard uses? If so, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/) guide.

### Authentication libraries {#authentication-libraries}

We highly recommend using the Mastercard [client authentication libraries](https://github.com/Mastercard?q=oauth) available in several popular programming languages.

## Transport encryption {#transport-encryption}

The transport over the Internet between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is secured by default when transmitted across networks. However, Mastercard additionally uses end-to-end payload encryption to encrypt sensitive data, such as Personally Identifiable Information (PII).

### JWE {#jwe}

|                         Encryption Protocol                          |                                                                                                                                                                             Details                                                                                                                                                                             |
|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [JSON Web Encryption](https://datatracker.ietf.org/doc/html/rfc7516) | JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures [RFC7159](https://datatracker.ietf.org/doc/html/rfc7159) and base64url encoding. Mastercard uses [JWE compact serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.1) for the encryption of sensitive data and supports full body payload encryption. |

All Mastercard Processing - Mastercard Services endpoints use full body JWE encryption.
Tip: Do you want to learn more about the encryption scheme Mastercard uses? If so, visit our [JWE Encryption Guide](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/#jwe-encryption).

### Encryption libraries {#encryption-libraries}

Mastercard has abstracted the encryption scheme into our [client encryption libraries](https://github.com/Mastercard?q=client-encryption), which are available in several programming languages. We recommend that you utilize these libraries to encrypt the sensitive data used by this service.

## Environments {#environments}

The following table describes the different environments that are available.

|          Environment           |                                                                                                                                                                                                                                                                                                              Description                                                                                                                                                                                                                                                                                                              |
|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox                        | The Sandbox environment is an early-access environment that provides limited-capacity mock APIs, allowing you to quickly test and begin integrating your solution. It returns predefined mock responses for specific requests (see [Testing](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/testing/index.md)) and is intended for initial development only. It should not be used for full integration testing. To access Sandbox: • Select **Mastercard Processing Mastercard** when setting up **My Projects** . • Generate your project keys. • Ensure you have received the required approvals. |
| Mastercard Test Facility (MTF) | The MTF environment provides access to the latest Production release version of APIs to conduct full User Acceptance Tests (UAT) before moving to Production. MTF is maintained and supported by Mastercard Processing, ensuring it remains functionally aligned with the Production environment. To access MTF, use the same keys generated for Sandbox. Note: Access to the MTF environment is included as part of the onboarding and implementation process offered by Mastercard Processing.                                                                                                                                      |
| Production                     | The Production environment is the live environment containing the latest Production API release. To access Production, you must select [Request Production Access](https://developer.mastercard.com/dashboard) in the Mastercard Processing Mastercard project that you have set up.                                                                                                                                                                                                                                                                                                                                                  |

## How to consume the API? {#how-to-consume-the-api}

There are two ways of integrating with the Mastercard Processing API:

* [Generating your own Mastercard Processing - Mastercard Services API client](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/api-basics/index.md#generating-your-own-mastercard-processing---mastercard-services-api-client)
* [Using a method of your choice](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/api-basics/index.md#using-a-method-of-your-choice)

### Generating your own Mastercard Processing - Mastercard Services API client {#generating-your-own-mastercard-processing---mastercard-services-api-client}

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

To learn how to generate your own client, follow the [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial using:

1. The following Mastercard Processing - Mastercard Services API specification file: [oas_mastercard_services.yaml](https://static.developer.mastercard.com/content/mastercard-processing-mastercard/uploads/oas_mastercard_services.yaml) (20KB)
2. An API client library generated using [OpenAPI Generator](https://openapi-generator.tech/docs/installation/) and the development framework of your choice (see also: [Generators List](https://openapi-generator.tech/docs/generators/)):  
   Example command (ensure that the specification file name matches the actual file you are using):  
   * Sh

   ```Sh
   openapi-generator-cli generate -g java -i oas_mastercard.yaml -o api_client
   ```

3. The following payload encryption code configurations (to be used at the [JWE - Create encryption keys]() step):
   * Java
   * C#

   ```java
   // change these values accordingly
   String clientEncryptionCertPath = "#PATH AND NAME OF YOUR PEM FILE HERE#";
   String mastercardEncryptionKeyFilePath = "#PATH AND NAME OF YOUR P12 FILE HERE#";
   String mastercardEncryptionAlias = "#YOUR KEY ALIAS HERE#";
   String mastercardEncryptionPass = "#YOUR KEY PASSWORD HERE#";

   // This will be the certificate used to encrypt the payload before sending
   Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertPath);

   // The response received from the call will need to be decrypted using this key
   PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(
           mastercardEncryptionKeyFilePath,
           mastercardEncryptionAlias,
           mastercardEncryptionPass);

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

   ```

   ```csharp
   // change these values accordingly
   var clientEncryptionCertPath = "#PATH AND NAME OF YOUR PEM FILE HERE#";
   var mastercardEncryptionKeyFilePath = "#PATH AND NAME OF YOUR P12 FILE HERE#";
   var mastercardEncryptionAlias = "#YOUR KEY ALIAS HERE#";
   var mastercardEncryptionPass = "#YOUR KEY PASSWORD HERE#";

   // This will be the certificate used to encrypt the payload before sending
   var encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertPath);

   // The response received from the call will need to be decrypted using this key
   var decryptionKey = EncryptionUtils.loadDecryptionKey(
           mastercardEncryptionKeyFilePath,
           mastercardEncryptionAlias,
           mastercardEncryptionPass);

   // Prepare JweConfig 
   var config = JweConfigBuilder.AJweEncryptionConfig()
           .WithEncryptionCertificate(encryptionCertificate)
           .WithDecryptionKey(decryptionKey)
           .WithEncryptionPath("$", "$")
           .WithDecryptionPath("$.encryptedValue", "$")
           .WithEncryptedValueFieldName("encryptedValue")
           .Build();
   ```

Tip: To learn how to build an API application with JWE, refer to the [Build an end-to-end application](https://developer.mastercard.com/mastercard-processing-core/tutorial/build-end-to-end-app/) tutorial of the Core API.

### Using a method of your choice {#using-a-method-of-your-choice}

The Funding service exposes REST APIs. Use the REST/HTTP client of your choice and leverage the Mastercard open-source [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) for signing your requests. For the API specification, see [API Reference](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/api-reference/index.md).

## Versioning (must read) {#versioning-must-read}

As per Mastercard standards, the Mastercard Processing APIs do not have any versioning in interfaces to ensure backward compatibility and avoid breaking changes.

Here is a list of what can be considered breaking and non-breaking changes.

|                     Backward-compatible (non-breaking) changes                      |                        Backward-incompatible (breaking) changes                         |
|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Adding an API interface to an API service                                           | Removing or renaming a service, interface, field, method, or enum value                 |
| Adding a method to an API interface                                                 | Changing an HTTP binding                                                                |
| Adding an HTTP binding to a method                                                  | Changing the data type of a field                                                       |
| Adding a field (an optional field or contains a default value) to a request message | Changing a resource name format                                                         |
| Adding a field to a response message                                                | Changing the visible behavior of existing requests                                      |
| Adding an output-only resource field                                                | Changing the URL format in the HTTP definition                                          |
| Adding a new optional query parameter with a default value (?parameter=value)       | Adding a read or write field to a resource message                                      |
| Adding an HTTP header field to a request/response message                           | Modifications (adding or modifying) a value to an enum in a response                    |
| Adding a new error code                                                             | Adding a new mandatory field to a request message without setting a field default value |

The listed items are not comprehensive. It only indicates what can be considered a breaking or non-breaking change.
Alert: You must adhere to these guidelines by writing an application in a way that backward-compatible changes (for example, adding a new field to a response) do not cause errors on your side. Mastercard Processing provides a minimum of 3 months' notice for changes to the APIs; see the [Release History](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/release-history/index.md) section.

## Idempotency {#idempotency}

Idempotency is a key concept in computer science, referring to certain operations that can be performed multiple times without changing the result beyond the initial execution. In the context of REST APIs, an API is considered idempotent when making multiple identical requests produce the same effect as making a single request.

To achieve idempotency, you should send an `Idempotency-Key` header that is unique to each request. The server uses this header, along with the request body, to identify subsequent retries of the same request.

The mechanism is intended to work for all `POST` methods. The `Idempotency-Key` is optional. If the header is not specified in the request, the request will be processed in the standard way.

If you send an `Idempotency-Key` in the request, then the application checks if this key is in the database.

* If the key is not found in the database, the API call is processed in a standard way according to the method's handling algorithm. When the processing is complete, the `Idempotency-Key` and the request and response bodies are stored in the database.
* If the `Idempotency-Key` of the request is already in the database, it additionally verifies the request body. If they are the same, it retrieves the response from the database and returns it.  

The idempotency keys are automatically removed from the application after 24 hours.

* If a request with a previous `Idempotency-Key` is retried after 24 hours, the request will be processed as a new request.
* If a request with a previous `Idempotency-Key` is retried within the 24-hour window, the API will reject the request with the following error:

```JSON
{
    "Errors": {
        "Error": [
            {
                "Source": "MASTERCARD PROCESSING",
                "ReasonCode": "IDEMPOTENCY_KEY_ALREADY_USED",
                "Description": "Idempotency Key MUST not be reused across different payloads.",
                "Recoverable": false
            }
        ]
    }
}
```

## Correlation-ID {#correlation-id}

The Mastercard Processing platform dynamically generates a universally unique identifier (UUID) and assigns it to the request header `X-MC-Correlation-ID`. The UUID is always added to the response header to provide end-to-end traceability.

In addition to the `X-MC-Correlation-ID`, you can generate your request identifier and pass it in the `Correlation-ID` header. It is recommended to generate a UUID in compliance with [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).

## Next Steps {#next-steps}

Now that you have an understanding of the services authentication and encryption, proceed to the [Quick Start Guide](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/quick-start-guide/index.md) section to learn how to access the API and generate your credentials.