# 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 PISP 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 confirm that both are ready to use. 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. **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. 3. **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 2, because Mastercard Open Finance Pay does not perform KYC checks on your merchants. Use this to help manage the merchants you have onboarded. 4. **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 2 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). 5. **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 2 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. 6. **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.