Decision guide: Merchant boarding

Build everything in your platform. Boarding applications are created and submitted entirely through API calls, and merchants never interact with Payabli’s forms or interface.

Key characteristic: No boarding links involved at any stage.

Create and prefill an application via API first, then send merchants a link to complete their specific application. This lets you populate known data while Payabli handles the completion UI.

Key characteristic: Link points to a specific application instance that you created and prefilled.

Workflow:

1. You create and prefill an application with merchant data via POST /boarding/application
2. You generate a link to this specific application
3. Merchant clicks the link, reviews, and completes their prefilled application on Payabli’s hosted form

Generate a link from a boarding template. When merchants click the link, it creates a new application instance that they complete on Payabli’s hosted form.

Key characteristic: Link is generated from a reusable template. The application doesn’t exist until the merchant starts filling it out.

Workflow:

1. You generate a link from a boarding template (via API or Payabli dashboard)
2. You send the link to merchants
3. Merchant clicks link and Payabli creates a new application from the template
4. Merchant completes the application and submits

Full API-driven boarding is the right choice when you need a fully embedded, white-labeled experience where merchants never leave your application.

You should also consider this approach if you need:

• Custom validation rules beyond Payabli’s standard validation
• Specialized approval workflows that integrate with your internal systems
• Complete control over the user interface and boarding flow

The complete control this approach provides allows you to build boarding experiences that match your business processes.

The API-driven approach has the highest development investment of the three boarding options. Initial implementation can span several weeks to months depending on your team’s size and experience. Beyond the initial build, you’re also responsible for any ongoing updates when Payabli’s requirements or APIs change.

A full API-driven solution requires careful planning, development, testing, and refinement before launch. It can take longer to get up and running compared to Payabli’s boarding link options.

However, the effort invested delivers returns in control and customization. You maintain complete ownership of the user experience, allowing you to create boarding flows that match your brand and integrate seamlessly with your existing workflows.

For organizations where white labeling or custom approval processes are essential, this approach is the only path forward.

When you choose API-driven boarding, you take on the responsibility of building and maintaining the entire boarding user interface, including:

• Forms for securely collecting business information, owner details, and banking credentials
• Managing the look and feel of the experience
• Implementing validation logic that matches Payabli’s backend requirements

Application status tracking becomes your responsibility as well, which means:

• Monitoring submission progress
• Handling any errors that occur during processing
• Providing clear feedback to merchants when issues arise
• Building retry logic for network failures
• Creating helpful error messages that guide merchants toward resolution

The API-driven approach has several technical considerations. You must handle sensitive data like social security numbers and bank account information with appropriate encryption and access controls. All API communications should use HTTPS, and you should never log sensitive information.

Your validation logic needs to match Payabli’s backend requirements to avoid submission failures. This includes features like:

• Format validation for EIN and SSN
• Routing number verification
• Email and phone number format validation
• Ensuring all required fields are collected before submission

The tighter your validation aligns with Payabli’s requirements, the fewer errors your merchants will encounter.

File handling requires secure upload mechanisms and appropriate file type validation. You need to:

• Support PDF, PNG, and JPG formats
• Enforce reasonable file size limits
• Handle upload failures gracefully
• Provide retry capabilities when network issues occur

The Payabli team can help you understand specific technical requirements, so reach out with any questions.

Prefilled applications with boarding links work best when you already have merchant data from your platform and can use it to streamline the boarding experience. This approach is ideal when you’re comfortable redirecting merchants to Payabli’s domain for the final completion steps, allowing you to minimize development effort while still providing a convenient, pre-filled experience.

You should consider this approach when:

• Quick time-to-market is a priority
• You have merchant data available to prefill application fields
• You’re comfortable with merchants seeing Payabli branding during completion
• You want to save merchants time by reducing manual data entry

The ability to prefill known information saves merchant time and reduces friction, while Payabli handles all the complex aspects of form validation, document collection, and legal agreement execution.

While this approach offers advantages, there are some considerations to keep in mind. Merchants will see Payabli branding during the completion process, which means you don’t maintain complete control over the visual experience. The workflow follows Payabli’s standard boarding process, so if you need custom approval flows or conditional logic based on merchant characteristics, this approach won’t work for you.

