# API Basics
source: https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/api-basics/index.md

The APIs use authentication. There is no payload encryption.

You set up the required authentication keys for the environment (Sandbox\*, MTF\* or Production) when you create your Mastercard Developers project for this service, see [Getting Started](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/getting-started/index.md). The private keys you download are provided in a format you can use directly with the Mastercard client OAuth libraries.

(\* The Sandbox keys you set up are used for both Sandbox and MTF.)

Once generated, most of these keys and their certificates can be accessed from your Mastercard Developers project page, except for the private keys you generated offline. Depending on the key type, you can also add, renew and revoke (delete) keys on that project page.

## Authentication {#authentication}

The APIs are RESTful APIs with OAuth security. Your API requests must have an OAuth 1.0a Authorization Header for authentication.

Generate the OAuth 1.0a Authorization Header using the appropriate private key (Sandbox Key or Production Key) and Consumer Key, signed using the Google Request Body Hash extension for OAuth. Your project page shows the Consumer Key (masked example shown below), which you can copy using **Actions \> Copy Consumer Key**. Ensure you copy the Consumer Key from the appropriate section.

![](https://static.developer.mastercard.com/content/mastercard-merchant-presented-qr/documentation/img/mastercard-send-consumer-key.png)

You can implement your own OAuth 1.0a header or use the relevant Mastercard OAuth libraries available on [GitHub](https://github.com/Mastercard?utf8=%E2%9C%93&q=oauth). For guidance, refer to the README.md file with the libraries.

For detailed information on using OAuth 1.0a with the APIs and generating Authorization Headers, see [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/).

## 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:

* API requests with body content (e.g. POST requests): If the Accept Header is not provided and Content-Type is provided, the response will be the same format as Content-Type.

* API requests with no body content (e.g. GET requests): If the Accept Header is not provided, the response format defaults to XML.

|     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 MPQR. 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 and will be added without changing the API version. 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.

### 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 ("_").

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

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

* Do not provide control characters or escape sequences in field values, such as \\n (newline) and \\r (carriage return).

* Name and address fields allow/support alphanumeric and special characters, as well as the extended ASCII characters listed:

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

* 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 '

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

* 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 \* , - . _ \~

* Query parameters with any of the following characters must be URL encoded:

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

* Times and timestamps present in resources returned by API calls will be in UTC (see [Date and Time Formats](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/field-uris-codes/index.md#date-and-time-formats)).

For information about the response codes, see [HTTP Response Codes](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/response-error-codes/index.md#http-response-codes).