# Quick Start Guide source: https://developer.mastercard.com/presentment/documentation/quick-start-guide/index.md ## Overview {#overview} This guide outlines the steps required to complete account setup, create a project, generate credentials, submit a Sandbox test request for the Offers for Publishers API, and prepare the project for Production access. ### Before you begin {#before-you-begin} * Create a [Mastercard Developers](https://developer.mastercard.com/) account. * Have a secure place to store downloaded OAuth and encryption keys. * Select the testing option to use: The reference application, Postman, or Insomnia ### Checklist {#checklist} | # | Step | What to do | |----|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | 1. | Access the API and generate credentials | Create a Mastercard Developers project, select the required API service, and save your Sandbox credentials and keys. | | 2. | Make your first Sandbox request | Use your Sandbox credentials to send an initial API request and verify authentication, connectivity, and project setup. | | 3. | Obtain a Sandbox Financial Institution Identifier | Use the Sandbox Financial Institution Identifier (f_id 999999) for initial testing until Mastercard assigns an official identifier. | | 4. | Configure and test your integration | Generate and configure an API client, then test the service using the available testing tools and resources. | | 5. | Complete company verification | Complete the company verification process required before requesting Production access. | | 6. | Promote your project to Production | Request Production access, generate Production credentials, and obtain approval before going live. | ## Step 1: Access the API and generate credentials {#step-1-access-the-api-and-generate-credentials} Tip: **OAuth 2.0:** The listed instructions support the OAuth 1.0a authentication protocol. For OAuth 2.0 guidance, refer to [Using OAuth 2.0 to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/). 1. Navigate to [Mastercard Developers](https://developer.mastercard.com/) and select **Sign up** to create an account. 2. Activate your account by opening the link sent to your email address, and log in. 3. Open your [My Projects](https://developer.mastercard.com/dashboard) page and select **Create new project**. 4. Name your project. 5. Indicate whether you are creating a project on behalf of a customer. Note: Check **Yes** if you are creating an API integration project for a customer. For example, you could be an integrator, a processor, or a service provider and the customer could be a merchant, issuer, or acquirer. 6. Provide the customer company name and customer company address (if applicable). 7. Select your API service: * **Offers for Publishers** * **User Account Administration** Note: The **User Account Administration** service requires the following: * Generation of encryption certificates to securely encrypt and decrypt requests and responses. For more information, refer to this [tutorial](https://developer.mastercard.com/presentment/tutorial/create-sandbox-project/index.md). * Conversion of the Mastercard encryption key PKCS#12 key as an RSA key. For more information, refer to Step 3 within the [User Account Administration Integration and Testing Tutorial](https://developer.mastercard.com/presentment/tutorial/user-account-admin-integration-and-testing/index.md). 8. Download and securely store your PKCS#12 (`.p12`) keystore file. 9. Create a key alias and keystore password, and retain these details for future access. 10. Save your Sandbox credentials. ## Step 2: Make your first Sandbox request {#step-2-make-your-first-sandbox-request} Once you have Sandbox credentials, make a simple request to confirm that your project is set up correctly. Before you run the request, make sure that you have: * Your Sandbox consumer key. * Your Sandbox `.p12` keystore file and its password. * Python 3 with the Mastercard OAuth 1.0a signer installed: `pip install mastercard-oauth1-signer requests`. The signer generates `oauth_timestamp`, `oauth_nonce`, and `oauth_signature`. ### Presentment example {#presentment-example} This first-call example uses `POST /access-tokens`, so you can verify access, OAuth signing, and the Sandbox base URL before moving on to encrypted flows. Note: For a full client setup, including encryption configuration, refer to the [API Basics](https://developer.mastercard.com/presentment/documentation/api-basics/index.md) section. Use the tabs to view the Sandbox request and response for Presentment. Replace the three placeholder values with your Sandbox credentials, then run the script. ```python import json import requests import oauth1.authenticationutils as authenticationutils from oauth1.oauth import OAuth CONSUMER_KEY = "YOUR_SANDBOX_CONSUMER_KEY" KEYSTORE_PATH = "/path/to/your-sandbox-key.p12" KEYSTORE_PASSWORD = "YOUR_KEYSTORE_PASSWORD" url = "https://sandbox.api.mastercard.com/loyalty/offers/presentment/access-tokens" body = json.dumps({ "fiId": "999999", "userId": "1PCLOSANDBOXBCN00002tra6athatR", "utcOffset": "-07:00" }) signing_key = authenticationutils.load_signing_key(KEYSTORE_PATH, KEYSTORE_PASSWORD) authorization = OAuth.get_authorization_header(url, "POST", body, CONSUMER_KEY, signing_key) response = requests.post( url, data=body, headers={ "Authorization": authorization, "Content-Type": "application/json", "Accept": "application/json" } ) print(response.status_code) print(response.json()) ``` Expected result: the script prints `200` and a response body containing a non-empty `accessToken` value. If you receive `401`, confirm your consumer key and keystore password, then refer to [Code and Formats](https://developer.mastercard.com/presentment/documentation/code-and-formats/index.md). ```json { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaUlkIjoiOTk5OTk5IiwidXNlclJlZiI6IjExOWY0Mzk1LTBjYzYtNGMxOS05ODc5LWRkMzUwZDA4ZGM5OSIsInV0Y09mZnNldCI6Ii0wNzowMCIsInVzZXJJZCI6IjFQQ0xPU0FOREJPWEJDTjAwMDAydHJhNmF0aGF0UiIsInVzZXJTdGF0dXMiOiJFWElTVElORyIsImlhdCI6MTc4NDE2ODA1MjAxNCwiY2FyZEF0dHJpYnV0ZXMiOm51bGwsImxhdGl0dWRlIjpudWxsLCJsb25naXR1ZGUiOm51bGwsInBvc3RhbENvZGUiOm51bGwsImNvdW50cnlDb2RlIjpudWxsLCJlb3BQcm9ncmFtIjpudWxsfQ.eWZhNXdIT3k0aGJncW5XRmgvb0wvVXdIZ01WVUdCZmdlTHlUUExhOEJ6MD0" } ``` Note: The response value is used as the `x-auth-token` in all subsequent requests. ### User Account Administration example {#user-account-administration-example}
This first-call example uses `POST /enrollments/eligibilities/searches`, so you can verify access, OAuth signing, and the Sandbox base URL before moving on to encrypted flows. Note: For a full client setup, including encryption configuration, refer to the [API Basics](https://developer.mastercard.com/presentment/documentation/api-basics/index.md) section. Use the tabs to view the Sandbox request and response for User Account Administration. ```json { "ban": "5330333671236516", "enrollmentType": "TARGETED", "fiIds": [ 15100 ], "includeEnrollmentExist": true, "includeProductDetails": true, "programType": "MTR" } ``` Expected result: `200 OK` and a response body indicating eligibility status of enrollment ```json { "items": [ { "enrollmentEligible": true, "fiId": "15100", "bankProductCode": "FIDOCASHBACK", "enrollmentRecordExists": true, "directIntegrationOnboarded": true, "programIdentifier": "PGM42051", "includeProductDetails": true, "mastercardProductDetails": { "issuerIca": "00000030642", "issuerName": "Fifth Third Bank, The", "cardIssuedCountryCode": "USA", "cardIssuedCountryName": "United States", "productCardType": "Consumer", "productCategory": "Credit", "brandProductCode": "MPL" }, "userId": "116a70c264034c3e945da8229c4030", "userIdType": "CRK", "accountId": "6fe2875af0794ecdaac8156863e7f7", "accountIdType": "ARK" } ] } ``` ## Step 3: Obtain a Sandbox Financial Institution Identifier {#step-3-obtain-a-sandbox-financial-institution-identifier} Testing requires a Financial Institution Identifier, called an f_id, to specify the platform and configuration instance. For initial testing, you can use the Sandbox f_id, 999999. An official f_id is assigned by Mastercard during the implementation phase. ## Step 4: Configure and test your integration {#step-4-configure-and-test-your-integration} ### Generate your own API client {#generate-your-own-api-client} 1. Navigate to the [API Reference](https://developer.mastercard.com/presentment/documentation/api-reference/index.md) section and select [User Account Administration](https://developer.mastercard.com/presentment/documentation/api-reference/user-account-admin/index.md) or [Presentment and platform offers](https://developer.mastercard.com/presentment/documentation/api-reference/presentment-and-platform-offers/index.md). 2. Download the User Account Administration specification or Offers for Publishers API specification (OpenAPI or Swagger). 3. Generate and configure an API client for the selected API. 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). Note: For a detailed guide, refer to the [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/developer-tools/generating-and-configuring-a-mastercard-api-client/) page. ### Test the service {#test-the-service} The service can be tested using the following methods: * [Reference Application](https://developer.mastercard.com/presentment/documentation/developer-tools/reference-application/index.md) * [Postman Collection](https://developer.mastercard.com/presentment/documentation/developer-tools/postman-collection/index.md) * [Insomnia Collection](https://developer.mastercard.com/presentment/documentation/developer-tools/insomnia-collection/index.md) * [Testing](https://developer.mastercard.com/presentment/documentation/testing/index.md) for test cases and additional examples ## Step 5: Complete company verification {#step-5-complete-company-verification} Company verification is a required prerequisite before you can request Production access for a service on Mastercard Developers. This ensures Mastercard is engaging with real organizations, reducing risks related to fraud and regulatory compliance. It also connects your developer activity to your official, pre-existing business relationship with Mastercard for streamlined onboarding and improved transparency. Follow the steps in our [Company Verification guide](https://developer.mastercard.com/platform/documentation/account-management/company-verification/) to complete this step. ## Step 6: Promote your project to Production {#step-6-promote-your-project-to-production} After you have tested your implementation in the Sandbox environments and completed the company verification prerequisite, it is time to move to Production. 1. Within your project, select **Request Production Access**. 2. Enter your Production key alias and keystore password. 3. Save your key alias and keystore password for future reference. 4. Confirm and download your Production keys. Note: Production Credentials are generated instantaneously, but they still need to be approved for Production environment access before you can go live. Once your Production access request has been reviewed, you receive a notification confirming your access has been approved or denied. For the complete onboarding process including contracting, Sandbox (MTF), service‑level agreements (SLAs), and escalation procedures, refer to the [Onboarding Checklist](https://developer.mastercard.com/presentment/documentation/tutorials-and-guides/onboarding-checklist/index.md). ## Next steps {#next-steps} Continue with the documentation that matches your next task: * [API Basics](https://developer.mastercard.com/presentment/documentation/api-basics/index.md) for authentication, encryption, and client configuration * The [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) section to learn more about supported use cases for User Account Administration, Presentment offers, Platform offers * [API Reference](https://developer.mastercard.com/presentment/documentation/api-reference/index.md) for endpoint details * [Testing](https://developer.mastercard.com/presentment/documentation/testing/index.md) for additional request scenarios * [Tutorials and Guides](https://developer.mastercard.com/presentment/documentation/tutorials-and-guides/index.md) to learn how to set up a Sandbox environment and test Offers for Publishers User Account Administration integrations. * [Onboarding Checklist](https://developer.mastercard.com/presentment/documentation/tutorials-and-guides/onboarding-checklist/index.md) for the full operational go-live process