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

## API Security {#api-security}

### Client Authentication {#client-authentication}

Warning: **Key Lifecycle:** Transactions Service supports both OAuth 1.0a and OAuth 2.0. You can renew or rotate Sandbox and Production keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard). You do not need to create a new project each time keys are updated.

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

1. A **private key** for the OAuth signature for API requests. It is recommended to keep the private key in a password-protected or hardware keystore. Data encrypted using a public key can only be decrypted using the corresponding private key.
2. A **public key** is shared with Mastercard during the project setup process through either a certificate signing request (CSR) or the API Key Generator. Mastercard will use the public key to verify the OAuth signature that is provided 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.
* The OAuth keys for your project can be set up on your project dashboard here ([Developer Dashboard](https://developer.mastercard.com/dashboard)), after you create a project.

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.

|      Authentication Protocol      |                                                                                                                                      Details                                                                                                                                      |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [OAuth 2.0](https://oauth.net/2/) | Mastercard uses [OAuth 2.0 Authorization](https://datatracker.ietf.org/doc/html/rfc6749) with the [Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4), using the FAPI 2.0 security profile (strong client authentication + DPoP token binding). |

OAuth 2.0 (client credentials) requires your application to request an access token from the authorization server, and call APIs using that access token with DPoP token binding.

Your application needs two sets of key material:

1. An **authentication private key** (from Mastercard Developers) used to sign the client assertion (`private_key_jwt`) for token requests.

2. A **DPoP key pair** generated and stored by your application, used to sign DPoP proofs (per token request and per API call).

* Token requests include a signed client assertion (`private_key_jwt`) and a DPoP proof.
* API calls send `Authorization: DPoP <access_token>` and a fresh DPoP proof per request (including `htm/htu` and `ath`).
* Nonce handling: if you receive `use_dpop_nonce`, retry with the `DPoP-Nonce` value as the `nonce` claim in the next DPoP proof.

Tip: Do you want to learn more about the authentication scheme Mastercard uses? For implementation details and examples, read our [Using OAuth 2.0 to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/) guide. Note: **Dual Authentication Support**

Transactions Service APIs support both OAuth 1.0a and OAuth 2.0 at the project level. A project can be configured to use either protocol individually, or both simultaneously, with no preference or migration requirement implied between them.

## Encryption {#encryption}

The transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is encrypted by default when transmitted across networks. Whereas sensitive data like card numbers (Payment Card Industry Data Security Standard) are sent, the entire request payload should be encrypted using the JWE encryption scheme. For further details,
please refer to [Securing Sensitive Data Using Payload Encryption.](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/)

### Encryption Libraries {#encryption-libraries}

Mastercard has abstracted the encryption scheme into our [client encryption libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries), which are available in several of the most used development languages. We highly recommend that you utilize these libraries to encrypt the sensitive data used by this service.

## How to Consume the Transactions Service? {#how-to-consume-the-transactions-service}

Note: There are multiple ways of integrating with the Transactions Service:

1. Using a generated API client (recommended)
2. Using a method of your choice

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

Create customizable API clients from the Transactions Service 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/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial with the following API specification:
[mrs-transactions-service-swagger.yaml](https://static.developer.mastercard.com/content/transactions-service/swagger/mrs-transactions-service-swagger.yaml) (13KB)

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

Transactions 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/security-and-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 Transactions Service [REST API Reference](https://developer.mastercard.com/transactions-service/documentation/api-reference/index.md).

## Environments {#environments}

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

| **Environment** |                                                                                                                                 **Description**                                                                                                                                 |
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | 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 to authenticate with this environment. The keys are set up when you create your project. |
| Production      | Full production environment containing the latest production API release.                                                                                                                                                                                                       |