# API Basics source: https://developer.mastercard.com/donations/documentation/api-basics/index.md ## Overview {#overview} The Donate API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns [JSON-encoded](https://www.json.org/json-en.html) responses, and uses standard HTTP response codes, authentication, and verbs. ## API Security {#api-security} ### Client authentication {#client-authentication} | Authentication Protocol | Details | |--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [OAuth 1.0a](https://oauth.net/core/1.0a/) | The Mastercard Donate API uses API keys to authenticate requests. Mastercard uses one-legged OAuth 1.0a for authenticating and authorizing client applications. It means that every request sent to us must be digitally signed, and only requests with valid signatures created by authorized clients are granted access to our services. | 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. The private key is used to encrypt the signature base string hash, and is decrypted using the public key at the server. 2. A **public key** is shared with Mastercard during the project setup as a certificate signing request (CSR). Mastercard uses 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://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. Additionally, you can add new OAuth keys inside your project dashboard if needed. Tip: Do you want to learn more about the authentication scheme Mastercard uses? For that, read out [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/using-oauth-1a-to-access-mastercard-apis) guide. ## Transport Encryption {#transport-encryption} The transport between client applications and Mastercard is secured using HTTPS [Transport Layer Security v1.2+](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is secured by default when transmitted across networks. However, Mastercard additionally uses end-to-end payload encryption to encrypt sensitive data such as Personally Identifying Information (PII). The Donate API uses POST requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Donate API is served over HTTPS TLS/SSL to ensure data privacy. HTTP and HTTPS with transport layer security versions below 1.2 are not supported. All requests must include a `Content-Type` of `application/json` and the body must be a valid JSON. Tip: Visit [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/securing-sensitive-data-using-payload-encryption/) to learn more about our encryption methods. ## Environment Descriptions {#environment-descriptions} The table below describes three different environments that are available: | Environment | Description | |----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Sandbox** | The Sandbox environment allows customers to immediately begin building their solution which can be easily moved to the MTF or Production environments without having to make code changes. This is just a test environment where developers can play around with the APIs and have basic setup ready to get some hold on how Mastercard Donate works. To know how to onboard and access the sandbox enviroment, refer to the [Generate credentials and create a Sandbox Project](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md#generate-credentials-and-create-a-sandbox-project) section in the [Quick Start Guide](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md). Note: You cannot test recurring donations such as Roundup and Micro using Sandbox due to constraints on downstream systems. | | **MTF** | The MTF environment is a pre-prod environment for testing your solutions. To know how to onboard and access the MTF environment, refer to the [Integrate](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md#integrate) and [Go-Live](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md#go-live) sections in the [Quick Start Guide](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md). Note: You can test recurring donations such as Roundup and Micro in the MTF environment as well. | | **Production** | The production environment provides the latest production API release. It is a real-time environment for end users to do their activities. To know how to move to production, refer to the [Integrate](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md#integrate) and [Go-Live](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md#go-live) sections in the [Quick Start Guide](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md). | ### Environment Domains {#environment-domains} * Sandbox * MTF * Production ```Sandbox https://sandbox.api.mastercard.com/donations ``` ```MTF https://mtf.api.mastercard.com/donations ``` ```Production https://api.mastercard.com/donations ``` ### 3D Secure (3DS) Authentication {#3d-secure-3ds-authentication} If your card supports 3DS, which adds an additional layer of security, we recommend that you provide the necessary authentication details during our API calls. These authentication details are used by our system to process your transactions securely and efficiently. Tip: By submitting your card details on Mastercard Donate Platform, you consent to having your card information tokenized. This token will be used for all future payments, including any recurring donations you set up through our platform. ## How to Consume the Donate API? {#how-to-consume-the-donate-api} ### Generating your own Donate API client {#generating-your-own-donate-api-client} Create customizable API clients from the Donate 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, refer to 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: * The API specification: [Donation-API-OAS5.7-Spec.yml](https://static.developer.mastercard.com/content/donations/swagger/Donation-API-OAS5.7-Spec.yml) (124KB) * The encryption configuration below (to be used at the *Enable Encryption* step): * Java * C# ```java FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder .aFieldLevelEncryptionConfig() .withEncryptionCertificate(encryptionCertificate) .withEncryptionPath("$", "$") .withEncryptedValueFieldName("encryptedData") .withEncryptedKeyFieldName("encryptedKey") .withOaepPaddingDigestAlgorithmFieldName("oaepHashingAlgorithm") .withOaepPaddingDigestAlgorithm("SHA-256") .withEncryptionKeyFingerprintFieldName("publicKeyFingerprint") .withIvFieldName("iv") .withFieldValueEncoding(FieldLevelEncryptionConfig.FieldValueEncoding.HEX) .build(); ``` ```csharp var fieldLevelEncryptionConfig = FieldLevelEncryptionConfigBuilder.AFieldLevelEncryptionConfig() .withEncryptionCertificate(encryptionCertificate) .withEncryptionPath("$", "$") .withEncryptedValueFieldName("encryptedData") .withEncryptedKeyFieldName("encryptedKey") .withOaepPaddingDigestAlgorithmFieldName("oaepHashingAlgorithm") .withOaepPaddingDigestAlgorithm("SHA-256") .withEncryptionKeyFingerprintFieldName("publicKeyFingerprint") .withIvFieldName("iv") .withFieldValueEncoding(FieldLevelEncryptionConfig.FieldValueEncoding.HEX) .build(); ``` ## Next Steps {#next-steps} Now that you have an understanding of the services authentication and encryption, proceed to the [Quick Start Guide](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md) to learn how to access the API and generate your credentials.