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

The Payment Acceptance API is an HTTP‑based, RESTful API that uses OAuth 1.0a with RSA‑based request signing for client authentication and supports end‑to‑end payload encryption to protect sensitive data.

This section explains the core concepts required to integrate with the Payment Acceptance API, including authentication, encryption, and environment configuration.

## Client Authentication {#client-authentication}

Warning: **Key Expiry:** Mastercard Payment Acceptance Sandbox and Production Keys will expire after one year. You will have to generate a new set of keys after they expire.

|          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. |

Mastercard Payment Acceptance uses OAuth 1.0a for API client authentication. Every request sent to Mastercard requires an RSA‑signed OAuth signature. This process requires the generation of an RSA public--private key pair consisting of:

1. A **private key** used for generating OAuth request signatures. Storing the private key in a password‑protected or hardware‑backed keystore is recommended.
2. A **public key** uploaded to Mastercard during project setup, either through a Certificate Signing Request (CSR) or the API Key Generator. The public key is used by Mastercard to verify the OAuth signature included with each API request.

* Requests with a body must be signed using the [Google request body hash extension](https://tools.ietf.org/id/draft-eaton-oauth-bodyhash-00.html) for OAuth.
* The OAuth keys are created during the process of project creation on [Mastercard Developers](https://developer.mastercard.com/dashboard). Additionally, you can add new OAuth keys inside your project dashboard if needed.

Client authentication libraries can be found on [GitHub](https://github.com/Mastercard?&q=oauth), with how-to information provided in the [README.md](https://github.com/Mastercard/oauth1-signer-java/blob/master/README.md) files.
Tip: Do you want to learn more about the authentication scheme Mastercard uses? If so, 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 is secured by default when transmitted across networks. In addition, Mastercard uses end‑to‑end payload encryption to encrypt sensitive data such as personally identifiable information (PII).
Note: Visit [Securing sensitive data using payload encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) to learn more about our encryption methods.

### Payload Encryption {#payload-encryption}

To ensure secure data transfer with the Payment Acceptance API, sensitive fields in payloads must be encrypted. Mastercard further encrypts all sensitive information. As a Creditor Agent handling sensitive business information, retrieved payment instruction data must be decrypted.

The Payment Acceptance API service uses Mastercard encryption to secure payloads.  

Refer to the [Mastercard encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#mastercard-encryption) section to learn more about the payload encryption.

## Event notification security {#event-notification-security}

Event notifications provide a mechanism for the Payment Acceptance API Service to notify you when a new event is triggered. To secure these event notifications and provide you with the ability to trust the Payment Acceptance API before receiving these notifications, Mastercard supports Mutual TLS (MTLS) authentication.

Mastercard recommends customers rely on the CA trusted method of verification. This approach enables comparatively smoother implementation or renewal of certificates in future for customers.

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

### Generating your own Payment Acceptance API client {#generating-your-own-payment-acceptance-api-client}

Create customizable API clients from the Payment Acceptance API specification and let Mastercard open-source client libraries handle the authentication for you. This approach offers the most flexibility and is strongly recommended.

To generate your own client, refer to the guide: [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) using:

1. The Payment Acceptance API specification file:
   [payment_acceptance_api.yaml](https://static.developer.mastercard.com/content/payment-acceptance-api/swagger/payment_acceptance_api.yaml) (119KB)

2. An API client library generated using [OpenAPI Generator](https://openapi-generator.tech/docs/installation/) and the development framework of your choice. (also refer to: [Generators List](https://openapi-generator.tech/docs/generators/))

* Sh

```Sh
{
openapi-generator-cli generate -g java -i payment_acceptance_api.yaml -o api_client
}
```

3. The following field‑level encryption configuration applies to endpoints that process sensitive data.

* Java

```Java
public FieldLevelEncryptionConfig getConfig() {
    FieldLevelEncryptionConfig config;
    try {
        Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(clientEncryptionCertificate);
        PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(mastercardEncryptionPkcs12KeyFile, mastercardEncryptionKeyAlias, mastercardEncryptionKeystorePassword);
        config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
                .withEncryptionCertificate(encryptionCertificate)
                .withEncryptionPath("$.paymentInformation.creditTransferTransactionInformation.supplementaryData.envelope.cardDetails", "$.paymentInformation.creditTransferTransactionInformation.supplementaryData.envelope.encryptedCardDetails")
                .withDecryptionKey(decryptionKey)
                .withDecryptionPath("$.paymentInformation.creditTransferTransactionInformation.supplementaryData.envelope.encryptedCardDetails", "$.paymentInformation.creditTransferTransactionInformation.supplementaryData.envelope.cardDetails")
                .withDecryptionPath("$.data.paymentInformation.creditTransferTransactionInformation.supplementaryData.envelope.encryptedCardDetails", "$.data.paymentInformation.creditTransferTransactionInformation.supplementaryData.envelope.cardDetails")
                .withOaepPaddingDigestAlgorithm("SHA-256")
                .withEncryptedValueFieldName("encryptedValue")
                .withEncryptedKeyFieldName("encryptedKey")
                .withIvFieldName("iv")
                .withOaepPaddingDigestAlgorithmFieldName("oaepPaddingDigestAlgorithm")
                .withEncryptionKeyFingerprintFieldName("publicKeyFingerprint")
                .withFieldValueEncoding(FieldLevelEncryptionConfig.FieldValueEncoding.BASE64)
                .build();
    } catch (EncryptionException | GeneralSecurityException | IOException e) {
        throw new CommonException(e.getMessage(), e);
    }
    return config;
}
```

4. Configure your client using our [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries) which are available in several languages. We recommend that you utilize these libraries to encrypt the sensitive data used by this service.

## Environment Descriptions {#environment-descriptions}

The table describes the two different environments that are available.

|               Environment                |                         Base URL                         |                                                                                                                                                                                          Description                                                                                                                                                                                           |
|------------------------------------------|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox - MTF (Mastercard Test Facility) | `https://sandbox.api.mastercard.com/commercial/payments` | The sandbox environment is an open, self-service test environment where developers can experiment with API calls without affecting real data or systems, ensuring that any errors or issues can be safely identified and resolved. To access Sandbox, select 'Payment Acceptance' when setting up My Projects and create your project keys and ensure you have received appropriate approvals. |
| Production                               | `https://api.mastercard.com/commercial/payments`         | The production environment is the live environment setting where the API interacts with actual users and the data environment. To access production, you need to select [Request Production Access](https://developer.mastercard.com/dashboard) in the Reference Service project you have set up.                                                                                              |

## Next Steps {#next-steps}

Now that you have an understanding of the services authentication and encryption, proceed to the [Use Cases](https://developer.mastercard.com/payment-acceptance-api/documentation/use-cases/index.md) section to learn about the different use cases of the service.