# API Basics
source: https://developer.mastercard.com/mastercard-send-funding/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 create a project using the **Mastercard Send** 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.

## How to Consume the Funding APIs {#how-to-consume-the-funding-apis}

There are multiple ways of integrating with the Funding 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 Funding 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:
[send-funding-api-swagger.yaml](https://static.developer.mastercard.com/content/mastercard-send-funding/swagger/send-funding-api-swagger.yaml) (170KB)

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

The Funding service exposes REST APIs: you are free to 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-funding/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 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-funding/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) | 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                     | 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:

* 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 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-funding/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 Funding 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 Network or there is a timeout. Mastercard Send will continue trying to retrieve the status from the Network until the timeout threshold is reached.

![](https://static.developer.mastercard.com/content/mastercard-send-funding/documentation/img/mastercard-send-timeout-unknown-si.png)

### Timeouts {#timeouts}

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

In rare cases where a 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 [Transaction Responses with an 'UNKNOWN' Status](https://developer.mastercard.com/mastercard-send-funding/documentation/response-error-codes/unknown-response/index.md).