# API Basics source: https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-basics/index.md The Enhanced Currency Conversion Calculator API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API returns [JSON-encoded](https://www.json.org/json-en.html) responses and uses standard HTTP response codes, authentication, and verbs. ## Authentication {#authentication} The Enhanced Currency Conversion Calculator API requires all requests to be signed using [**OAuth 1.0a**](https://oauth.net/core/1.0a/). In short * Mastercard uses [**OAuth 1.0a**](https://oauth.net/core/1.0a/) for authenticating client applications * Requests with a body must be signed using the Google Request Body Hash extension for OAuth * OAuth Keys for your project can be set up in your dashboard * Client authentication libraries can be found on GitHub, with how-to information provided in README.md files For further details, see [**Using OAuth 1.0a to Access Mastercard APIs**](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) ## How to Consume the API {#how-to-consume-the-api} You can integrate with the Enhanced Currency Conversion Calculator API in the way that best suits your development workflow: * **Try it in the browser:** Use [API Reference](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-reference/index.md) to send requests directly to the Sandbox without creating a project or keys. * **Generate a client from the OpenAPI specification:** Download the specification below and use a tool such as [OpenAPI Generator](https://openapi-generator.tech) to generate a client in your language of choice, then wire in Mastercard's [OAuth 1.0a signing library](https://github.com/Mastercard/oauth1-signer-java) for authentication. For the full walkthrough, see [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/). [swaggerui.yaml](https://static.developer.mastercard.com/content/enhanced-currency-conversion-calculator/swagger/swaggerui.yaml) (24KB) * **Use the Reference Application or a REST client:** See [Developer Tools](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/developer-tools/index.md) for the downloadable reference application and Postman collection. ## Environments {#environments} There are two Mastercard environments: * **Sandbox:** Sandbox environment is where you access API stubs that return simulated, static responses. * **Production:** Production environment is where you complete testing and launch your solution. | Environment | URL | |-------------|----------------------------------------------------------------------------------| | Sandbox | | | Production | | ## API Keys and Access {#api-keys-and-access} * Mastercard authenticates API requests using your account's API keys. If you do not include your key when making an API request, or use one that is incorrect or outdated, Mastercard returns an error. * Your API keys are available in your project dashboard on [**Mastercard Developers**](https://developer.mastercard.com/). * To renew your Project Keys, go to **My Project dashboard** , click **Actions** , and then click **Renew** . For more details, see [How To Renew Your Project Keys](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/renewing-your-keys/ "Renew"). Warning: All keys created in the Mastercard Developer Portal account expire after one year and must be renewed, otherwise they will be revoked.
The following table outlines the key management activities. Once generated, most of these keys and their certificates are accessible from the API project dashboard, except for the private keys generated offline. | Category | Description | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox Key | Private keys used for API authentication with the Sandbox environments. Mastercard generates the initial set of keys when creating your project; you download the Signing Key via your browser. The project page shows the Consumer Key. If you want to generate and use your own keys, you can discard the Mastercard-generated keys and renew them using your Certificate Signing Request (CSR) file. | | Production Key | Private keys used for API authentication with the Production environment. Mastercard can generate this key set for you when you request Production access; you download the Signing Key via your browser. Alternatively, we recommend that you generate your own keys and upload your CSR file, to ensure you are the only entity possessing your private key. The project page shows the Consumer Key. | **Production Access** When you are ready to move to production, you can request Production access. To request Production access click **Request Production Access** through the project dashboard. Once your production access request has been reviewed, you will receive a notification indicating your access has been approved or denied. The following diagram shows the production environment architecture: ![prod-env-architecture](https://static.developer.mastercard.com/content/enhanced-currency-conversion-calculator/uploads/ecc-architecture.JPG) 1. Verifies authorization of access to production currency rate data 2. Retrieves and returns production currency rate data for authorized client ## Encryption {#encryption} ### Transport Encryption {#transport-encryption} All API endpoints are secured using HTTPS with Transport Layer Security (TLS) 1.2 or higher, ensuring that all data transmitted between clients and the service is encrypted in transit. During each connection, a secure TLS handshake establishes trust using industry-standard digital certificates and negotiates strong encryption algorithms to protect the session. This approach ensures confidentiality (data cannot be read by unauthorized parties), integrity (data cannot be altered in transit), and authenticity (clients are communicating with a trusted endpoint), aligning with modern security standards for enterprise-grade APIs. ### Payload Encryption {#payload-encryption} The Enhanced Currency Conversion Calculator API does not require any additional payload encryption. Requests are simple `GET` calls with query parameters and no request body, so only the OAuth 1.0a signature described above is required. ## Glossary {#glossary} To ensure the best experience when integrating with this service, familiarize yourself with the following conventions. | Category | Description | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| | [Parameters](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/parameters/index.md) | A glossary that explains input and output responses. | | [HTTP Response codes](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/code-and-formats/index.md#http-status-and-reason-codes) | Detailed descriptions on HTTP codes and messages. | | [ISO Currency Codes](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/code-and-formats/index.md#iso-currency-codes) | List of currencies available via the API. |