# Quick Start Guide source: https://developer.mastercard.com/unified-installments/documentation/quick-start-guide/index.md ## Overview {#overview} Use this guide to go from account setup to your first successful Sandbox request for Mastercard Installments API. You will create a project, generate credentials, make a test call, and prepare the same project for Production access. Tip: If you want the fastest path to a working Sandbox request, start with the [Postman Collections page](https://developer.mastercard.com/unified-installments/documentation/developer-tools/postman-collection/index.md). It lets you test Sandbox and Production flows without writing code first. ### 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. * Decide how you want to test: Postman, Insomnia, the reference application, or your own client. ### Sandbox checklist {#sandbox-checklist} | # | Step | What to do | |---|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | Access | Get access to Mastercard Installments API and create your Mastercard Developers project. | | 2 | Credentials | Generate your Sandbox OAuth credentials and record your consumer key. | | 3 | Encryption | Configure JWE payload encryption with your client encryption certificate. `POST /offers` requires the PAN to be encrypted. See [API Basics](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md#encryption). | | 4 | First call | Send your first Sandbox request with OAuth 1.0a signing and JWE encryption, using the Postman collection or the Mastercard client libraries. | | 5 | Validation | Use the sample response and the [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) page to validate test data, positive flows, and negative flows. | | 6 | Production | After you complete Sandbox testing, request Production access for the same project. See [Step 5](https://developer.mastercard.com/unified-installments/documentation/quick-start-guide/index.md#step-5-promote-the-same-project-to-production) and the [Onboarding Checklist](https://developer.mastercard.com/unified-installments/documentation/onboarding-checklist/index.md). | ## Step 1: Get access to the API {#step-1-get-access-to-the-api} 1. Go to [Mastercard Developers](https://developer.mastercard.com/) and 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/create-project) page and start a new project. Sandbox access is open, so you can begin testing as soon as your project credentials are generated. ## Step 2: Create a project and generate Sandbox credentials {#step-2-create-a-project-and-generate-sandbox-credentials} Create a Mastercard Developers project to generate your Sandbox credentials. Sandbox gives you mocked data so you can validate your integration before requesting Production access. ### Project Details {#project-details} 1. Click **Create new project** on your [My Projects](https://developer.mastercard.com/) page. ![Mastercard Installments Project Details](https://static.developer.mastercard.com/content/unified-installments/img/project-detail-01.png) 2. Enter a project name. 3. If prompted, indicate whether you are creating the project on behalf of a client. 4. In the **Select at least one API** field, choose **Mastercard Installments API**. ### Project Credentials {#project-credentials} 5. In **Project Credentials** , create a key alias and keystore password for your OAuth keys, record them securely, and click **Proceed**. ![Select OAuth Type](https://static.developer.mastercard.com/content/unified-installments/img/project-creds-02.png) ### Additional Credentials {#additional-credentials} 6. Create a key alias and keystore password for your encryption keys, record them securely, and click **Create Project** . ![Encryption key credentials](https://static.developer.mastercard.com/content/unified-installments/img/add-creds-03.png) 7. Download the OAuth 1.0a signing key (`.p12`) and the client encryption certificate (`.pem`), and store them in a safe place. Then click **Open Project**. ### Save the values you will need {#save-the-values-you-will-need} 8. On the project dashboard, record the following values: * Sandbox and Production status * Authentication consumer key * Client encryption key fingerprint ![Summary](https://static.developer.mastercard.com/content/unified-installments/img/summary-1.png) ## Step 3: Configure Sandbox and make your first request {#step-3-configure-sandbox-and-make-your-first-request} Once you have Sandbox credentials, configure OAuth 1.0a signing and JWE payload encryption, then call `POST /offers` to verify that your project is set up correctly. ### Sandbox environment {#sandbox-environment} * Use the Sandbox base URL: `https://sandbox.api.mastercard.com/installments`. * For all environments and base URLs, see [Environment Descriptions](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md#environment-descriptions). Note: **Sandbox and MTF are the same environment.** The Sandbox is Mastercard's Test Facility (MTF), so both terms refer to the pre-Production test environment at `https://sandbox.api.mastercard.com/installments`. Use this base URL for all Sandbox/MTF testing, and switch to `https://api.mastercard.com/installments` only for Production. Some sample responses reference `mtf.installments.mastercard.com` URLs (for example, provider logos), which are test-only assets served from that same environment. ### Configure authentication and encryption {#configure-authentication-and-encryption} Before you run the request, make sure you have: * Your Sandbox consumer key * Your OAuth signing key (`.p12` file, key alias, and keystore password) * Your client encryption certificate (`.pem` file) Every request must be signed with OAuth 1.0a. `POST /offers` also requires JWE payload encryption. The Mastercard client encryption library encrypts the `sensitiveData` object and sends the result in the `encryptedValue` field, so you do not build the JWE yourself. For the full configuration, see [Authentication](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md#authentication) and [Encryption](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md#encryption). ### Request {#request} **GIVEN** : The consumer has access to the Mastercard Installments API and has integrated their solution or application with the [/installments/offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#apis) endpoint. **WHEN** : The consumer backend system makes a REST call to the `/installments/offers` endpoint. **THEN** : The consumer should receive details of all the eligible offers based on the following criteria: * amount * currency * localdatetime * country * mcc * url * acquirerId * merchantId * PAN (sent in `sensitiveData`, which is encrypted into `encryptedValue`) #### URL {#url} ```cli https://sandbox.api.mastercard.com/installments/offers ``` #### Request headers {#request-headers} Send the following headers with every request: | Header | Value | Purpose | |-----------------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | `Authorization` | `OAuth oauth_consumer_key="...", oauth_nonce="...", oauth_timestamp="...", oauth_signature="...", ...` | OAuth 1.0a signature generated by your Mastercard signer. | | `Content-Type` | `application/json` | Declares a JSON request body. | | `Accept` | `application/json` | Requests a JSON response. | #### Request body {#request-body} Write the request with `sensitiveData` in clear text. The JWE configuration encrypts it before the request is sent. * JSON ```JSON { "transaction": { "amount": 150, "currency": "USD", "localDateTime": "2025-08-03T16:55:43Z" }, "merchant": { "name": "Globex Decor", "country": "USA", "mcc": "1711", "url": "https://www.globexdecor.com", "acquirerId": 234353, "merchantId": "121234" }, "sensitiveData": { "consumer": { "primaryAccountNumber": 2303770000057107 } } } ``` After encryption, the body sent to Mastercard replaces `sensitiveData` with `encryptedValue`: * JSON ```JSON { "transaction": { "amount": 150, "currency": "USD", "localDateTime": "2025-08-03T16:55:43Z" }, "merchant": { "name": "Globex Decor", "country": "USA", "mcc": "1711", "url": "https://www.globexdecor.com", "acquirerId": 234353, "merchantId": "121234" }, "encryptedValue": "eyJraWQiOiI3NjFiMDAzYzFlYWRlM(...).Y+oPYKZEMTKyYcSIVEgtQw" } ``` ### Send the request {#send-the-request} Choose one of the following options. Both sign the request with OAuth 1.0a and encrypt `sensitiveData` with JWE. #### Option A: Postman {#option-a-postman} 1. Fork the Mastercard Installments API collection from the [Postman Collection](https://developer.mastercard.com/unified-installments/documentation/developer-tools/postman-collection/index.md) page. 2. Select the **Mastercard API Sandbox Environment with JWE Encryption** environment. 3. Set `baseUrl` to `https://sandbox.api.mastercard.com/installments`, and set `consumerKey`, `privateKey`, `publicKeyFingerprint`, and `encryptionCert` from your project. 4. Set `pathToRawData` to `$.sensitiveData`, `pathToEncryptedData` and `encryptedValueFieldName` to `encryptedValue`, and `encryptionType` to `jwe`. 5. Open the `POST /offers` request, paste the request body above, and select **Send**. #### Option B: Java with the Mastercard client libraries {#option-b-java-with-the-mastercard-client-libraries} Add the `com.mastercard.developer:oauth1-signer`, `com.mastercard.developer:client-encryption`, and `com.squareup.okhttp3:okhttp` dependencies, then run: * Java ```java PrivateKey signingKey = AuthenticationUtils.loadSigningKey( "path/to/sandbox-signing-key.p12", "", ""); Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate( "path/to/client-encryption-certificate.pem"); JweConfig jweConfig = JweConfigBuilder.aJweEncryptionConfig() .withEncryptionCertificate(encryptionCertificate) .withEncryptionPath("$.sensitiveData", "$") .withEncryptedValueFieldName("encryptedValue") .build(); // Encrypt first so the OAuth body hash covers the encrypted payload. OkHttpClient client = new OkHttpClient.Builder() .addInterceptor(new OkHttpJweInterceptor(jweConfig)) .addInterceptor(new OkHttpOAuth1Interceptor("", signingKey)) .build(); Request request = new Request.Builder() .url("https://sandbox.api.mastercard.com/installments/offers") .header("Accept", "application/json") .post(RequestBody.create(MediaType.parse("application/json"), requestBodyJson)) .build(); try (Response response = client.newCall(request).execute()) { System.out.println(response.code() + " " + response.body().string()); } ``` Replace the placeholders with your Sandbox values, and set `requestBodyJson` to the request body above. ### Response {#response} * JSON ```JSON { "offers": [ { "apr": 15.36, "currencySymbol": "$", "feeDistribution": "FRST_INSTL", "feeType": "FIXED_AMT", "feeValue": 10, "countryCode": "USA", "firstInstallmentAmount": 22.5, "firstInstallmentSchedule": "TRANSCTN_DATE", "frequency": "MONTHLY", "interestRate": 0, "objectType": "OfferGroupAndPriority", "offerBeginDatetime": "2025-05-21T15:00:00-04:00", "offerDisplayText": "12 monthly payments of $12.50", "offerEndDatetime": "2029-12-31T18:59:59-05:00", "offerId": "71392364", "offerType": "CARDED_OFFER", "oneTimeFeeAmount": 10, "otherInstallmentAmount": 12.5, "priority": 1, "provider": { "cid": "242666", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "providerLogoUrl": "https://mtf.installments.mastercard.com/mtf/Mast_b3136bef-1f6f-4fae-8732-3cd539f30d91.png", "providerName": "Mastercard - Operations and Technology - BizOps", "disclosure": "Disclosure: This offer is part of a testing environment and is not valid for actual transactions. All Terms & Conditions displayed are for simulation purposes only.", "disclosureLinks": [ { "linkText": "Terms and Conditions", "linkUrl": "https://www.mastercard.com/us/en/terms-of-use.html" } ] }, "schedulePayments": [ { "installmentAmount": 22.5, "installmentNumber": 1 }, { "installmentAmount": 12.5, "installmentNumber": 2 }, { "installmentAmount": 12.5, "installmentNumber": 3 }, { "installmentAmount": 12.5, "installmentNumber": 4 }, { "installmentAmount": 12.5, "installmentNumber": 5 }, { "installmentAmount": 12.5, "installmentNumber": 6 }, { "installmentAmount": 12.5, "installmentNumber": 7 }, { "installmentAmount": 12.5, "installmentNumber": 8 }, { "installmentAmount": 12.5, "installmentNumber": 9 }, { "installmentAmount": 12.5, "installmentNumber": 10 }, { "installmentAmount": 12.5, "installmentNumber": 11 }, { "installmentAmount": 12.5, "installmentNumber": 12 } ], "selectable": false, "tenure": 12, "totalAmount": 160, "totalFeeAmount": 10, "totalInterestAmount": 0, "totalInterestAndFeeAmount": 10, "transactionCurrency": "USD" }, { "apr": 23.68, "countryCode": "USA", "currencySymbol": "$", "feeDistribution": "ALL_INSTL", "feeType": "PRCENTG", "feeValue": 1.5, "firstInstallmentAmount": 25.4, "firstInstallmentSchedule": "DELAY_RE_PYMNT", "frequency": "WEEKLY", "interestRate": 1.25, "objectType": "OfferGroupAndPriority", "offerBeginDatetime": "2025-05-21T15:00:00-04:00", "offerDisplayText": "6 weekly payments of $25.40", "offerEndDatetime": "2029-12-31T18:59:59-05:00", "offerId": "71392362", "offerType": "CARDED_OFFER", "otherInstallmentAmount": 25.4, "recurringFeeAmount": 0.38, "priority": 2, "provider": { "cid": "242666", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "providerLogoUrl": "https://mtf.installments.mastercard.com/mtf/Mast_b3136bef-1f6f-4fae-8732-3cd539f30d91.png", "providerName": "Mastercard - Operations and Technology - BizOps", "disclosure": "Disclosure: This offer is part of a testing environment and is not valid for actual transactions. All Terms & Conditions displayed are for simulation purposes only.", "disclosureLinks": [ { "linkText": "Terms and Conditions", "linkUrl": "https://www.mastercard.com/us/en/terms-of-use.html" } ] }, "schedulePayments": [ { "installmentAmount": 25.4, "installmentNumber": 1 }, { "installmentAmount": 25.4, "installmentNumber": 2 }, { "installmentAmount": 25.4, "installmentNumber": 3 }, { "installmentAmount": 25.4, "installmentNumber": 4 }, { "installmentAmount": 25.4, "installmentNumber": 5 }, { "installmentAmount": 25.4, "installmentNumber": 6 } ], "selectable": false, "tenure": 6, "totalAmount": 152.4, "totalFeeAmount": 2.25, "totalInterestAmount": 0.12, "totalInterestAndFeeAmount": 2.37, "transactionCurrency": "USD" } ], "offerTransactionId": "473848442280480768", "total": 2 } ``` ### What success looks like {#what-success-looks-like} * The request returns `200 OK`. * The response body lists the eligible offers that match the request criteria. * Each offer includes an `offerId`, an `offerType`, and the installment schedule in `schedulePayments`. * The response includes an `offerTransactionId`. Use it with an `offerId` to create a plan with `POST /plans`, as described in the [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) page and the [Post Purchase](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/post-purchase/index.md) use case. > **Test data:** The sandbox includes pre-loaded available testing data. See [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) for additional scenarios. Tip: If the test fails, check these three items: * [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) * [API Basics](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md) * [Codes and Formats](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md) ## Step 4: Choose how you want to test and integrate {#step-4-choose-how-you-want-to-test-and-integrate} After the first Sandbox request succeeds, pick the integration path that matches your workflow: * **Postman or Insomnia:** Use the [Postman Collections page](https://developer.mastercard.com/unified-installments/documentation/developer-tools/postman-collection/index.md) or [Insomnia Collection](https://developer.mastercard.com/unified-installments/documentation/developer-tools/insomnia-collection/index.md) page for setup. * **Reference Application:** Use the [Reference Application](https://developer.mastercard.com/unified-installments/documentation/developer-tools/reference-app/index.md) page. * **curl or a custom client:** Use the [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) page for test cases and additional examples. ## Step 5: Promote the same project to Production {#step-5-promote-the-same-project-to-production} Once your project is working in Sandbox, request Production access for that same project. ### Transition your project from Sandbox to Production {#transition-your-project-from-sandbox-to-production} 1. **Open your project in Mastercard Developers** : Go to your [My Projects](https://developer.mastercard.com/dashboard) page and open the Mastercard Installments project you used for Sandbox testing. 2. **Request Production access for that project** : In the project dashboard, select **Request Production Access** . Your Sandbox and Production statuses are shown separately on the project page, so you can track when Production moves from `Not Requested` to an enabled `Ready` state. 3. **Generate or download your Production keys**: After Production access is approved, download the Production OAuth and encryption keys for the same project. Keep the Production key material separate from your Sandbox keys. 4. **Update your application configuration**: Switch the base URL from Sandbox to Production: * Sandbox: `https://sandbox.api.mastercard.com/installments` * Production: `https://api.mastercard.com/installments` Update your application to use the Production consumer key, signing key, and encryption certificates. For a detailed overview of the process involved in moving to production, see [Move Project to Production](https://developer.mastercard.com/unified-installments/tutorial/production-access/index.md). Note: OAuth 1.0a authentication and JWE payload encryption work the same way in Sandbox and Production. The main changes are the Production key set, the Production approval state, and the Production base URL. If you need the full onboarding process, including contract, Sandbox, SLA, and escalation details, see the [Onboarding Checklist](https://developer.mastercard.com/unified-installments/documentation/onboarding-checklist/index.md). ## Next Steps {#next-steps} Continue with the documentation that matches your next task: * [API Basics](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md) for authentication, encryption, and client configuration. * [Use cases](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-program-with-merchant-participation/index.md) for endpoint details. * [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) for additional request scenarios.