# Quick Start Guide source: https://developer.mastercard.com/mdes-token-connect/documentation/quick-start-guide/index.md ## Quick Start Guide {#quick-start-guide} This guide takes you from zero to a verified sandbox response in a single linear path. By the end you will have a working Mastercard Developers project and a confirmed successful call to the MDES Token Connect Sandbox. *** ** * ** *** ## Prerequisites {#prerequisites} Before you begin, ensure you have the following: * An existing **MDES integration** --- MDES Token Connect is an add-on to MDES. If you have not yet integrated with MDES, refer to the [MDES Issuer Implementation Guide](https://trc-techresource.mastercard.com/r/bundle/m_mdes_iss_impl_en-us/page/d/en-US/ovo1732530667092.html). * A **Mastercard Developers account** --- [Sign up here](https://developer.mastercard.com/dashboard) if you do not already have one. * An HTTP client capable of generating **OAuth 1.0a signed requests** (e.g. Postman with the Mastercard OAuth 1.0 plugin, or a Mastercard client library). 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/) for details. *** ** * ** *** ## Step 1 --- Create a Sandbox Project {#step-1--create-a-sandbox-project} Note: The Sandbox environment is **NOT instantly accessible** once your project is created. CIS project number is required at this stage. 1. Log in to [Mastercard Developers](https://developer.mastercard.com/dashboard) and click **Create new project**. 2. Enter a **Project name**. 3. Select whether you are creating the project for your own CID or on behalf of a client, then click **Proceed**. 4. From the API dropdown, select **MDES Token Connect** and click **Proceed**. 5. Select the **Sandbox** environment and click **Proceed**. Note: Ignore the Mock option --- MDES Token Connect does not support the Mock test environment. 6. Accept the legal agreements and click **Proceed**. 7. Enter a **Key alias** and **Keystore password** , then click **Proceed**. 8. On the Additional Credentials screen click **Create Project** --- the Client Encryption Key is generated automatically. 9. Click **Download key file** to save your project credentials, then click **Open project**. For the full step-by-step walkthrough with screenshots, see [Creating a Project](https://developer.mastercard.com/mdes-token-connect/documentation/tutorials-and-guides/create-project/index.md). *** ** * ** *** ## Step 2 --- Obtain your Credentials {#step-2--obtain-your-credentials} From the project summary page in Mastercard Developers, locate and note the following: | Credential | Where to find it | |-----------------------------------------|-----------------------------------------------| | **Consumer Key** | Project summary → Sandbox credentials section | | **Signing Key** (`.p12`) | Downloaded in the key file from Step 1 | | **Key Alias** and **Keystore Password** | Values you entered in Step 1 | The **Sandbox base URL** for all MDES Token Connect requests is: https://sandbox.api.mastercard.com/mdes/connect/1/0/ ## Step 3 --- Onboard {#step-3--onboard} Contact your CIS engineer and provide necessary details to onboard on Sandbox (MTF) environment. *** ** * ** *** ## Step 4 --- Make your First API Call {#step-4--make-your-first-api-call} The `getEligibleTokenRequestors` endpoint is the simplest first call --- it requires no payload encryption and returns a meaningful list of Token Requestors available in the Sandbox. **Endpoint:** `POST https://sandbox.api.mastercard.com/mdes/connect/1/0/getEligibleTokenRequestors` Note: The `Authorization` header must contain a valid **OAuth 1.0a signature** generated from your Consumer Key and signing key. Use the [Mastercard OAuth client library](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) or a compatible tool (e.g. Postman) to sign the request before sending. ```bash curl --location --request POST \ 'https://sandbox.api.mastercard.com/mdes/connect/1/0/getEligibleTokenRequestors' \ --header 'Content-Type: application/json' \ --header 'Authorization: OAuth realm="sandbox.api.mastercard.com",oauth_consumer_key="",oauth_token="",oauth_signature_method="RSA-SHA256",oauth_timestamp="",oauth_nonce="",oauth_version="1.0",oauth_signature=""' \ --data-raw '{ "requestId": "123456", "accountRanges": [ 518569007, 520473160 ], "supportsTokenConnect": true }' ``` Replace the placeholder values: | Placeholder | Value | |-----------------------|------------------------------------------------------| | `` | Consumer Key from Step 2 | | `` | Unix timestamp at time of request | | `` | Unique random string for this request | | `` | RSA-SHA256 signature generated by your OAuth library | Tip: Using Postman? Install the [Mastercard OAuth 1.0 Authorization helper](https://developer.mastercard.com/platform/documentation/developer-tools/mastercard-oauth1-signer-postman/) to have the `Authorization` header generated automatically from your `.p12` file. *** ** * ** *** ## Step 5 --- Validate the Response {#step-5--validate-the-response} A successful request returns HTTP **200** with a `tokenRequestors` array. The Sandbox contains pre-configured test Token Requestors --- a response similar to the following confirms your project credentials and sandbox access are working correctly: ```json { "tokenRequestors": [ { "tokenRequestorId": "50153069329", "name": "MERCURY", "consumerFacingEntityName": "ProFilmHub", "tokenRequestorType": "MERCHANT", "enabledAccountRanges": [ 5185690070000000000, 5204731600000000000 ], "supportedPushMethods": [ "WEB" ], "supportsMultiplePushedCards": true, "supportsCardHolderAuthentication": true, "supportsTokenConnect": true, "availablePushMethods": [ { "type": "WEB", "uri": "http://www.tokenrequestor1.com/pushtoken" } ] } ], "responseId": "123456" } ``` If you receive an error response instead, see the troubleshooting table below: | Symptom | Likely cause | Resolution | |-------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | HTTP 401 | Invalid or missing OAuth signature | Verify your Consumer Key and `.p12` file match the project; re-generate the OAuth signature | | `AUTHORIZATION_FAILED` | Incorrect signing key or fingerprint | Re-download the key file and confirm the key alias and keystore password | | `CRYPTOGRAPHY_ERROR` | Wrong encryption certificate or fingerprint | Confirm `publicKeyFingerprint` value --- see [API Basics](https://developer.mastercard.com/mdes-token-connect/documentation/api-basics/index.md) | | Empty `tokenRequestors` array | Account ranges not enabled for Sandbox | Confirm the account ranges passed exist in the MDES Sandbox configuration | For a full list of error codes and their resolution steps, see [Code and Formats](https://developer.mastercard.com/mdes-token-connect/documentation/code-and-formats/index.md). *** ** * ** *** ## Next Steps {#next-steps} Now that you have a verified sandbox connection, continue with the following: | Topic | Where to go | |--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | Encryption setup and API client generation | [API Basics](https://developer.mastercard.com/mdes-token-connect/documentation/api-basics/index.md) | | Implementation Guides | [Tutorials and Guides](https://developer.mastercard.com/mdes-token-connect/documentation/tutorials-and-guides/index.md) | | Use case walkthroughs (push to wallet, merchant, etc.) | [Use Cases](https://developer.mastercard.com/mdes-token-connect/documentation/use-cases/index.md) | | Specification | [API Reference](https://developer.mastercard.com/mdes-token-connect/documentation/api-reference/index.md) |