# Onboarding Affiliates
source: https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md

Alert: To use the Partner Direct Model via an API, you need to sign up for the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/). Users who do not have the permission to access the Mastercard Developers API will be directed to a page where they can request access.

As a Direct Partner, you can use the following options to onboard your affiliate customers:

* [Mastercard Developers API](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md#onboard-using-the-api)
* [Mastercard Developers Dashboard](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/onboarding-customers/index.md#onboard-using-mastercard-developers-dashboard)

## Onboard Using the Mastercard Developers API {#onboard-using-the-mastercard-developers-api}

Note: The Mastercard Developers API (Onboarding API) and the Open Finance API use different base URLs.   

* For Mastercard Developers API, the base URL is `https://apiedge.mastercard.com/`.
* For Open Finance API, the base URL is `https://api.finicity.com/`.
Make sure to use the correct base URL depending on whether you are working with the Mastercard Developers API (Onboarding API) or the Open Finance API.

Call the [Mastercard Developers API](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/) to create projects to onboard and manage your affiliate customers/partners. When a project is created, the project corresponds to a specific affiliate customer. A one-to-one relationship exists between projects and the affiliates you onboard.

Mastercard Developers API uses OAuth 1.0a for authenticating your requests. To learn more, 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/).

Once you successfully create projects for your affiliates, project credentials are generated for each one of your affiliate customers. The project credentials are unique and can be used to serve business needs such as registering applications and customizing experiences for your consumers/end-users.

After you create projects through the Developers API and onboard affiliate customers, the projects will be available on the [project dashboard](https://developer.mastercard.com/dashboard) of your account on Mastercard Developers.
Tip: You can start using the Developers API without writing any code. Follow the steps in the [Developers API Quick Start Guide](https://developer.mastercard.com/mastercard-developers-api/documentation/quick-start-guide/) to explore the Developers API Postman Collection and test all the endpoints. You can use the pre-defined requests in the Postman collection to call the API.


1. [Log in](https://developer.mastercard.com/dashboard) to Mastercard Developers.
2. **Add API Key**
   * Go to your [Account](https://developer.mastercard.com/account/profile) page and in the Developers API Keys section click **Add key**
3. **Generate a Key**
   * Provide a **Key name** and **Keystore Password**
   * If prompted, review and accept the **Mastercard Developers API Terms \& Conditions** to proceed
   * Click **Create Key** to generate a private key in your browser. This will create a PKCS#12 keystore file secured with your keystore password
   * Download the signing key as a PKCS#12 keystore by clicking **Download key** . To learn more about the methods available for creating your keys, refer to the [Creating Keys](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#creating-keys) section in the Mastercard Developers Platform documentation
4. **Get Your Consumer Key**

   Get your consumer key from the Developers API Keys section of your Account page. To learn more about what a consumer key is and its usage, refer to the [Consumer Key](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#the-consumer-key) section in the Mastercard Developers Platform documentation.
5. **Extract the Signing Key (Private Key)**

   The signing key is a private key used to generate request signatures and confirms ownership of the consumer key. Use the following command to extract the private key from your PKCS#12 keystore (use the password protecting your PKCS#12 file):
   * OpenSSL

   ```OpenSSL
     openssl pkcs12 -in 'mykey.p12' -nocerts -nodes -passin pass:{password} | openssl rsa -out mykey.pem
     
   ```

   Expected result:  

   ```java
   -----BEGIN RSA PRIVATE KEY-----
   MIIEpQIBAAKCAQEAzSdC+wm6Dv4ynlhU5tuMLMsX7AeMWoysQKAaCDCStEWUHyj4
   K84X+ZQH0kIJkpWS0M1+vWHTSAu0QvHNDPRIJKMNE2cCRVKApVZ8jQ9DhFkVYE0j
   AhggCNQTJ0kXDBvc1mZPOJDmXusvHIG3BbRSE6ohZHoUXAuAg4bbwZwmvgDgMrmN
   9A9upgMrVZMfrCWeKiBUKoGnwGwUf0iMiHXJhD1Wjdtf0+VAsZNI7r05n9FTHmiC
   ...
   YlR8szTbz1WEx//hU5Ea2sfcKmPDTNWQnx0IgSmPu5I9qf7KJxSYhOk=
   -----END RSA PRIVATE KEY-----
   ```

6. **Use the Consumer Key and Private Key**   
   You will require both the `Consumer Key` and the private key extracted from the PKCS#12 file in the previous step to be able to call the API.
7. **Add a Key using a CSR**   
   You can also add a key by uploading a CSR generated in your system:
   * Go to the Developers API Keys section in your [Account](https://developer.mastercard.com/account/profile) page and click **Add Key**
   * Select **Upload a CSR**
   * Provide a Key name and click **Add an attachment**. Browse and choose the CSR file generated in your system
   * If prompted, review and accept the **Mastercard Developers API Terms \& Conditions** to proceed
   * Click **Create Key** . For more information on this method, refer to the [Creating Keys](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#method-2) section in the Mastercard Developers Platform documentation

**Key Limits and Status:**

* After adding a key, its status will appear as **Pending**. You will receive an email notification once the key is approved, after which you can start sending requests to the Developers API
* You can add a maximum of **2 keys**
* If a key request is declined, you must revoke the declined key before adding a new one
To create a project, call the `POST /projects` endpoint. Ensure that the `type` is set to `OPEN_BANKING_PARTNER` and the `serviceId` to `1443`. For more details on the request parameters, see the [API Reference](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference) section in the Mastercard Developers API documentation.

##### Sample Request {#sample-request}

```JSON

{
  "type": "OPEN_BANKING_PARTNER",
  "name": "My Open Finance Project",
  "region": "US",
  "service": {
    "serviceId": 1443
  },
  "environment": "SANDBOX",
  "credential": {
    "type": "PARTNER",
    "description": "A custom description for the credential"
  },
  "company": {
    "name": "Client Company Name",
    "isGovernmentEntity": false,
    "address": {
      "type": "Headquarters",
      "addressLine1": "420 8th Street S.E",
      "addressLine2": "Brooklyn, NY",
      "city": "NYC",
      "state": "NY",
      "postalCode": "90210",
      "countryCode": "USA"
    }
  },
  "commercialCountries": [
    "USA"
  ]
}
```

After successful project creation, the Developers API returns the affiliate customer details including their `partnerId`, `secret`, and `appKey` along with the ID for the newly created project. This project ID will be required to request production access. You will receive an email notification once the project is successfully created.

##### Sample Response {#sample-response}

```JSON
{
  "id": "1c1ea17e-260d-11ee-be56-0242ac120002",
  "name": "My Open Finance Project",
  "type": "OPEN_BANKING_PARTNER",
  "region": "US",
  "services": [
    {
      "id": 1443,
      "name": "Open Finance"
    }
  ],
  "environments": [
    {
      "name": "SANDBOX",
      "credentials": [
        {
          "id": "04bcdc45-9a96-4516-a7b0-49a26440d405",
          "type": "PARTNER",
          "partnerId": "2445583866521",
          "appKey": "555617add4733a9befefa2560cdcfb71",
          "plan": "Test Drive",
          "status": "APPROVED",
          "description": "A custom description for the credential",
          "secrets": [
            {
              "secret": "SdknnFTYoAlWgFakTHy1",
              "expirationDate": "2025-10-25T15:24:20Z"
            }
          ]
        }
      ],
      "projectServices": [
        {
          "serviceId": 1443,
          "status": "APPROVED"
        }
      ]
    }
  ],
  "teamMembers": [],
  "invitedUsers": [],
  "company": {
    "id": "a7a200c9-f0ae-44c9-97f7-0ebd2943adfd",
    "companyId": "293101",
    "name": "Client Company Name",
    "verified": true,
    "isGovernmentEntity": false,
    "address": {
      "type": "Headquarters",
      "addressLine1": "420 8th Street S.E",
      "addressLine2": "Brooklyn, NY",
      "city": "NYC",
      "state": "NY",
      "postalCode": "90210",
      "countryCode": "USA"
    }
  },
  "commercialCountries": [
    "USA"
  ]
}
```

Optionally you can call [GET /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) to view the status of your project creation.

<br />

We recommend that you onboard affiliate customers in a Sandbox environment first before requesting production access. Onboarding your affiliate customers in Sandbox not only gives you the ability to test, but also helps you avoid incurring any accidental billing before enabling production access for your customers.

To request production access, call [POST /projects/{project_id}/environments](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) with the `projectId` assigned to your affiliate customer's project. You can retrieve a full list of your projects including the project IDs by calling the [GET /projects](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) endpoint.

##### Sample Request {#sample-request}

```JSON
{
  "name": "PRODUCTION",
  "credential": {
    "type": "PARTNER",
    "description": "A credential used in Production"
  }
}
```

You will receive a response containing the credentials for the production environment. These credentials are still not approved for production use and will be in `PENDING` status. The production access request will be reviewed by Mastercard, and once approved you will receive a notification via email.
Note: The response to your production access request can contain one or more statuses. It is important to refer to the appropriate status field to determine the state of your production access request.

* The `CredentialStatus` field accurately represents the status of the credentials for use in production. When returned as `APPROVED` you can use your credentials in production.
* The `ProjectServiceStatus` field is always returned as `APPROVED` and does not reflect the status of your production access.

##### Sample Response {#sample-response}

```JSON
{
    "name": "PRODUCTION",
    "credentials": [
        {
            "status": "PENDING_APPROVAL",
            "partnerId": "2445584446024",
            "id": "d945c717-0196-49f7-a782-c9dbe312ff42",
            "type": "PARTNER",
            "appKey": "b41a66b50cfbfc2955fed24f3e425099",
            "plan": "Test Drive",
            "secrets": [
                {
                    "secret": "e3CMpVzJYZfE91A8G1hU",
                    "expirationDate": "2025-03-19T06:07:18Z"
                }
            ],
            "description": "Production credentials for my project",
            "error": null
        }
    ],
    "projectServices": [
        {
            "serviceId": 1443,
            "status": "APPROVED",
            "credentials": []
        }
    ]
}
```

Optionally you can call [GET /projects/{project_id}](https://developer.mastercard.com/mastercard-developers-api/documentation/api-reference/#apis) to view the status of your production access request. Once approved, the status of the credentials change from `PENDING_APPROVAL` to `APPROVED`.

## Onboard Using Mastercard Developers Dashboard {#onboard-using-mastercard-developers-dashboard}

1. [Log in](https://developer.mastercard.com/account/log-in) to Mastercard Developers and click the **Create New Project** button at the top of this page.

2. Enter a name for your project.

3. You have the option to choose if you want to create a project for yourself or for a client. Choose **Yes** to create a project on behalf of a client.

4. Enter the company name and address of the affiliate customer.

5. Select **Open Finance** from the **Select your API service** drop-down list.

6. Ensure the region is selected as United States.

7. Provide a helpful description for the Sandbox credentials and click **Create Project** .

1. Go to the Production section and click **Request Upgrade**.

2. Provide a helpful description for the production credentials and click **Proceed**. The production access request will be reviewed by Mastercard and once approved, you will receive a notification via email.

## Next Steps {#next-steps}

See [Manage Projects](https://developer.mastercard.com/open-finance-us/documentation/participant-model/partner-direct/managing-customers/index.md) to manage your affiliate customers' projects on Mastercard Developers.