# Quick Start Guide source: https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/quick-start-guide/index.md This guide walks you through every step required to go from zero to a working Enhanced Currency Conversion Calculator API integration in Sandbox, and then on to Production. ## Prerequisites {#prerequisites} * A [Mastercard Developers](https://developer.mastercard.com/) account. * For **Sandbox** testing, no special eligibility is required --- any Mastercard Developers account can create a project and call the Sandbox stubs. * For **Production** access, you must be a registered Mastercard issuing customer located in the European Economic Area (EEA) with an Interbank Card Association (ICA) number. See [Service-Specific Configuration](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/quick-start-guide/index.md#6-service-specific-configuration) below. ## 1. Create a Sandbox Project {#1-create-a-sandbox-project} Sign in to [Mastercard Developers](https://developer.mastercard.com/dashboard) and create a new project, selecting **Enhanced Currency Conversion Calculator API** from the **Choose API** list. This single project provides both your Sandbox keys now and your Production keys later. For the full click-by-click walkthrough, see [How to Create a Project](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/tutorials-and-guides/how-to-create-a-project-tutorial/index.md). ## 2. Generate Credentials {#2-generate-credentials} When your project is created, Mastercard automatically generates your Sandbox OAuth 1.0a signing key. Download the **PKCS#12 (.p12)** keystore and make a note of the **Keystore Password** , **Key Alias** , and **Consumer Key** shown on the project page --- you will need all three to sign requests. Tip: If you prefer to control your own private key, you can discard the Mastercard-generated keys and renew them using your own Certificate Signing Request (CSR) instead. See [API Basics](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-basics/index.md#api-keys-and-access). ## 3. Configure Authentication {#3-configure-authentication} The Enhanced Currency Conversion Calculator API signs every request using **OAuth 1.0a** . Use your Consumer Key and `.p12` file with one of Mastercard's [OAuth 1.0a signing libraries](https://github.com/Mastercard/oauth1-signer-java) to generate the `Authorization` header for each call --- do not implement the signing algorithm yourself. For background on how OAuth 1.0a signing works for Mastercard APIs, see [Authentication](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-basics/index.md#authentication). ## 4. Generate an API Client {#4-generate-an-api-client} Use the OpenAPI specification with [OpenAPI Generator](https://openapi-generator.tech) (or an SDK of your choice) to generate a typed API client, then wire in the OAuth 1.0a signing library from Step 3. [swaggerui.yaml](https://static.developer.mastercard.com/content/enhanced-currency-conversion-calculator/swagger/swaggerui.yaml) (24KB) Alternatively, download the [Reference Application](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/developer-tools/reference-app/index.md) for a working example that already includes request signing. ## 5. Test the Sandbox {#5-test-the-sandbox} The fastest way to see a live response is to use the **Execute** button on the [API Reference](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-reference/index.md) page --- it calls the Sandbox for you without needing a project or keys. To call the Sandbox yourself with your signed client, send: * Request ```Request GET https://sandbox.api.mastercard.com/enhanced/settlement/currencyrate/subscribed/summary-rates ?rate_date=2023-02-27 &trans_curr=GBP &trans_amt=100 &crdhld_bill_curr=EUR Authorization: OAuth oauth_consumer_key="", oauth_signature="", ... ``` Expected response (`200 OK`): * JSON ```JSON { "name": "mastercard-and-ecb-currency-conversion-rates", "description": "Provides Mastercard currency conversion rate, calculated cardholder billing amount, the ECB reference rates and the calculated percentage difference between Mastercard and ECB rates for a provided currency pair", "requestDate": "2023-02-27 10:04:18", "data": { "transCurr": "GBP", "crdhldBillCurr": "EUR", "rateDate": "2023-02-27", "transAmt": 100, "mastercard": { "mastercardFxRateDate": "2023-02-27", "mastercardConvRateInclPctFee": 1.1339231, "mastercardConvRateExclAllFees": 1.2048193, "crdhldBillAmtInclAllFees": 113.39231, "crdhldBillAmtExclAllFees": 111.50 }, "ecb": { "ecbReferenceRateDate": "2023-02-27", "ecbReferenceRate": 1.1305 }, "effectiveConversionRate": 1.1339231, "pctDifferenceMastercardExclAllFeesAndEcb": 1.3931, "pctDifferenceMastercardInclAllFeesAndEcb": 0.3072 } } ``` The Sandbox returns simulated, static responses so you can validate your integration end-to-end before requesting Production access. For the full range of positive and negative scenarios to try, see [Testing](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/testing/index.md). ## 6. Service-Specific Configuration {#6-service-specific-configuration} The Enhanced Currency Conversion Calculator API is available only to Mastercard issuers located in the European Economic Area (EEA). Before you can move to Production: * You must be a registered Mastercard issuing customer with a valid Interbank Card Association (ICA) number. If you are an existing customer but don't know your ICA, you can find it by logging into [Mastercard Connect](https://www.mastercardconnect.com/). * Access is subscription-based --- issuers are charged a quarterly subscription fee (currently EUR 1,250). See AN 3493 on Mastercard Connect \> Technical Resource Center for current pricing. This eligibility and subscription check happens as part of the Production access review in Step 7 --- you do not need to complete it before testing in Sandbox. ## 7. Promote to Production {#7-promote-to-production} Once you have successfully tested in Sandbox, click **Request Production Access** on your project dashboard. Mastercard reviews the request, including your ICA and EEA-issuer eligibility, and notifies you by email once it is approved. Mastercard access review and approval are completed within seven business days. Once we have reviewed and approved your request, you will receive the approval email. Now your Production credential are activated, you are ready to go live with your API integration. Note: If the access review is not completed within seven business days, contact your Mastercard Account Representative or select **Get Help** from the [Support](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/support/index.md) page. For the full walkthrough, including generating your Production OAuth key, see [How to Move to Production](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/tutorials-and-guides/how-to-move-to-production-tutorial/index.md) and [Onboarding Checklist](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/tutorials-and-guides/onboarding-checklist/index.md). ## Next Steps {#next-steps} | Category | Description | |--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | [Use Cases](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/use-cases/index.md) | Common use cases and their implementations, including sequence diagrams. | | [Testing](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/testing/index.md) | Positive and negative test cases for every endpoint. | | [API Reference](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-reference/index.md) | Try the Sandbox APIs directly from your browser. | | [Support](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/support/index.md) | FAQs and support. |