A redirect is required for agreement execution, meaning merchants briefly leave your app’s context to complete the boarding process. For organizations where maintaining complete white labeling consistency is critical, the full API-driven approach may be more appropriate despite its higher implementation effort.

The prefilled application and boarding link approach follows this process:

1. Create application via API: Use POST /boarding/application to create a new application and include merchant data you’ve already collected
2. Pre-fill known data: Include business information, contact details, banking credentials, owner information, and any other data you have
3. Generate application-specific link: Use the API to create a secure link to this specific application instance
4. Deliver the link: Email it directly to merchants or display it within your app
5. Merchant completes the form: They arrive at Payabli’s hosted form where their data is pre-populated
6. Merchant reviews and completes: They verify pre-filled data, complete any missing fields, and upload required documents
7. Execute agreements: The merchant signs required agreements through Payabli’s eSign provider
8. Track progress: Receive webhook notifications about status changes throughout the process

When merchants click the link, they only need to complete missing fields and review the prefilled data for accuracy. Throughout this process, you receive webhook notifications about status changes, letting you track progress and respond when boarding is complete or requires attention.

Key advantage: The application already exists with merchant data before the link is sent. The link points to this specific application instance, not a generic template.

This approach delivers these key advantages:

For merchants:

• Save significant time by not re-entering information they’ve already provided to your platform
• Reduced likelihood of abandoning the application process due to fewer fields to complete
• Immediate visibility into what information is still needed
• Seamless experience across all devices with responsive design

For your development team:

• Minimal effort: only API calls required, no UI to build
• No complex validation logic to implement or maintain
• Zero document upload handling to manage
• Faster implementation than full API-driven approach

What Payabli handles:

• All form validation, progress saving, and error messaging
• Built-in document upload with file type validation, size restrictions, and secure storage
• Payabli’s eSign provider integration for legal compliance with agreement execution
• Mobile-responsive form design that works across all devices

Default boarding links are the right choice when:

• You don’t have merchant data to prefill applications
• The quickest possible time-to-market is your primary concern
• Payabli’s standard boarding workflow meets your needs
• Development resources are limited or unavailable

The default boarding link experience provides a proven, compliant boarding workflow that you can implement with minimal technical effort, allowing you to focus on other aspects of your platform integration.

The primary trade-off with the default boarding link experience is reduced control over the user experience. Consider these limitations:

• Merchants see Payabli branding throughout the entire process rather than your own brand
• The process follows Payabli’s standard workflow with no room for custom approval steps or conditional logic
• You can’t pre-populate merchant-specific data (though some basic pre-population via query parameters may be possible)
• You can’t implement custom validation rules beyond what Payabli provides as standard

While Payabli’s validation is comprehensive and covers all regulatory requirements, platforms with specific business rules or additional data requirements would need to collect that information separately. For organizations where these limitations are acceptable, the dramatically reduced development effort and maintenance burden often outweigh the loss of customization capabilities.

The default boarding link experience follows the simplest implementation pattern:

1. Generate a boarding link: Create a link from your boarding template via the Payabli dashboard or API
2. Send the link: Email it to merchants or redirect them from your application
3. Merchant clicks link: Payabli creates a new application instance from the template
4. Merchant completes application: They fill out the hosted form with business information, owner details, and banking credentials
5. Payabli handles everything: Form presentation, validation, document collection, and Payabli’s eSign provider agreement execution
6. Receive notifications: Get webhook updates when boarding is complete or action is required

You receive webhook notifications when key events occur, such as when boarding is complete or when action is required. This allows you to track merchant progress and respond appropriately in your own systems, even though the boarding process happens entirely on Payabli’s domain.

Key characteristic: The link is generated from a reusable template. No application exists until the merchant starts interacting with the form. This means the same link structure can be used for multiple merchants.

Optional enhancements:

You can enhance the default boarding link experience with a few customizations:

• Customize redirect URLs so merchants return to specific pages after they submit the application
• Configure webhook notifications to trigger specific workflows in your system, such as automatically provisioning merchant accounts or sending welcome emails

The Payabli boarding links approach delivers the fastest path to production of any boarding method:

Speed and simplicity:

• Zero user interface development required
• Hours to days implementation timeline
• Minimal ongoing maintenance burden
• Can generate links directly from Payabli dashboard (no code required)

Proven experience:

