Intelligent boarding overview

Boarding is how a business becomes a live paypoint: an entity that can move money. You collect the business and owner details, run them through underwriting, and the paypoint is activated after approval.

A paypoint set up for Pay In accepts payments, which is what most people mean by a merchant. A paypoint can also be set up for Pay Out to send payments, or for both. The boarding process is what sets up all of them.

Read this before you build a boarding integration or configure boarding in the Payabli Portal. For help choosing an approach, see the boarding decision guide.

Boarding object model

Boarding centers on a set of objects. An organization contains suborganizations, paypoints, and templates. A paypoint is backed by a business. To request service, it uses an application based on a template, which the business and its people fill out. A paypoint’s billing comes from a default billing profile, and a template can override it. A business has payment methods.

Each object plays a distinct role:

• Organization — The top scope. It contains suborganizations, paypoints, and templates. Payabli turns on the organization settings, such as billing, risk, and funding, that determine which features the organization and its suborganizations can use. You can’t change these settings with the API. To turn on a new service, reach out to your Payabli contact.
• Paypoint — the entity that moves money. A paypoint set up for Pay In is a merchant; a paypoint can also be set up for Pay Out, or both. A paypoint belongs to an organization and is backed by a business. To request service, a paypoint uses an application that a template drives. Paypoints can nest under a parent paypoint, so an organization can model locations or business units as a hierarchy.
• Template — The organization creates and manages templates, which shape the applications paypoints use to request services. The template controls which sections appear, what an applicant can prefill, form labels, custom rules, the signing method, service selection, additional verification and search services, and underwriting settings. A template can also override the default billing profile for the paypoints boarded with it.
• Billing profiles — the fee schedules and pricing for Pay In and Pay Out. A paypoint uses the default billing profile unless its template overrides it. Templates work well when you have a small set of standard pricing packages, around 3 to 5. If you negotiate custom pricing with many merchants, Payabli can assign billing to a paypoint directly, during boarding or after it. To set that up, reach out to your Payabli contact.
• Application — a paypoint’s request for service, submitted on its behalf and driven by a template. A business and its people fill it out, and it moves through the status lifecycle covered next.
• Business — the legal entity being boarded. It holds legal details such as legal name, structure, tax reference, addresses, and contact information. It backs one or more paypoints, links one or more people (owners, signers, employees), and has payment methods. Identified by a businessUuid.
• People — the individuals on a business: owners, signers, and employees. People are shared entities: a person can be linked to more than one business, so the link is a business-person relationship rather than ownership. Each person carries identity details and a verification status.
• Payment methods — the bank accounts and cards a business holds, used to move money, for example the account where funds settle. Each has an owner, a type, a token reference, and a status. Deleting one sets its status to inactive rather than removing it.

The objects relate to each other like this:

Application lifecycle

An application moves through a series of statuses from the moment it’s created to the moment its requested services are live. The diagram shows the main path. For every status, its code, and what moves an application between statuses, see Boarding application statuses.

An application is created in draft, where you can still edit it. Submitting it starts review. Automated checks run first. From there, an application is either approved without a person (autoapproved) or routed to a reviewer (pendingreview). Reviewers can ask the applicant for documents or more information, escalate, approve, or deny. After all the requested services are boarded, the application moves to activated and those services are live.

Who acts on the application drives each transition:

• Reviewer actions move an application forward or back: approve, deny (a reason is required), escalate, or request documents or information.
• Applicant actions respond to those requests: provide documents, provide a response, or withdraw the application.
• The status history records every transition in order, so you can audit how an application reached its current state.

Two ways to build an application

The objects are the same whichever way you board a paypoint. What differs is who assembles the application.

• API-driven — your integration creates and populates the application through the boarding endpoints, then submits it. You control each step, and you can record who signed the application when you submit.
• Payabli-hosted flow — the applicant completes a Payabli-hosted experience. That flow assembles the template, pricing, and services and validates the application before it’s submitted. It’s keyed by the application’s requestsReference rather than your API credential.

Both paths converge on the same lifecycle above and produce the same paypoint.

Related resources

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