# Marketplace Integration

After fully integrating the April checkout using our **[direct API integration](/developer-portal/direct-integration-landing)**,
it can now be modified to better serve business to business transactions alongside business to customer transactions.

If you are using April in a more conventional business to customer configuration, this section is not relevant to your integration.

## Terminology

For this configuration, we will use the following terminology to identify participants in this type of relationship:

- **Marketplace:** The entity setting up integration with April. A *marketplace* functions as a service for
other entities (*sub-merchants*) to sell products or services through. Examples of *marketplaces* include
invoicing providers, trading platforms, online marketplaces, digital property portals or rental services.
- **Sub-merchant:** An entity conducting business through the *marketplace*. A *marketplace* has a
B2B relationship with a number of *sub-merchants*. Examples of *sub-merchants* include rental property owners,
artists, or product re-sellers using the marketplace to list, advertise and sell their products or services.
- **Customer:** An entity buying the products or services provided by the *sub-merchant*.


## Marketplace API key and Merchant tokens

The marketplace will be issued with an API key used to make calls from its backend system to April’s API for
onboarding sub-merchants and performing various functions on their behalf.
Each sub-merchant onboarded will be given Publishable and Secret API merchant keys to be primarily used in
the checkout flow to create payments for their customers.

## Sub-merchant Onboarding

Sub-merchants need to be onboarded to the marketplace through April before they can start making payments.
If the marketplace already has a sub-merchant onboarding process they can use
April’s onboarding API to add April integration to their existing process.

Onboarding sub-merchants in April requires the following information:

- Business name, business type, industry, tax ID, and tax country.
- Email addresses for admin and support staff.
- A custom URL to use for dashboards.
- The business name that appears on customer’s card statements.
- Title, role, name, date of birth, email, addresses, phone number and identity document scans for beneficial owners of the sub-merchant.


In some cases, generally when the business name doesn't match the registered name for the ABN, April might also require a scan of the Certificate of Registration.

### Onboarding with April API

We encourage using the April API onboarding endpoints for marketplaces with their own established sub-merchant onboarding process.
This will streamline the experience for the sub-merchants, keeping them on the marketplace’s site and avoiding asking for sub-merchant details twice.


```mermaid
sequenceDiagram
  participant MA as Marketplace service
  participant API as AprilAPI

  MA->>+API: Create sub-merchant account
  MA->>API: Provide business and bank details
  MA->>API: Upload identity document scans
  API->>API: Trigger KYB checks

Note over MA,API: KYC is asynchronous but typically takes seconds or minutes to complete

  loop While issues with KYB
    MA->>+API: Query status of sub-merchant KYB
    API->>-MA: Notify status of KYB and any required remediations
    MA->>API: Upload any additional requirement information
    API->>API: Trigger KYB checks
  end
```

To begin the sub-merchant onboarding process, the marketplace backend process will call the [Create Merchant](/openapi/april-public/merchants/createmerchant) endpoint.

On success, the API will return the April internal ID for the sub-merchant account. This `merchantId` will be required for subsequent calls.

Once the sub-merchant account has been created the following API endpoints must be called **in order** to complete the onboarding process:

1. [Upload Merchant File](/openapi/april-public/merchants/uploadmerchantfile) - for partnerships a scan of a partnership agreement needs to be uploaded. For trusts a trust deed is required. Retain the file ID for the next step. For all other types of businesses, this step can be skipped.
2. [Update Merchant](/openapi/april-public/merchants/updatemerchant) **Update Merchant Business Profile** - set general sub-merchant company details. Can be called more than once to update any details if they change.
3. [Upload Merchant File](/openapi/april-public/merchants/uploadmerchantfile) - upload a scan of each beneficial owner’s identity document (passport or driver’s licence, front and back). Retain the returned file ID for the next step.
4. [Create Beneficial Owner](/openapi/april-public/merchants/createbeneficialowner) - call for each owner and enter personal details and scanned identity document file IDs from the previous step.
5. [Update Merchant](/openapi/april-public/merchants/updatemerchant) **Add Merchant Bank Account** - add sub-merchant bank account details.


The maximum size for uploaded files is 10MB and the supported formats are JPEG, PNG and PDF.

Once these steps are complete, please [contact support](https://limepay.zendesk.com/hc/en-us) who will perform one final check and enable payments for the sub-merchant completing the onboarding process.

### Customer Experience

Customers engage with the April checkout within the branded environment of the marketplace or sub-merchants.
Those who have elected to pay in instalments will receive communication directly from April
and can manage their payments through the April customer dashboard. Both the dashboard and these communications
can be customised to fit the branding of the marketplace or sub-merchant via the April merchant dashboard.

## What's next?

Marketplace merchants may wish to action **[transaction transfers](/developer-portal/transaction-transfers)** between themselves and merchants.

br
br
**[Return to documentation home](/).**