# 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. You can use the Merchant Onboarding API to onboard new merchants. This section describes how you can use the API when you operate using the Mastercard Open Finance Pay license. When you operate using the Mastercard Open Finance Pay license, there are two scenarios, and the way you onboard a merchant depends on the onboarding type: * **No business relationship.** The merchant has no business relationship with Mastercard Open Finance Pay and uses a third-party settlement account. You onboard the merchant with the API, setting `onboardingType` to `Api`. * **Business relationship.** The merchant has a business relationship with Mastercard Open Finance Pay and uses an account it legally owns. You onboard the merchant through a web flow so that Mastercard Open Finance Pay can perform the appropriate KYC and due diligence, setting `onboardingType` to `Web`. The **Create Merchant** endpoint returns a `flowUrl` that you redirect the merchant to so they can complete the onboarding themselves. ## Overview {#overview} This diagram shows an overview of the flow to onboard a merchant that has no business relationship with Mastercard Open Finance Pay. Diagram merchant_onb_unlicensed_no_rel This diagram shows an overview of the flow to onboard a merchant that has a business relationship with Mastercard Open Finance Pay. Diagram merchant_onb_unlicensed_rel ## 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. **Determine the onboarding type.** When a merchant asks you to enable them to accept payments through Mastercard Open Finance Pay, determine whether the merchant has a business relationship with Mastercard Open Finance Pay. This determines the `onboardingType` you use when you create the merchant. 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. The fields you include depend on the onboarding type - refer to [Create Merchant Fields](https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-unlicensed-integrators/index.md#create-merchant-fields). When there is no business relationship, Mastercard Open Finance Pay performs light screening on the merchant, such as a sanctions-list check and a risk assessment. When there is a business relationship, the response also returns a `flowUrl`. Redirect a representative from the merchant to the `flowUrl` so they can complete the required self-onboarding steps. Mastercard Open Finance Pay then performs the necessary KYC and due diligence before activating the merchant. Once the merchant completes the flow, they are returned to the `redirectUrl` you passed in the request. 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. The endpoint also returns the current status of the merchant - refer to [Merchant Statuses](https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-unlicensed-integrators/index.md#merchant-statuses). 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-unlicensed-integrators/index.md#payment-destination-options). Note: When there is a business relationship with Mastercard Open Finance Pay, you cannot add a payment destination through the API. Instead, the payment destination is onboarded through the web flow. You can retrieve the `destinationId` values using the **Get Merchant Payment Destinations** endpoint. 6. **Fetch all the merchants you have onboarded.** Call the **Get Merchants** endpoint to fetch the details of all the merchants you have onboarded. API Reference: `GET /merchants` Use the `offset` and `limit` query parameters to manage pagination: * `limit` returns only that number of items. * `offset` controls how many items are skipped before the results are returned. For example: API Reference: `GET /merchants?offset=10&limit=20` In this example, the API returns resources 11 to 30. If you do not specify a limit and offset, the default of 1 to 1,000 applies. 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-unlicensed-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. The endpoint also returns the current status of each payment destination - refer to [Payment Destination Statuses](https://developer.mastercard.com/ob-accept-payments/documentation/payments/merchant-onboarding/merch-onb-for-unlicensed-integrators/index.md#payment-destination-statuses). 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 fields you include in the **Create Merchant** request body depend on whether the merchant has a business relationship with Mastercard Open Finance Pay. ### No Business Relationship {#no-business-relationship} The following fields are mandatory when the merchant has no business relationship: | **Field** | **Description** | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `onboardingType` | The type of Merchant Onboarding flow to start. For this scenario, set this to `Api`. | | `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. | ### Business Relationship {#business-relationship} The following fields are mandatory when the merchant has a business relationship: | **Field** | **Description** | |------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `onboardingType` | The type of Merchant Onboarding flow to start. For this scenario, set this to `Web`. The response returns a `flowUrl` that you redirect the merchant to so they can progress with the onboarding process. | | `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. | The following fields are optional: | **Field** | **Description** | |---------------------|---------------------------------------------------------------------------------------------------------------------------| | `language` | The language used on the screens during the Merchant Onboarding flow. | | `redirectUrl` | The URL that Mastercard Open Finance Pay redirects the merchant back to after they complete the Merchant Onboarding flow. | | `parentMerchantId` | Identifier of the parent merchant of a merchant store. | | `externalReference` | Identifier as specified within the external system. | ## Merchant Statuses {#merchant-statuses} A newly onboarded merchant can be in one of the following statuses: | **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. | ## 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. 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. ## Payment Destination Statuses {#payment-destination-statuses} A payment destination can be in one of the following statuses: | **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 performs is to verify the account's ownership, which usually requires additional documents. | | `SUSPENDED` | The account is suspended. | | `REJECTED` | The account is rejected and cannot be used. |