# Merchant Onboarding for Licensed Integrators source: https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-licensed-integrators/index.md Note: This is a preview of our Merchant Onboarding solution for Licensed Integrators and is still subject to change. [Contact us](https://openbankingeu.mastercard.com/contact-us) to understand if it is appropriate for use in your individual circumstance. Mastercard Open Finance Pay understands the need to offer our Integrators efficient, secure and scalable solutions for onboarding new Merchants to our Open Finance payment platform. In this section, we will describe our Merchant Onboarding APIs and how they can be used by Integrators that operate on their own license. Using these APIs you can automate the process for onboarding your Merchants with Mastercard Open Finance Pay. When an Integrator operating on their own license onboards Merchants, it is considered that there is no business relationship between Mastercard Open Finance Pay and the Merchants. As a result, the KYC obligations would sit with the Integrator. Mastercard Open Finance Pay will automatically approve the new Merchants without the need to go through an internal KYC flow at Mastercard Open Finance Pay. ### Flow for Merchant Onboarding for Licensed Integrators {#flow-for-merchant-onboarding-for-licensed-integrators} Diagram merch_onb_licensed 1. Merchant asks the Integrator to enable them to accept payments through Mastercard Open Finance Pay. 2. The Integrator performs appropriate KYC checks on the Merchant before onboarding them to Mastercard Open Finance Pay. 3. The Integrator sends a Create merchant request to Mastercard Open Finance Pay including the relevant Merchant information. 4. Mastercard Open Finance Pay returns a `merchantId` which uniquely identifies the Merchant in our systems and will be used by the Integrator to specify the Merchant in other API calls. 5. Using the `merchantId`, the Integrator calls the Get merchant endpoint to understand the latest status of the newly onboarded Merchant. As Licensed Integrator, you can expect your newly onboarded Merchant to be automatically approved as Mastercard Open Finance Pay will not perform any KYC checks on the Merchants of Licensed Integrators. 6. Mastercard Open Finance Pay returns the latest status of the Merchant as well as the Merchant details that were received during the Create merchant request. 7. The Integrator sends a Create merchant payment destination request to Mastercard Open Finance Pay. This will include the details of the payment destination bank account that funds will be paid into. 8. Mastercard Open Finance Pay will return a `destinationId`. This uniquely identifies the newly onboarded payment destination account. To have funds paid into the bank account that sits under the `destinationId` you will need to pass the `destinationId` in future payment requests. 9. The Integrator fetches all of the payment destinations that have been previously onboarded for a specific Merchant that will be identified by passing the `merchantId` in the path. 10. Mastercard Open Finance Pay returns a list of all previously onboarded payment destinations for the Merchant as well as their current status in Mastercard Open Finance Pay. As Licensed Integrator, you can expect your newly onboarded payment destinations to be automatically approved as Mastercard Open Finance Pay will not perform any KYC checks on the payment destinations of Licensed Integrators. 11. The Integrator informs the Merchant that the onboarding process is now complete and they can begin to accept Open Finance payments. ### Steps for Merchant Onboarding for Licensed Integrators {#steps-for-merchant-onboarding-for-licensed-integrators} #### STEP 1 - Authenticate with the API {#step-1---authenticate-with-the-api} To use the API, you need to be authenticated with the service. You will need to make sure that you are using the **ob_onboarding** scope in the request body when Authenticating. Refer to the [API Basics / Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/api-basics/authentication/index.md) section for detailed instructions regarding how you can authenticate with the service. #### STEP 2 - Call the Merchant Onboarding APIs {#step-2---call-the-merchant-onboarding-apis} After the initial Integrator onboarding, and authentication, you are ready to call the Merchant Onboarding endpoints. With these endpoints, you can create a new Merchant, Add a payment destination to a Merchant and fetch details on Merchants and Payment Destinations. #### STEP 3 - Create a new Merchant {#step-3---create-a-new-merchant} API Reference: `POST /merchants` Using the `/merchants endpoint` will result in Mastercard Open Finance Pay returning a `merchantId`. The `merchantId` is a unique identifier for the new Merchant within Mastercard Open Finance Pay. The `merchantId` will be passed in by the Integrator for other Merchant Onboarding endpoints to specify this Merchant. When creating a Merchant using the `/merchants` endpoints, there are several mandatory fields that will need to be passed in the request body. These are described below: | **Mandatory Fields** | **Description** | |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `onboardingType` | Here you will define the type of Merchant Onboarding flow that you wish to start. For Licensed Integrators the `onboardingType` will be `Api`. When a Licensed Integrator onboards a Merchant there is no need to send the merchant down a web based onboarding flow since Mastercard Open Finance Pay will not perform any KYC on the Merchant. | | `companyName` | Here you will pass in the legal company name of the Merchant that you are onboarding. | | `companyRegistrationNumber` | Here you will pass in the company registration number of the Merchant that you are onboarding. | | `tradingName` | Here you will pass in the trading name that the Merchant uses when carrying out business. This is also commonly known as a DBA name (Doing Business As name). The name passed in here will appear on the Mastercard Open Finance Pay screens during a payment journey. | | `country` | Here you will pass in the country in which the Merchant you are onboarding is registered in. | There are also some optional fields that can be passed in the `/merchants` endpoint when creating a new Merchant: | **Optional Fields** | **Description** | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isContractPresent` | Inform Mastercard Open Finance Pay that the License holder has a contract in place with the payee and has undertaken appropriate due diligence / KYC processes on the Merchant that is being onboarded. | | `categoryCode` | Here you will pass in the merchant Category Code for the Merchant that you are onboarding. The Merchant Category Code reflects the primary category in which a merchant does business. The `categoryCode` field is mandatory for clients participating in PayFrom. | | `logoImage` | Here you will pass in the logo of the Merchant that you are onboarding. The logo will be passed in the request body in the form of a base64 encoded string. This is the Merchant logo that will appear on Mastercard screens during the payment journey. | | `logoImageType` | Here you will pass in the file format of the logo that you passed in `logoImage`. | | `parentMerchantId` | Identifier of the parent merchant of a merchant store. | | `externalReference` | Identifier as specified within the external system. | | `isDisabled` | Flag that shows if a merchant is disabled. | #### STEP 4 - Fetch the details of a specific Merchant and check the Merchant status {#step-4---fetch-the-details-of-a-specific-merchant-and-check-the-merchant-status} API Reference: `GET /merchants/{merchant_id}` You can use the `/merchants/{merchant_id}` endpoint to fetch the details of a Merchant that you have previously created and also check the current status of that Merchant within Mastercard Open Finance Pay. Most of the details returned here will reflect what was populated by the Integrator when creating the Merchant. It will also return the current status of the Merchant within Mastercard Open Finance Pay. As a licensed Integrator you can expect that the status for the Merchant will automatically move to APPROVED once the Merchant has been created in Step 3. This can be used to assist you with the management of the Merchants that you have onboarded to Mastercard Open Finance Pay. #### STEP 5 - Create a Destination account for a Merchant {#step-5---create-a-destination-account-for-a-merchant} API Reference: `POST /merchants/{merchant_id}/payment-destinations` You can use the `/merchants/{merchant_id}/payment-destinations` endpoint to add a payment destination account to a Merchant. A successful call to this endpoint will result in a `destinationId` being returned. The `destinationId` is an integral part of the Mastercard Open Finance Pay Accept Payments offering. The `destinationId` is a reference to a previously onboarded payment destination account. The `destinationId` obtained here will be passed in by the integrator in future payment requests to both identify the Merchant and the payment destination account that the PSU will be paying into. There are two different options for onboarding a new payment destination: **1. Onboarding a payment destination that will reference a previously onboarded destination.** This scenario is typically used in a Distributor model where the Integrator / Distributor will receive the funds in their accounts and then onward settle them to their Merchants. In this case the previously onboarded `parentDestinationId` will have been onboarded at the Integrator level. When onboarding a reference payment destination there are two mandatory fields that must be passed in: | **Mandatory Fields** | **Description** | |-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `identificationType` | Specifies the type of destination onboarding that is required. When onboarding a reference account, the value passed in here must be Reference. | | `parentDestinationId` | The value passed in here is the previously onboarded Integrator `destinationId`. The destination bank account details for this previously onboarded `destinationId` will be inherited by the Merchant. In the response, a new Merchant level `destinationId` will be returned. This means that when the Integrator passes in the new Merchant level `destinationId` in a payment request it will result in funds being paid into the bank account previously onboarded for the Integrator level `parentDestinationId`. This would be suitable for a scenario where an Integrator wants to collect funds on behalf of their Merchants and then onwards settle the funds to the Merchants. | **2. Onboard a new payment destination account using bank account details.** When onboarding a new payment destination account the Integrator will provide the bank account details that they wish to have funds paid into. Mastercard Open Finance Pay operates in many markets and the bank account details required in each market will be different. To make it clear to the Integrator what account details they will need to provide for each market we use the concept of a **paymentRail**. In the [API References](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md) you can see a breakdown of each **paymentRail** supported and the details that need to be supplied for each paymentRail to successfully onboard a new payment destination bank account. This is typically used in a Direct model where the funds will transfer directly from the Payer's account to the Merchant's account. | **Mandatory Fields** | **Description** | |----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `identificationType` | Specifies the type of destination onboarding that is required. When onboarding new bank account details, the value passed in here must be AccountDetails. | | `account` | Object for the creation of a new Payment Destination using bank account details. The details that are required in the account object will depend on the paymentRail chosen by the Integrator. Refer to the [API References](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md) to see the full breakdown of available payment rails and the fields that will be required to successfully onboard destination bank account details for each market. | Once you have successfully onboarded a new destination account using account details, the API will return a new `destinationId`. This `destinationId` can then be used in future payment requests to identify the Merchant and specify the destination account that the funds will be paid into. #### STEP 6 - Fetch the details for all Merchants that have been onboarded for an Integrator {#step-6-fetch-the-details-for-all-merchants-that-have-been-onboarded-for-an-integrator} API Reference: `GET /merchants` With the `/merchants` endpoint you can fetch details for all of the merchants that have been previously onboarded by you as an Integrator. With this endpoint we offer offset and limit query parameters to help you to manage pagination. * Limit will ensure that only that number of items are returned. * Offset will control how many items will be skipped before returning the results. ###### Example: {#example} API Reference: `GET /merchants?offset=10&limit=20` In this example, the API will return resources 11 to 30. If a limit and offset is not specified then the default of 1 to 1,000 will apply. This endpoint will return a list of Merchants. Each individual Merchant will be identifiable by it's `merchantId`, `companyName` or `tradingName`. The information returned for each Merchant will be similar to the details that were passed in by the Integrator when creating the Merchant in step 3. Additionally, this endpoint will return the current status of each merchant within Mastercard Open Finance Pay. This endpoint will assist you in managing and keeping track of all of the different Merchants that you have previously onboarded. #### STEP 7 - Fetch all of the payment destinations that have been onboarded for a specific Merchant {#step-7-fetch-all-of-the-payment-destinations-that-have-been-onboarded-for-a-specific-merchant} API Reference: `GET /merchants/{merchant_id}/payment-destinations` With the `/merchants/{merchant_id}/payment-destinations` endpoint you can fetch all of the payment destinations that have been previously onboarded for a specific Merchant. The `merchantId` (you received in Step 3) will be required in the path to identify the Merchant that you want to query. The endpoint will return a list of payment destinations, each one will be identifiable by the `destinationId`. This endpoint will assist you in managing and keeping track of all of the different payment destinations that you have previously onboarded for your Merchants. The information that can be returned by this endpoint is as follows: * `destinationId` - The unique identifier for the previously onboarded payment destination. * `parentDestinationId` - The unique identifier for the Integrators payment destination, the details of which will be inherited by the Merchants `destinationId`. This is only for the case where a reference payment destination was onboarded as outlined in Step 5.1. * `account` - The object containing the account details for the payment destination. * `paymentRail` - The payment rail by which the payment will be executed. See more detail on this in the API reference or in Step 5.2 above. * `status` - An object containing the latest status for the Merchants payment destination within Mastercard Open Finance Pay. * `code` - The latest status of the Merchants payment destination. * `lastUpdated` - When this status was last updated. * `accountType` - The type of the account. * `description` - Long description of the account that will help to provide further details on it. * `externalReference` - Unique identifier for the specified account within the external system. #### STEP 8 - Manage a list of disabled markets for a specific Merchant {#step-8---manage-a-list-of-disabled-markets-for-a-specific-merchant} API Reference: `PUT /merchants/{merchant_id}/disabled-markets` With the `/merchants/{merchant_id}/disabled-markets` endpoint, you can manage the list of markets that you want to disable for a particular Merchant. When using this endpoint, there are a couple of things that you need to consider: * **Complete List Submission:** When updating the disabledMarkets for your merchant, you must always submit the full list of markets to be disabled. This list should include all previously disabled markets as well as any new markets you want to add. * **Enabling Markets:** To enable a market that was previously disabled, submit an updated request excluding that market from the disabled markets list. In other words, only include markets that should remain disabled. ###### Example Workflow {#example-workflow} 1. Initially, your disabled markets list might be: \[Market A, Market B, Market C\]. 2. To add Market D to the disabled list, submit the full updated list: \[Market A, Market B, Market C, Market D\]. 3. To enable Market B, submit the updated list excluding it: \[Market A, Market C, Market D\]. Note: **Important:** Partial lists or incremental updates are not supported. Always send the full, up-to-date list of disabled markets for your merchant. In the GET Merchant(s) endpoints, `availableMarkets` and `disabledMarkets` details are returned based on this logic: `availableMarkets` represents all countries where the merchant is currently enabled to operate. Calculated based on: * Markets available at the integrator level. * Exclusion of any markets marked as disabled at either the merchant or parent merchant level. * For merchant stores, this list reflects the filtered availability after applying parent-level restrictions. `disabledMarkets` lists all markets where the merchant is not allowed to operate. * For parent merchants: directly defined at the merchant level. * For merchant stores: * Inherits the parent merchant's disabled markets. * Additional store-specific market restrictions can be added. Note: All country codes use the ISO 3166-1 alpha-2 standard. #### STEP 9 - Disable a Merchant {#step-9---disable-a-merchant} API Reference: `PUT /merchants/{merchant_id}/disabled` With the `/merchants/{merchant_id}/disabled` endpoint, you can disable and then, if required, enable a Merchant again. This is achieved using the `isDisabled` flag. This flag will be set to `true` or `false`. * When it is set to `true`, this means the Merchant is disabled and it is not possible to accept payments for this Merchant. * When it is set to `false`, this means that the Merchant is enabled and the Merchant is open to accept payments. In the `GET Merchant(s)` endpoints, `isDisabled` will be returned based on the current status of the Merchant.