# Boarding overview

> Master the merchant boarding process from template creation to activation. Understand required KYC/KYB fields, application statuses, underwriting steps, and automated account provisioning

<AudienceInfo audiences={["developers", "partners"]} />

Boarding is the process of enabling a paypoint to process payments via Payabli, and is the first step toward monetizing payments. Boarding happens in stages. These stages include the initial submission of a merchant application, underwriting the merchant account, and configuration and backend setup to activate the merchant account and enable live processing.

To board and underwrite a merchant you need to collect key information about the business, the owners, and how they intend to process payments. This information is sent to underwriting to make sure the paypoint is legitimate, creditworthy, and isn't a fraud risk.

The start-to-finish boarding process looks like this. Hover over steps for more information.

<div class="flowchart-container-horizontal">
  <div class="flowchart-box-horizontal flowchart-tooltip">
    Send boarding link

    <span class="flowchart-tooltiptext">
      Send merchants a boarding link that's created using your boarding template.
    </span>
  </div>

  <div class="flowchart-arrow-horizontal">
    →
  </div>

  <div class="flowchart-box-horizontal flowchart-tooltip">
    Merchant applies

    <span class="flowchart-tooltiptext">
      The merchant fills out and submits the application, and e-signs the agreement.
    </span>
  </div>

  <div class="flowchart-arrow-horizontal">
    →
  </div>

  <div class="flowchart-box-horizontal flowchart-tooltip">
    Underwriting

    <span class="flowchart-tooltiptext">
      Payabli reviews and decides on the application.
    </span>
  </div>

  <div class="flowchart-arrow-horizontal">
    →
  </div>

  <div class="flowchart-box-start flowchart-tooltip">
    Paypoint created

    <span class="flowchart-tooltiptext">
      If the merchant's application is approved, the Payabli team converts them to a paypoint.
    </span>
  </div>
</div>

Templates, boarding applications, and boarding links all work together to get merchants ready for underwriting and going live.

Templates allow you to customize your merchant application for different boarding scenarios. The Payabli team creates your first template, called the *root template*. After you have a template, you can access a digital boarding link to send to merchants.

After the merchant enters their information in boarding link and submits it, it becomes an *application* in Payabli. You can monitor the progress of the merchant account from initial submission to underwriting to live and processing.

## Boarding process overview

For partners, the boarding process includes three main steps. Create a boarding template, generate boarding links for your paypoints, and wait for the paypoint to submit the application and go through underwriting.

<Steps>
  <Step title="Get your boarding template">
    Payabli's Templating system gives your organization the ability to decide what fields you want to capture in a boarding link. This flexibility lets you send different boarding links to different paypoint segments. For example, you can use different templates to present different pricing to small and medium business (SMB), middle-market (MM), and enterprise paypoints. [Pricing packages](/guides/pay-ops-billing-and-fees-overview) are also built into the templates.

    The Payabli team creates boarding templates for you. Your first template is the root template, and it's used most often in testing and to build other templates. Many organizations only need the root template, but you can work with Payabli to create as many as needed for your use case.
  </Step>

  <Step title="Send boarding link">
    After your boarding template is created, you can send the boarding link to prospective merchants. The merchant uses the boarding link to create an application. They can save their application and return to complete the application later.

    After the merchant submits their application via the boarding link, the application data is securely stored in Payabli. Payabli underwrites each merchant for payment acceptance. When the merchant is approved, Payabli activates their payment processing features and alerts the organization.
  </Step>

  <Step title="Set up notifications">
    Stay up-to-date on paypoint boarding status by subscribing to the boarding webhook notifications or set up notifications in PartnerHub or via the API.

    <div>
      <table>
        <thead>
          <tr>
            <th>
              Notification
            </th>

            <th>
              Description
            </th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>
              CreatedApplication
            </td>

            <td>
              A new boarding application was created.
            </td>
          </tr>

          <tr>
            <td>
              SubmittedApplication
            </td>

            <td>
              A boarding application was received to process.
            </td>
          </tr>

          <tr>
            <td>
              ActivatedMerchant
            </td>

            <td>
              A new merchant account was activated.
            </td>
          </tr>

          <tr>
            <td>
              HoldingApplication
            </td>

            <td>
              An application was put on hold.
            </td>
          </tr>

          <tr>
            <td>
              DeclinedApplication
            </td>

            <td>
              A boarding application was declined.
            </td>
          </tr>

          <tr>
            <td>
              BoardingApplication
            </td>

            <td>
              An application passed to boarding status.
            </td>
          </tr>
        </tbody>
      </table>
    </div>

    Learn more about [Notifications](/guides/pay-ops-notifications-webhooks-overview)
  </Step>

  <Step title="Activate and test">
    When the merchant is approved and activated, Payabli converts them to a paypoint. They can then run test transactions to make sure the account is working as expected. You can use the `ActivatedMerchant` webhook to receive the [entry name](/developers/api-reference/api-overview#entrypoint-vs-entry) for the paypoint, which you need to complete setup.

    When testing boarding functions in the sandbox, applications don't automatically move from one status to another like they do in the production environment. When you're ready to test different boarding scenarios, let the Payabli team know when you want to move applications between statuses.
  </Step>
</Steps>

## Required fields for boarding

Certain Know Your Customer (KYC) and Know Your Business (KYB) fields are required for all boarding applications. These fields are required to ensure that Payabli meets regulatory standards and helps prevent fraud. The required fields depend on the merchant type (individual or business) and the region where the merchant is located.

This interactive tool helps you understand which fields are required based on your boarding template configuration. Select the options that match your boarding scenario to see the required fields.

<BoardingFieldValidator />

Merchant underwriting is a similar process to applying for a mortgage or car loan. Payabli must gather certain information from merchants to meet federal know-your-business (KYB) and know-your-customer (KYC) requirements, and to confirm a merchant's trustworthiness.

All applicants must complete a Payabli Merchant Application that includes the legal information for the business, and information about each beneficial owner. Other documents may be required if the screening verification doesn't return any verifiable digital validation.

**Business information**

* Legal entity name of business registered with the IRS and the state in which the business is incorporated. If Payabli can't verify the legal name during underwriting, we may request the applicant's SS-4 (A document from the IRS that confirms the EIN and managing member of the business being underwritten) or articles of incorporation.
* Federal Tax ID: EIN/TIN. For a sole proprietorship, the sole proprietor may use their Social Security Number (SSN).
* Applicable DBA ("doing business as") name or trade names registered to the legal entity that's applying.
* Business legal address. This is the principal place of business or a local office.
* Business Type and description of product sold and or service provided. This description must be detailed enough for Payabli to determine the merchant's Merchant Category Code (MCC).
* Business website URL.

**Beneficial owner information**

For *each* beneficial owner, Payabli needs the following information:

* Legal name
* Date of birth
* Contact information: current U.S. residence address, direct phone number, and direct email address
* Identification number: either a Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN)
* Driver's license number and state of issuance

