Decision guide: Merchant boarding

Intelligent boarding gives you two ways to board a merchant. You can collect everything in your own platform and submit the application with the API. Or you can create the application with the API and send the merchant to the Payabli-hosted form to finish it. Use this guide to choose between them, then follow the linked guides to build it. For the objects behind both approaches, see Intelligent boarding overview.

Considerations

• Both approaches use the boarding API, which uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
• Every application needs a boarding template, because Payabli reviews the application with the template’s underwriting settings. The template’s custom questions and document requirements also apply to the application. To find your template’s reference, see Manage boarding templates with the API.
• Plan to follow each application’s status with webhooks and polling. See Track the application.
• Both approaches produce the same application, follow the same statuses, and end with the same activated paypoint.
• If you already board merchants with the legacy Boarding endpoints, see Migrate from legacy boarding to intelligent boarding.

Compare the approaches

The approaches differ in who collects the merchant’s details and who builds the experience the merchant sees:

Form validation means checking what the merchant enters in your forms. Either way, the API tells you when a field is missing or invalid when you validate the application.

In short:

• Choose API-driven boarding when you want the merchant to stay in your platform and you can build the forms to collect and validate their details. The API is also the recommended way to add services to a paypoint over time.
• Choose the hosted form when you want Payabli to handle the merchant-facing form, the signature, and document uploads, and sending the merchant to a Payabli-hosted page works for your platform.

Board with the API

With API-driven boarding, your integration creates the business, its people, its paypoint, and the application. Then it validates the application and submits it with the signer’s signature details. Pick the workflow that matches what the merchant needs:

• A business that’s new to Payabli: Board a new business with the API.
• A new location for a business that’s already on Payabli: Add a location for a business with the API.
• More Pay In or Pay Out services for a paypoint that’s already boarded: Request more services with the API.

For each step on its own, see Manage applications with the API.

Send the merchant to the hosted form

With the hosted form, your integration creates the records with the API, and the merchant completes and submits the application on a Payabli-hosted page.

1. Create the paypoint and its business, and add what you already know about the business and its owners. Follow the first steps in Board a new business with the API, up to creating the application.

2. Create the application with a POST request to /v2/requests. Include the services the merchant needs, and set requestTemplate to your template’s reference. See Create an application.

3. Send the merchant the link to this application. Build it from the application’s requestsReference:

   • Sandbox: https://app-sandbox.payabli.com/boarding/app/{requestsReference}
   • Production: https://app.payabli.com/boarding/app/{requestsReference}

   If you use a custom domain for the hosted form, use your configured domain in place of the Payabli host.

4. The merchant opens the link, completes the form, signs, and submits the application.

The link opens the application you created in step 2. When the merchant opens the link and signs in, the form loads all the data associated with the application at that moment. After the merchant opens the form, updating those records with the API isn’t recommended. The updates don’t apply to the open session, and the session’s data takes priority.

If the business has another application that’s still open, the hosted form shows the message Another application for this business is already in progress. Before you send the link, finish the other application or withdraw it.

Track the application

After the application is submitted, both approaches work the same way. Payabli reviews it and moves it through its statuses until the paypoint is activated or the application is denied.

• Subscribe to the boarding webhooks to hear about submission, approval, denial, and activation as they happen. Intelligent boarding sends the same events as legacy boarding. See Status webhooks.
• Poll the application for the statuses that send no webhook. These include pendingdocuments and pendingresponse, which mean underwriting is waiting on you. See Track status changes.
• When underwriting requests documents or information, respond with the API. See Respond to underwriting requests.

Legacy boarding

Legacy boarding, with its prefilled applications and template boarding links, is documented in the Legacy boarding section of the navigation. Start with Boarding overview. For new integrations, use intelligent boarding.

Related resources

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