• Boarding workflow refined based on thousands of merchant applications
• Best practices for field ordering, help text, and error messaging built in
• Mobile-responsive design works seamlessly across all devices

Built-in features:

• Field validation and user guidance reduce merchant errors and abandoned applications
• Automatic progress saving allows merchants to complete applications across multiple sessions
• Payabli’s eSign provider handles all aspects of legal agreement execution in compliance with electronic signature requirements
• Document upload with built-in validation and secure storage

Embedded Experience Required:

If merchants must remain within your application for brand consistency or workflow integration, choose the Full API-Driven approach. This provides complete control but requires building all UI components.

Redirect Acceptable:

If merchants can be directed to Payabli’s domain for completion, use prefilled applications with boarding links (if you have data to pre-fill) or the default Payabli boarding link experience (if you don’t have data). These approaches significantly reduce development time.

Brand Consistency Importance:

• Critical: Full API-Driven only
• Important but flexible: Prefilled application with boarding links
• Flexible: Boarding links

Full Development Team Available:

With dedicated frontend and backend resources, the Full API-Driven approach enables complete customization.

Limited Development Resources:

Prefilled applications with boarding links or the default Payabli boarding link experience require minimal development effort. Implementation typically takes 1-2 weeks for Prefilled applications (mostly API integration and webhook handling) or hours to days for the default Payabli boarding link experience.

Time to Market:

• Fastest: The default Payabli boarding link experience (hours to days)
• Balanced: Prefilled applications with boarding links (days to weeks)
• Longest: Full API-Driven (weeks to months)

You Have Merchant Data:

If you’ve already collected merchant information through your platform (business details, contact info, banking information), Prefilled applications with boarding links let you pre-fill applications and save merchants time.

You Don’t Have Merchant Data:

If you’re starting fresh or haven’t collected merchant information yet, the default Payabli boarding link experience provides a complete form that merchants fill out from scratch.

You Want to Collect Everything Yourself:

If you want complete control over data collection and validation, Full API-Driven boarding is the only option that keeps merchants entirely within your application.

Complex Custom Workflows:

If you need custom approval flows, multi-step validations, or integration with internal systems, choose the Full API-Driven approach. This gives you complete control over the boarding lifecycle.

Standard Boarding Process:

If Payabli’s standard boarding workflow meets your needs, use boarding links (either prefilled applications or the default Payabli boarding link experience). This leverages proven processes and reduces maintenance burden.

Create Merchant Application:

• Endpoint: POST /boarding/application
• Use for: Full API-Driven and prefilled applications with boarding links
• Required: Business info, owner details, banking credentials
• Note: For prefilled applications, you create the application first, then generate a link to it

Generate Link from Template:

• Endpoint: POST /boarding/templates/{templateId}/generate-link
• Use for: default boarding links experience
• Required: Template ID
• Returns: Link that creates a new application when clicked

Generate Link for Existing Application:

• Endpoint: POST /boarding/application/{applicationId}/generate-link
• Use for: prefilled applications with boarding links
• Required: Application ID
• Returns: Link to specific application instance

Check Application Status:

• Endpoint: GET /boarding/application/{applicationId}
• Use for: Polling application status
• Returns: Current status, pending items, rejection reasons

Update Application:

• Endpoint: PATCH /boarding/application/{applicationId}
• Use for: Updating submitted applications
• Required: Application ID, fields to update

Additional Endpoints:

• Get boarding application by auth token
• List applications for an organization
• Get boarding link by ID

Subscribe to these webhook events to track boarding progress. For complete webhook payload details, see the webhook payloads reference.

MerchantBoardingStarted:

• Fires when: Merchant opens boarding link
• Use for: Tracking engagement
• Applies to: prefilled applications and the default Payabli boarding link experience

MerchantBoardingCompleted:

• Fires when: Merchant submits application
• Use for: Initiating internal boarding workflows
• Applies to: All approaches

MerchantBoardingApproved:

• Fires when: Application approved for processing
• Use for: Activating merchant features
• Applies to: All approaches

MerchantBoardingRejected:

• Fires when: Application requires corrections
• Use for: Notifying merchant of issues
• Applies to: All approaches

MerchantBoardingDocumentRequired:

• Fires when: Additional documents needed
• Use for: Requesting missing documentation
• Applies to: All approaches

Learn more:

• Notifications and webhooks overview