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

## Client Authentication {#client-authentication}

Mastercard uses [OAuth 1.0a](https://oauth.net/core/1.0a/) with a body hash extension for authenticating 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 API 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:

* A **private key** for signing OAuth API requests. Store the private key in a password-protected or hardware keystore. It encrypts the signature base string hash, which the server decrypts using the public key.
* A **public key** shared with Mastercard during project setup through a certificate signing request (CSR) or an API Key Generator. Mastercard uses the public key to verify the OAuth signature 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.

You generate and download your OAuth keys, also known as signing keys, when you create your Mastercard project with the **Mastercard Send** API service, see the [Quick Start Guide](https://developer.mastercard.com/mastercard-send-avs/documentation/quick-start-guide/index.md). You can also add and manage the keys in your Mastercard Developers project page, accessed from your [My projects](https://developer.mastercard.com/dashboard) dashboard.
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}

Connections between client applications and Mastercard are secured using [Transport Layer Security (TLS/SSL)](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is secured by default when transmitted across networks. All Mastercard Send APIs support TLS 1.2 and 1.3.

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

There are multiple ways of integrating with the Account Verification 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 Verification API specification and let Mastercard open-source client libraries handle the authentication for you. This approach offers more flexibility and is strongly recommended.

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

* The following OpenAPI specification file: [account-verification-api-swagger.yaml](https://static.developer.mastercard.com/content/mastercard-send-avs/swagger/account-verification-api-swagger.yaml) (16KB)
* 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/)):
  * Sh

  ```sh
  openapi-generator-cli generate -g java --library okhttp-gson -i account-verification-api-swagger.yaml -c config.json -o api_client
  ```

### Using a Method of Your Choice {#using-a-method-of-your-choice}

The Account Verification Service exposes a REST API: you can use the REST/HTTP client of your choice and can still leverage the Mastercard open-source [client libraries](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) for signing your requests.

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

## Environment Descriptions {#environment-descriptions}

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

|          Environment           |                       Base URL                        |                                                                                                                                                                                                                                                         Description                                                                                                                                                                                                                                                         |
|--------------------------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox                        | `https://sandbox.api.move.mastercard.com/send/static` | Early-access environment containing limited-capacity mock APIs, enabling you to try the APIs 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/mastercard-send-avs/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. |
| Mastercard Test Facility (MTF) | `https://sandbox.api.move.mastercard.com/send`        | Pre-production test environment containing the latest pre-release version of the real APIs, intended for full integration testing prior to moving to production. Use your Sandbox keys for authentication.                                                                                                                                                                                                                                                                                                                  |
| Production                     | `https://api.move.mastercard.com/send`                | 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).                                                                                                                                                                                                                                                                                  |

## HTTP Headers {#http-headers}

The API accepts requests in JSON or XML format. Use the Content-Type header to provide the data format in the request and use the Accept header to determine the response format. If the Accept header is not provided and Content-Type is provided, the response will be the same format as Content-Type.

|     Header     |                           Description                            |             Examples             |
|----------------|------------------------------------------------------------------|----------------------------------|
| Content‑Type   | The format of the body content being submitted: JSON or XML.     | application/json application/xml |
| Content‑Length | The length of the body content being submitted, in octets.       | 54138                            |
| Accept         | The format you would like returned in the response: JSON or XML. | application/json application/xml |

The response includes this header:

|     Header     |                                                                                                                                                                                                                              Description                                                                                                                                                                                                                               |            Examples            |
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
| correlation-id | The unique Correlation ID for the API call in Mastercard systems. We recommend you log this ID for tracking purposes. When seeking support, providing the relevant Correlation ID may help resolve your inquiry more quickly. For example, in some situations an unsuccessful API call may result in a 4xx/5xx error response and the request message data might not reach Mastercard Send. Mastercard Support teams can use the Correlation ID to trace the API call. | 0.9d5e6cc1.1692956220.1e87632a |

## 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 populated, it will be omitted from the response. However, participants should code to all response fields.

### Conventions {#conventions}

* URLs will be all lowercase, with the possible exception of resource identifiers.

* When URL elements consist of multiple words, the words will be separated by hyphens ("-").

* Input parameter names and resource member names will be in lowercase.

* When input parameter names and resource member names consist of multiple words, the words will be separated by underscores ("_").

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

* Unless otherwise specified, parameter and resource data types will allow/support UTF (English) alphanumeric characters (a-z,A-Z,0-9) and special characters that are supported by the networks. Special characters include:  

  \<space\> ! " # $ % \& ' ( ) \* + , - . / : ; \< = \> ? @ \[ \\ \] _ \` { \| } \~

* Name and address fields allow/support alphanumeric and special characters as well as the extended ASCII characters listed below. Other multi-lingual characters and MBCS (multibyte character set) are not supported.  

  À Á Â Ã Ä Å Ç È É Ê Ë Ì Í Î Ï Ñ Ò Ó Ô Õ Ö Ù Ú Û Ü Ý à á â ã ä å ç è é ê ë ì í î ï ñ ò ó ô õ ö ù ú û ü ý ÿ

* Within submitted XML, the following special character substitutions must be made:  

  \< would be \&lt;  

  \> would be \&gt;  

  " would be \&quot;  

  \& would be \&amp;  

  ' would be '

* Resource references must contain only characters from the following set, which will result in resource references that can be passed as URL query parameters or in XML without encoding:  

  Alphanumeric and \* , - . _ \~

## Next Steps {#next-steps}

Now that you have an understanding of the service's authentication, proceed to [Use Cases](https://developer.mastercard.com/mastercard-send-avs/documentation/use-cases/index.md) for examples of how the API service could be used in a funds transfer flow.