# 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. You can use the Merchant Onboarding API to onboard new merchants. This section describes how you can to use the API when you operate on your own license. When you operate on your own license, there is no business relationship between Mastercard Open Finance Pay and your merchants, so the Know Your Customer (KYC) obligations sit with you. Mastercard Open Finance Pay approves your new merchants automatically, without an internal KYC flow. ## Overview {#overview} This diagram shows an overview of the flow to onboard a merchant. Diagram merch_onb_licensed ## How It Works {#how-it-works} This section explains how to onboard a merchant and add a payment destination. With the Merchant Onboarding endpoints, you can create a merchant, add a payment destination, and fetch the details of your merchants and payment destinations. 1. **Perform KYC checks on the merchant.** When a merchant asks you to enable them to accept payments through Mastercard Open Finance Pay, perform the appropriate KYC checks before you onboard them. Because you operate on your own license, the KYC obligations sit with you, and Mastercard Open Finance Pay approves your merchants automatically without its own KYC flow. 2. **Authenticate with the API.** Make sure to use the `ob_onboarding` scope in the request body when you authenticate. Refer to [Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/api-basics/index.md) for detailed instructions on how to authenticate with the service. 3. **Create a new merchant.** Call the **Create Merchant** endpoint. API Reference: `POST /merchants` The response returns a `merchantId`, a unique identifier for the new merchant within Mastercard Open Finance Pay. You pass the `merchantId` in the other Merchant Onboarding endpoints to specify this merchant. Refer to [Create Merchant Fields](https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-licensed-integrators/index.md#create-merchant-fields) for the fields to include in the request body. 4. **Check the merchant status.** Call the **Get Merchant** endpoint to fetch the details of a merchant you created and check its current status. Use the `merchantId` from step 3 as the `merchant_id` path parameter. API Reference: `GET /merchants/{merchant_id}` Most of the details returned reflect what you provided when you created the merchant. As a licensed integrator, the status moves to APPROVED automatically once you create the merchant in step 3, because Mastercard Open Finance Pay does not perform KYC checks on your merchants. Use this to help manage the merchants you have onboarded. 5. **Create a destination account for the merchant.** Call the **Create Merchant Payment Destination** endpoint to add a payment destination account to a merchant. Use the `merchantId` from step 3 as the `merchant_id` path parameter. API Reference: `POST /merchants/{merchant_id}/payment-destinations` A successful call returns a `destinationId`, a reference to the onboarded payment destination account. You pass the `destinationId` in future payment requests to identify both the merchant and the payment destination account that the payer pays into. There are two options for onboarding a new payment destination - refer to [Payment Destination Options](https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-licensed-integrators/index.md#payment-destination-options). 6. **Fetch all the merchants you have onboarded.** Call the **Get Merchants** endpoint. API Reference: `GET /merchants` Use the `offset` and `limit` query parameters to page through the results: * `offset` is the number of items to skip from the start of the list. * The minimum is 0, which skips nothing and starts at the first item. * The default is 0. * `limit` is the maximum number of items to return. * The highest value accepted is 1,000. * The default is 1,000. For example: /merchants?offset=10&limit=20 This request skips the first 10 merchants and returns the next 20, so you receive items 11 to 30. If you do not set `offset` and `limit`, the defaults apply and the endpoint returns the first 1,000 items. The endpoint returns a list of merchants, each identifiable by its `merchantId`, `companyName`, or `tradingName`. The information returned for each merchant is similar to the details you provided when you created the merchant in step 3. The endpoint also returns the current status of each merchant, which helps you manage and track all the merchants you have onboarded. 7. **Fetch the payment destinations for a merchant.** Call the **Get Merchant Payment Destinations** endpoint to fetch all the payment destinations you have onboarded for a specific merchant. Use the `merchantId` from step 3 as the `merchant_id` path parameter. API Reference: `GET /merchants/{merchant_id}/payment-destinations` The endpoint returns a list of payment destinations, each identifiable by its `destinationId`. This helps you manage and track all the payment destinations you have onboarded for your merchants. The endpoint can return: * `destinationId` - The unique identifier for the onboarded payment destination. * `parentDestinationId` - The unique identifier for your payment destination, whose details are inherited by the merchant's `destinationId`. This applies only when a reference payment destination was onboarded, as described in [Payment Destination Options](https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-licensed-integrators/index.md#payment-destination-options). * `account` - The object containing the account details for the payment destination. * `paymentRail` - The payment rail by which the payment is executed. * `status` - An object containing the latest status for the merchant's payment destination within Mastercard Open Finance Pay. * `code` - The latest status of the merchant's payment destination. * `lastUpdated` - When this status was last updated. * `accountType` - The type of the account. * `description` - A long description of the account that provides further detail. * `externalReference` - A unique identifier for the account within the external system. 8. **Manage the disabled markets for a merchant.** Call the **Update Merchant Disabled Markets** endpoint to manage the list of markets you want to disable for a merchant. Use the `merchantId` from step 3 as the `merchant_id` path parameter. API Reference: `PUT /merchants/{merchant_id}/disabled-markets` Consider the following when you use this endpoint: * **Complete list submission:** When you update the disabled markets, always submit the full list of markets to disable. Include all previously disabled markets and any new markets you want to add. * **Enabling markets:** To enable a market that was previously disabled, submit an updated request that excludes that market from the list. In other words, include only the markets that should remain disabled. For example: 1. Your disabled markets list might initially 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 that excludes 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** and **Get Merchants** endpoints, `availableMarkets` and `disabledMarkets` are returned based on this logic: * `availableMarkets` represents all countries where the merchant is currently enabled to operate. It is calculated based on the markets available at your level, minus any markets marked as disabled at the merchant or parent merchant level. For merchant stores, this list reflects the filtered availability after parent-level restrictions are applied. * `disabledMarkets` lists all markets where the merchant is not allowed to operate. For parent merchants, these are defined directly at the merchant level. For merchant stores, they inherit the parent merchant's disabled markets, and you can add store-specific market restrictions. Note: All country codes use the ISO 3166-1 alpha-2 standard. 9. **Disable a merchant.** Call the **Disable Merchant** endpoint to disable a merchant and, if required, enable it again. Use the `merchantId` from step 3 as the `merchant_id` path parameter. Set the `isDisabled` flag: * `true` disables the merchant, so you cannot accept payments for it. * `false` enables the merchant, so it can accept payments. API Reference: `PUT /merchants/{merchant_id}/disabled` In the **Get Merchant** and **Get Merchants** endpoints, `isDisabled` is returned based on the current status of the merchant. 10. **Confirm onboarding is complete.** Inform the merchant that onboarding is complete and they can begin to accept Open Finance payments. ## Create Merchant Fields {#create-merchant-fields} The following fields are mandatory in the **Create Merchant** request body: | **Field** | **Description** | |-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `onboardingType` | The type of Merchant Onboarding flow to start. For licensed integrators, set this to `Api`. Because Mastercard Open Finance Pay does not perform KYC on your merchant, there is no need to send the merchant through a web-based onboarding flow. | | `companyName` | The legal company name of the merchant you are onboarding. | | `companyRegistrationNumber` | The company registration number of the merchant you are onboarding. | | `tradingName` | The trading name the merchant uses when carrying out business, also known as a DBA (Doing Business As) name. This name appears on the Mastercard Open Finance Pay screens during a payment journey. | | `country` | The country in which the merchant you are onboarding is registered. | The following fields are optional: | **Field** | **Description** | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isContractPresent` | Confirms that the license holder has a contract in place with the payee and has completed appropriate due diligence and KYC processes on the merchant being onboarded. | | `categoryCode` | The Merchant Category Code for the merchant you are onboarding, which reflects the primary category in which the merchant does business. This field is mandatory for clients participating in PayFrom. | | `logoImage` | The logo of the merchant you are onboarding, passed as a base64-encoded string. This logo appears on Mastercard screens during the payment journey. | | `logoImageType` | The file format of the logo 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 whether a merchant is disabled. | ## Payment Destination Options {#payment-destination-options} When you create a payment destination with the **Create Merchant Payment Destination** endpoint, there are two options. **Option 1: Reference a previously onboarded destination.** This is typically used in a distributor model, where you receive the funds in your accounts and then settle them onward to your merchants. The `parentDestinationId` is onboarded at your own level. The following fields are mandatory: | **Field** | **Description** | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `identificationType` | Specifies the type of destination onboarding required. When you onboard a reference account, set this to `Reference`. | | `parentDestinationId` | The previously onboarded `destinationId` at your own level. The merchant inherits the destination bank account details of this `destinationId`. The response returns a new merchant-level `destinationId`. When you pass the new merchant-level `destinationId` in a payment request, funds are paid into the bank account previously onboarded for the `parentDestinationId`. This suits a scenario where you collect funds on behalf of your merchants and then settle the funds onward to them. | **Option 2: Onboard a new payment destination account using bank account details.** You provide the bank account details you want funds paid into. Because the required details differ by market, we use the concept of a **paymentRail** to make clear what account details you need for each market. This is typically used in a direct model, where the funds transfer directly from the payer's account to the merchant's account. Refer to the [API reference](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md) for a breakdown of each supported **paymentRail** and the details required to onboard a new payment destination bank account. The following fields are mandatory: | **Field** | **Description** | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `identificationType` | Specifies the type of destination onboarding required. When you onboard new bank account details, set this to `AccountDetails`. | | `account` | Object for creating a new payment destination using bank account details. The details required in the `account` object depend on the payment rail you choose. Refer to the [API reference](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md) for the full breakdown of available payment rails and the fields required to onboard destination bank account details for each market. | After you onboard a new destination account using account details, the API returns a new `destinationId`. You can then use this `destinationId` in future payment requests to identify the merchant and specify the destination account that the funds are paid into.