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

## API Security {#api-security}

### Client authentication {#client-authentication}

Mastercard uses OAuth 1.0a for authenticating your application. You can manage your authentication keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard) after you created a project using the **Mastercard Account Validation** API service.
Tip: Do you want to learn more about the authentication scheme Mastercard uses? For that, 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.

### Transport encryption {#transport-encryption}

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

In addition to that, this service supports optional JSON Web Encryption (JWE) to provide end-to-end payload encryption to secure sensitive data like Personally Identifying Information (PII). You can manage your encryption keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard). The Sandbox API does not support payload encryption.

To use payload encryption for the full APIs, you must request enablement when Mastercard onboards your configuration preferences. The onboarding choice is:

* Disabled = Always use unencrypted payloads
* Enabled = Always use encrypted payloads
* Flexible = Can use either unencrypted or encrypted payloads, indicated by the `X-Encrypted` header value

Tip: Do you want to learn more about the authentication and encryption schemes Mastercard uses? For that, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) and [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) guides.

## How to consume the Account Validation API {#how-to-consume-the-account-validation-api}

There are multiple ways of integrating with this API service:

* Using a generated API client (recommended)
* Using a method of your choice

### Generating your own API client {#generating-your-own-api-client}

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

For this, please follow our [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/) tutorial with the following API specification:
[account-validation-api-swagger.yaml](https://static.developer.mastercard.com/content/account-validation/swagger/account-validation-api-swagger.yaml) (29KB)

To use payload encryption with the full APIs, use the encryption configuration below (to be used at the "*Enable Encryption*" step of the tutorial):
* Java
* C#

```java
JweConfig encryptionConfig = JweConfigBuilder.aJweEncryptionConfig()
    .withEncryptionCertificate(encryptionCertificate)
    .withDecryptionKey(decryptionKey)
    .withEncryptionPath("$", "$.encrypted_payload")
    .withDecryptionPath("$.encrypted_payload.data", "$")
    .withEncryptedValueFieldName("data")
    .build();
```

```csharp
var encryptionConfig = JweConfigBuilder.AJweEncryptionConfig()
    .WithEncryptionCertificate(encryptionCertificate)
    .WithDecryptionKey(decryptionKey)
    .WithEncryptionPath("$", "$.encrypted_payload")
    .WithDecryptionPath("$.encrypted_payload.data", "$")
    .WithEncryptedValueFieldName("data")
    .Build();
```

Mastercard uses [JWE compact serialization](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#jwe-encryption). Example encrypted payload for a request or success response:
* JSON

```JSON
{
  "encrypted_payload": { 
    "data": "eyJhbGciO12345NBLU9BRVAiLCJlbmMiOiAiQTI1NkdDTSIsImtpZCI6ICJhNGI0N2VlMWQ3NGZhYmNkYWYxMDI2YWZiYmFkZjE0YmRkNDMwY2MyNzNjMzliOTcxNWQwYTJmNjMwNDc2NGRjIiwiY3R5IjogImFwcGxpY2F0aW9uL2pzb24iCn0=.MSxQNqXDpK8cmhn4U912345vW5tj_4XR5iMgB5JBT0hjr0X6r-4pBdI5O6OokbRdKDSJZJxkPbyE_FJDS1o77tXB51WNqffYpvfm_FDOZbynqB3mF6WOYvDWVd2OXsqABRttVVpLekfcgEi2Zx9g98qtmPouHHNhJ4i0YVerLtRMO4rJlFUDqniJtXSoaShkmT8d0nMpl7s0tFANl432WScwxkgZK_lFWdIIwBzRwN9PM0F72AtVPrDnBH5xRAiHWGY0BKMgIC0Lb6RjXnkGlX3Ar620CW_1vFvc_YF1PWI_T2XfGITux_UgUfRbpgMoHRImjGdLsCXGruESNXsVFQ.rQxU123452YXBz7M.NDpzf_8bI123454_n-varEr20hPsW7UffHAggZXVVQPhLPu-eMEeJxUvWwHl-56xOYvw83BVpwUxxHzG6BWIOi02n51pAuGqpLpCHMRXZBC2uJL0x3Xy9865H5rScsVeqXi1L506XoXG2jtp-aa37sNgNFSsMUPcwVi_kw-DNSsfSpDaoKa3ZeXz97ub4cE7Rz2DHdySRtthtvFtJiixnl1l-DSwAP93Ha-LKgykeqBx6aZPUl-z0bzKXXjsQTbughn4Txhfsdfgx1Bz3Omt7hQIqwqcCOnvZQcw-5OZ_9uJNRWQeMv0fhYU9KYu71J2J9WAaGjfOt5UGsGSB-hpmBTxQOXN832FHCi4XdpUgSBfm35Pyw-fffpCAmrgr8pzqC_0AC7012O2plKv6w.qLtaT12345ofSHPUk3L03Q"
  }
}
```

[Error responses](https://developer.mastercard.com/account-validation/documentation/code-and-formats/index.md#error-codes) are not encrypted.

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

This service exposes a REST API: you are free to use the REST/HTTP client of your choice and can still leverage the Mastercard open-source [client authentication](https://developer.mastercard.com/platform/documentation/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 dealing with payload encryption.

For that, please refer to the Account Validation [REST API Reference](https://developer.mastercard.com/account-validation/documentation/api-reference/index.md).

## Environments {#environments}

The table below describes the three different environments that are available.

|          Environment           |                                                                                                                                                                                                                                                                                             Description                                                                                                                                                                                                                                                                                             |
|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox                        | Early-access environment containing a limited-capacity mock API, enabling you to try the API quickly to assist with initial integration and solution development. The Sandbox returns mock responses for a defined request (see [Sandbox Testing](https://developer.mastercard.com/account-validation/documentation/testing/index.md#sandbox-testing)) and should not be used for full integration testing. Use your Sandbox keys to authenticate with this environment. The keys are set up when you create your project. The Sandbox API does not support payload encryption.                     |
| Mastercard Test Facility (MTF) | Pre-production test environment containing the latest pre-release version of the real API, intended for full integration testing prior to moving to production. Validation inquiries for this environment are handled by a simulator; they are not passed to card issuers. Use your Sandbox keys for authentication. If you request enablement of payload encryption when Mastercard onboards your configuration preferences, you can send encrypted request payloads to the MTF API and receive encrypted success (200) responses. Use your Sandbox encryption keys for encryption and decryption. |
| Production                     | Full production environment containing the latest production API release. Use your Production keys to authenticate with this environment. The keys are set up when you request Production access for your project (via your project page). If you use the optional payload encryption, use your Production encryption keys for encryption and decryption.                                                                                                                                                                                                                                           |

## Technical considerations {#technical-considerations}

We reserve the right to add optional parameters to resource actions/services and to add new fields to resource representations returned in responses. These types of changes are considered backward compatible. Applications consuming these resources should be written such that new fields appearing in returned resource representations will not cause errors.

We reserve the right to truncate consumer data, when required to comply with constraints of financial messages initiated through calls to the API. We will not modify the consumer data in storage but will perform any required truncation when the financial message is constructed.

If a field is not provided or populated, it will be omitted from the response. However, participants should code to all response fields.

### Conventions {#conventions}

* Avoid providing blank/empty values for any optional fields. If you are not supplying a field value, omit the field completely.

* Unless otherwise specified, API fields allow/support UTF (English) alphanumeric characters, but do not support multi-lingual characters and MBCS (multibyte character set).