# API Basics
source: https://developer.mastercard.com/mastercard-send-person-to-person/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-person-to-person/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 Person-to-Person (P2P) 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 P2P Payment Transfer 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: [send-payment-transfer-api-swagger.yaml](https://static.developer.mastercard.com/content/mastercard-send-person-to-person/swagger/send-payment-transfer-api-swagger.yaml) (175KB)
* 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 send-payment-transfer-api-swagger.yaml -c config.json -o api_client
  ```

The [Java API Client](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/tutorials-and-guides/api-tutorial/index.md) tutorial also shows how to generate a Java API client for this API.

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

The P2P service exposes REST APIs: 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 the API specification, refer to [API Reference](https://developer.mastercard.com/mastercard-send-person-to-person/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-person-to-person/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. Transactions in this environment are not executed against the networks. 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).                                                                                                                                                                                                                                                                                               |

Note: OAuth 1.0a authentication works the same way in Sandbox, MTF, and Production. The main differences are the base URL, keys, credentials, and Partner Reference ID (used for `partnerId`).

## HTTP Headers {#http-headers}

The APIs accept 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.

Request headers can include:

|      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 |
| `Repeat-Flag`    | Non-standard HTTP header. When set to 'true', indicates that the POST request is a ['Repeat Flag POST request'](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/tutorials-and-guides/repeat-flag/index.md) that duplicates a previous transaction request. Only use this in exception situations as per [these procedures](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/tutorials-and-guides/exception-management/index.md#procedures) or when otherwise advised by Mastercard. | false                            |

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

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

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

* 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-send-person-to-person/documentation/field-uris-codes/date-time-formats/index.md)).

### List of Resources {#list-of-resources}

In API responses, a list of resources will be represented as follows:

* `resource_type` = Type of resource, for example "list"
* `item_count` = Number of items in the list
* `data` = An array containing the actual items in the list

## API Response Times and Timeouts {#api-response-times-and-timeouts}

As a processing platform, Mastercard Send connects to downstream networks to process and manage your API requests. Based on system architecture, the maximum response time(s) available to provide a response for Mastercard Send transaction processing APIs (such as a Payment Transfer) is 40 seconds. Although this is the maximum response time based on system timeouts to handle exceptions, most of the API request response times will be below 2 seconds.

A transaction response can have an 'UNKNOWN' status in some situations, such as when a network issue delays a response from the Receive Network or there is a timeout. Mastercard Send will continue trying to retrieve the status from the Receive Network until the timeout threshold is reached.

![Send timeout unknown receiving institution](https://static.developer.mastercard.com/content/mastercard-send-person-to-person/documentation/img/mastercard-send-timeout-unknown-ri.png)

For guidance on detecting and responding to payment exception scenarios, see [Exception Management](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/tutorials-and-guides/exception-management/index.md).

### Timeouts {#timeouts}

A timeout occurs when Mastercard Send does not receive a response from the Receive Network within the expected timeframe (40 seconds). When such a timeout error occurs, Mastercard generates a system reversal (if supported by the Receive Network) and routes the reversal to the Receive Network. The API response will indicate a 'DECLINED' status.

In rare cases where a Receive Network does not support reversals, or if a network communication issue prevents the reversal from processing, the API response will indicate an 'UNKNOWN' status. See ['UNKNOWN' or 'PENDING' Status](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/response-error-codes/status/index.md#unknown-or-pending-status).

## 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-person-to-person/documentation/use-cases/index.md) for examples of how the API service could be used in a funds transfer flow.