# Merchant Onboarding for Unlicensed Integrators source: https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-unlicensed-integrators/index.md Note: This is a preview of our Merchant Onboarding solution for Unlicensed 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 using Mastercard Open Finance Pay License. Using these APIs, you can automate the process for onboarding your Merchants with Mastercard Open Finance Pay. When an Integrator operating using Mastercard Open Finance Pay License onboards Merchants, there are two different scenarios to consider and the way you onboard your Merchants will depend on the onboarding type: 1. Onboarding a Merchant where the Merchant will have no business relationship (**No business relationship** - Using a third party settlement account) with Mastercard Open Finance Pay. In this scenario, you can onboard Merchants using the Merchant Onboarding API 2. Onboarding a Merchant where the Merchant will have a business relationship (**Business relationship** - Using an account that is legally owned by the Merchant) with Mastercard Open Finance Pay. In this scenario, you will need to onboard Merchants using a web flow so that Mastercard Open Finance Pay can perform appropriate KYC and due diligence on the Merchant. You can use the Create merchant endpoint to get a **flowUrl** that you can redirect the Merchant to so they can complete the onboarding process themselves. #### Data Flow - Onboarding a Merchant where the Merchant will have no business relationship with Mastercard Open Finance Pay {#data-flow---onboarding-a-merchant-where-the-merchant-will-have-no-business-relationship-with-mastercard-open-finance-pay} Diagram merchant_onb_unlicensed_no_rel 1. The Merchant asks the Integrator to enable them to accept payments via Mastercard Open Finance Pay. 2. The Integrator determines that there is no business relationship between the Merchant and Mastercard Open Finance Pay and sends a Create merchant request including the relevant Merchant information with the `onboardingType` set to `Api`. 3. As there is no Business Relationship between the Merchant and Mastercard Open Finance Pay, we will perform some light screening on the Merchant such as a check against a sanctions list and a risk assessment. 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. 6. Mastercard Open Finance Pay returns the latest status of the Merchant as well as the Merchant details that we 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 or the `parentDestinationId` that you want the Merchants new `destinationId` to refer to. 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. 11. The Integrator informs the Merchant that the onboarding process is now complete and they can begin to accept Open Finance payments. #### Data Flow - Onboarding a Merchant where the Merchant will have a business relationship with Mastercard Open Finance Pay {#data-flow---onboarding-a-merchant-where-the-merchant-will-have-a-business-relationship-with-mastercard-open-finance-pay} Diagram merchant_onb_unlicensed_rel 1. The Merchant asks the Integrator to enable them to accept payments through Mastercard Open Finance Pay. 2. The Integrator determines that there is a business relationship between the Merchant and Mastercard Open Finance Pay and sends a Create merchant request including the relevant Merchant information with the `onboardingType` set to `Web`. 3. 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. We will also return a **flowUrl**. 4. The Integrator will redirect a representative from the Merchant to the flowUrl where the Merchant will complete the required self onboarding steps. 5. Mastercard Open Finance Pay will begin the necessary KYC and Due Diligence on the Merchant before activating them in our systems. 6. When the required steps in the Merchant Onboarding flow have been completed by the Merchant, we will return the Merchant to the redirectUrl that was passed in by the Integrator in the create merchant request. 7. Using the `merchantId`, the Integrator calls the Get merchant endpoint to understand the latest status of the newly onboarded Merchant. 8. Mastercard Open Finance Pay returns the latest status of the Merchant as well as the Merchant details that we received during the Create merchant request. 9. Onboard payment destination ID using the web onboarding flow. 10. 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. 11. 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. 12. 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 Unlicensed Integrators {#steps-for-merchant-onboarding-for-unlicensed-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 (only when there is not BR) to a Merchant and fetch details on Merchants and Payment Destinations (only when there is not BR) . ##### 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 onboarding a Merchant as an Unlicensed Integrator, there are two different scenarios and it is important to consider this before stating the Merchant Onboarding process: * Onboarding a Merchant where the Merchant will have no business relationship with Mastercard Open Finance Pay. * Onboarding a Merchant where the Merchant will have a business relationship with Mastercard Open Finance Pay. The differences between the two types of Merchant Onboarding are described below: **1. Onboarding a Merchant where the Merchant will have no business relationship with Mastercard Open Finance Pay.** When creating a Merchant using the `/merchants` endpoint for Merchants where there will be no business relationship with Mastercard Open Finance Pay, 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. In this scenario the `onboardingType` will be `Api`. | | `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` endpoints 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. | **2. Onboarding a Merchant where the Merchant will have a business relationship with Mastercard Open Finance Pay.** When creating a Merchant using the `/merchants` endpoint for Merchants where there will be a business relationship with Mastercard Open Finance Pay, there are two mandatory fields that will need to be passed in the request body. This is described below: | **Mandatory Fields** | **Description** | |----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `onboardingType` | Here you will define the type of Merchant Onboarding flow that you wish to start. In this scenario the `onboardingType` will be `Web`. In this case, we will return a **flowUrl** that you will redirect the Merchant to so they can progress with the onboarding process. | | `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 solutions screens during a payment journey. . | There are also some optional fields that can be passed in the `/merchants` endpoints when creating a new Merchant in this scenario: | **Optional Fields** | **Description** | |---------------------|---------------------------------------------------------------------------------------------------------------------------------| | `language` | Here you can specify the language that will be used on the screens during the Merchant Onboarding flow. | | `redirectUrl` | Here you can specify the URL that we will redirect the Merchant back to after they have completed the Merchant Onboarding flow. | | `parentMerchantId` | Identifier of the parent merchant of a merchant store.. | | `externalReference` | Identifier as specified within the external system.. | In this scenario, the `/merchants` endpoint will return a **flowUrl** that you will redirect the Merchant to so they can progress with the onboarding process and complete the required self onboarding steps. ##### 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 detail 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. There are several statuses that a newly onboarded Merchant can be in: | **Status** | **Description** | |-----------------------|---------------------------------------------------------------------------------------------| | `INITIALIZED` | Participant data is currently being collected, and the review process has not yet started. | | `AWAITING_REVIEW` | The review process has been initiated for the given participant journey. | | `APPROVED` | The review process has been successfully completed, and the participant is now active. | | `NEEDS_CLARIFICATION` | Additional data is required to complete the review. | | `REJECTED` | The review process has been completed, but the participant's application has been rejected. | #### 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. Note: A payment destination cannot be added via the API request if integrator has a business relationship with Mastercard Open Finance Solutions. In this case, the payment destination will be onboarded via the web flow UI. DestinationIds can be retrieved using the GET endpoint. 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.** 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. | **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, we 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, we 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 detal 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 . There are several statuses that a destination can be in: | **Status** | **Description** | |-----------------------|---------------------------------------------------------------------------------------------------------------------| | `UNDER_REVIEW` | The review process has been initiated for the given account. | | `APPROVED` | The review process has been successfully completed, and the account is now active. | | `NEEDS_CLARIFICATION` | One of the checks compliance does, is to verify account's ownership, which usually requires additional document(s). | | `SUSPENDED` | The account is suspended. | | `REJECTED` | The account is rejected and cannot be used. | #### 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.