Payabli uses this information to verify the individual's identity and their relationship with the business.

{/* vale Payabli.Contractions = NO */}

To learn more about beneficial ownership, see [What is beneficial ownership?](/guides/pay-ops-boarding-kyc-fields-overview#beneficial-ownership).

{/* vale Payabli.Contractions = YES */}

## Application and boarding status

Applications go through several statuses during the boarding process. These statuses help you track where an application is in the process, from submission to activation. You can check the status in PartnerHub or with the API.

### Check boarding status in PartnerHub

To check a boarding application's status in PartnerHub, navigate to **Portfolio > Applications**, and then find the application in the table. The boarding status appears in the **Status** column.

<Info>
  Substatuses aren't currently available in PartnerHub. If you have a question about an application, reach out to the Payabli team.
</Info>

### Check boarding status with the API

To check an application's boarding status with the API, send a GET request with the `appId` to [`/api/Boarding/read/{appId}`](/developers/api-reference/boarding/get-boarding-application-by-id). The status is returned in the response as `boardingstatus`.

This example queries the application with ID `100`.

```curl Request
curl --request GET \
    --url https://api-sandbox.payabli.com/api/Boarding/read/100 \
    --header "accept: application/json" \
    --header "requestToken: <API TOKEN>"
```

A successful response returns the boarding status in the `boardingStatus` field.

```json Response
// Response truncated to show only the relevant fields
{
  "idApplication": 100,
  ...
  "boardingStatus": -99,
  ...

}
```

### Statuses

These are the available `boardingStatus` values.

<div id="boarding-status">
  <table>
    <thead>
      <tr>
        <th>
          Value
        </th>

        <th>
          Key
        </th>

        <th>
          Description
        </th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          Not Submitted
        </td>

        <td>
          -99
        </td>

        <td>
          The application is incomplete or hasn't been submitted yet.
        </td>
      </tr>

      <tr>
        <td>
          Declined
        </td>

        <td>
          0
        </td>

        <td>
          The application has been declined.
        </td>
      </tr>

      <tr>
        <td>
          Pending Signature
        </td>

        <td>
          2
        </td>

        <td>
          The application is waiting on the applicant's signature.
        </td>
      </tr>

      <tr>
        <td>
          Underwriting
        </td>

        <td>
          3
        </td>

        <td>
          The application is in underwriting.
        </td>
      </tr>

      <tr>
        <td>
          Submitted
        </td>

        <td>
          4
        </td>

        <td>
          The application is complete and submitted, but hasn't moved to underwriting yet.
        </td>
      </tr>

      <tr>
        <td>
          Manual Review
        </td>

        <td>
          6
        </td>

        <td>
          The application is in underwriting and requires further review.
        </td>
      </tr>

      <tr>
        <td>
          Approved
        </td>

        <td>
          7
        </td>

        <td>
          The application has been approved and is queued for boarding.
        </td>
      </tr>

      <tr>
        <td>
          Withdrawn
        </td>

        <td>
          8
        </td>

        <td>
          The applicant has voluntarily withdrawn their application.
        </td>
      </tr>

      <tr>
        <td>
          Boarding
        </td>

        <td>
          10
        </td>

        <td>
          The application is boarding with our service providers, banks, and Payabli.
        </td>
      </tr>

      <tr>
        <td>
          Activated
        </td>

        <td>
          99
        </td>

        <td>
          The paypoint has been created, and all configurations have been completed, but the paypoint hasn't processed a transaction yet.
        </td>
      </tr>

      <tr>
        <td>
          Live
        </td>

        <td>
          100
        </td>

        <td>
          The paypoint has successfully processed a pay in or pay out transaction.
        </td>
      </tr>

      <tr>
        <td>
          Exception Error
        </td>

        <td>
          -1
        </td>

        <td>
          An unidentified error has occurred with this application. Contact support to review.
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Substatuses

Some statuses have substatuses to give you more information about where an application is in the process. These aren't available in PartnerHub, so use the API to check them.

#### Manual Review substatus

These statuses may appear when an application is in the Manual Review (6) status.

<div id="manual-review-substatus">
  <table>
    <thead>
      <tr>
        <th>
          Value
        </th>

        <th>
          Key
        </th>

        <th>
          Description
        </th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          Pending Review
        </td>

        <td>
          1
        </td>

        <td>
          The application was flagged during underwriting and is waiting on manual review.
        </td>
      </tr>

      <tr>
        <td>
          Pending Documentation
        </td>

        <td>
          2
        </td>

        <td>
          The reviewer has requested additional documents from the applicant or org.
        </td>
      </tr>

      <tr>
        <td>
          Pending Action
        </td>

        <td>
          3
        </td>

        <td>
          An additional task has been requested from the applicant or org.
        </td>
      </tr>

      <tr>
        <td>
          Missing Data
        </td>

        <td>
          4
        </td>

        <td>
          The application needs additional data to complete underwriting.
        </td>
      </tr>
    </tbody>
  </table>
</div>

#### Boarding substatus

These statuses may appear when a merchant is in the Boarding (10) status.

<div id="boarding-enablement-substatus">
  <table>
    <thead>
      <tr>
        <th>
          Value
        </th>

        <th>
          Key
        </th>

        <th>
          Description
        </th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          ServiceProvider Review
        </td>

        <td>
          5
        </td>

        <td>
          The application was submitted to service provider for review, validation, and boarding.
        </td>
      </tr>

      <tr>
        <td>
          ServiceProvider Processing
        </td>

        <td>
          6
        </td>

        <td>
          The application is processing and waiting on final results.
        </td>
      </tr>

      <tr>
        <td>
          ServiceProvider Hold
        </td>

        <td>
          7
        </td>

        <td>
          The service provider requires additional information or a correction from the applicant, org, or Payabli.
        </td>
      </tr>

      <tr>
        <td>
          Pending Configuration
        </td>

        <td>
          8
        </td>

        <td>
          The paypoint has been created and is waiting on configuration and activation.
        </td>
      </tr>
    </tbody>
  </table>
</div>

#### Declined substatus

These substatuses may appear when an application has a Declined status (0).

<div id="boarding-declined-substatus">
  <table>
    <thead>
      <tr>
        <th>
          Value
        </th>

        <th>
          Key
        </th>

        <th>
          Description
        </th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          Standard Decline
        </td>

        <td>
          9
        </td>

        <td>
          The application has been declined for a reason. The reason is provided in the status text.
        </td>
      </tr>

      <tr>
        <td>
          Credit Decline
        </td>

        <td>
          10
        </td>

        <td>
          The application has been declined for a reason. The reason is provided in the status text.
        </td>
      </tr>
    </tbody>
  </table>
</div>

## Related resources

See these related resources to help you get the most out of Payabli.

<AccordionGroup>
  <Accordion title="Next steps">
    * **[Add additional data to boarding applications](/guides/pay-ops-developer-boarding-add-data)** - Learn how `additionalData` works in boarding applications
    * **[API-driven boarding quickstart](/guides/pay-ops-developer-boarding-quickstart)** - Learn to use example code to set up a custom app for boarding using the Payabli API
    * **[Boarding application field explorer](/guides/pay-ops-boarding-field-explorer)** - Learn how boarding application fields interact and which are required and recommended
    * **[Bulk boarding guide](/guides/pay-ops-boarding-bulk)** - Learn how to bulk board merchants in Payabli
    * **[Manage boarding in the UI](/guides/pay-ops-portal-boarding-manage)** - Learn how to manage the boarding process for paypoints in the Payabli UI
  </Accordion>

  <Accordion title="References">
    * **[Boarding statuses reference](/guides/pay-ops-boarding-status-reference)** - Learn about statuses and substatuses during the merchant boarding process
    * **[Paypoint statuses](/guides/pay-ops-paypoint-status-reference)** - Learn about the different statuses of paypoints
    * **[Pay In TransEvent reference](/guides/pay-in-transevents-reference)** - Learn about TransEvent values for pay in transactions
  </Accordion>

  <Accordion title="Related topics">
    * **[Required fields for boarding applications](/guides/pay-ops-boarding-kyc-fields-overview)** - Learn more about the know-your-customer (KYC) and know-your-business (KYB) fields required for merchant onboarding
  </Accordion>
</AccordionGroup>