Onboarding

The Onboarding APIs enable programmatic submission of merchant applications, sending hosted applications to signers, and tracking status through approval.

You can either send a comprehensive application with most data prefilled, or create a minimal application that the merchant completes in the hosted flow. Use this section when you want to automate KYB and onboarding instead of relying only on manual portal workflows.

Onboarding works together with Entity Management, Reporting, and Settlement:

• Onboarding collects and reviews merchant data

• Entity Management creates merchants, locations, and terminals after approval

• Payments, Reporting, and Settlement use those entities for processing, history, and funding

When to use Onboarding

Use the Onboarding APIs when you want to:

• Create merchant applications from your own UI

• Generate a hosted onboarding package for one or more signers

• Let signers review and sign the application securely, without exposing raw KYB APIs to the browser

• Track application status, including missing fields and risk decisions

• Resume a partially signed application if a signer drops off

• Subscribe to webhooks for application events such as submitted, approved, declined, or needs info

If you do not need to manage onboarding programmatically and only submit a few merchants, you can coordinate with Bead to use portal-based boarding instead.

Application types

There are two primary ways to initiate an application through the API.

Full application

• Endpoint: POST /merchant-onboarding/applications

• Request body: InitiateOnboardingRequest

You send a comprehensive request that includes:

• Business identity and contact information

• Ownership structure and controlling persons

• Banking details

• Fee configuration, such as tender fees and settlement fees

• signerInfo with signer details

This is best for partners who already have most merchant data in their own systems and want to prefill the application so the signer mostly reviews and confirms.

Minimal or “empty” application

• Endpoint: POST /merchant-onboarding/applications-short

• Request body: InitiateEmptyOnboardingRequest plus fee configuration, as defined in the current specification

You send the minimum required details so that Bead can create an application shell and invite the signer to complete the rest in the hosted flow. At a minimum this includes:

• Merchant identity and your partner references

• signerInfo for the recipient

• Fee configuration for the merchant

This path is designed for partners who want to minimize data collection in their own systems and let the merchant supply most information directly in the hosted flow.

Required signer and fee information

For both application types:

• You must provide signerInfo so Bead knows who should receive and sign the application.

• You must provide fee information because fees are not editable in the hosted application.

You cannot send a completely empty application without signer and fee data. If you attempt to omit fees, the request will be rejected or fail validation because the signer cannot correct fees in the page.

High level flow

A typical programmatic onboarding flow looks like this.

1. Create an application

Choose one of the two entry points.

• Full application

  • Call POST /merchant-onboarding/applications with business identity, contacts, owners, banking details, fee configuration, and signerInfo.

• Minimal or empty application

  • Call POST /merchant-onboarding/applications-short with merchant identifiers, signerInfo, and fee configuration. The hosted flow will collect the remaining data from the signer.

Both endpoints return a MerchantOnboardingResponse that includes:

• applicationId

• envelopeId

• status

• signingUrl may be null

2. Deliver the signing experience

By default, Bead sends the onboarding email directly to the merchant signer using the signer email provided in signerInfo.

• The merchant signer receives a secure email invitation to review and sign the application.

• The email content and delivery behavior are handled by Bead and its provider.

If signingUrl is present in the response, you can also:

• Use it in your own email or SMS messaging

• Expose it in your portal for click-to-complete onboarding flows

You should still plan for the email flow as the primary delivery method and treat signingUrl as an additional convenience.

3. Signer reviews and signs

• The signer opens the hosted onboarding experience from the email or from your use of signingUrl.

• For full applications, the signer reviews prefilled information and confirms or adds any missing fields.

• For minimal applications, the signer supplies most of the required details directly in the hosted flow.

• The hosted flow captures signatures and required consents.

4. Track status and completeness

• Call GET /merchant-onboarding/applications/{applicationId} to retrieve status and any completeness indicators.

• Configure webhooks so your system is notified when the application state changes, such as:

  • submitted

  • needs info

  • approved

  • declined

Your integration can then update merchant records, trigger internal tasks, or notify users based on these events.

5. Handle edge cases

• Use resume signing flows when a signer stops partway through the process.

• Use manual risk feedback when additional information is required from the merchant.

• Decide how you will surface needs-more-information states to your own users.

6. After approval

• Once the application is approved, use Entity Management APIs to create or update merchants, locations, and terminals based on the approved data.

• Payments, Reporting, and Settlement then use those entities for processing, reconciliation, and funding.

Each step is covered in more detail on the Onboarding subpages.

Core objects and schemas

Onboarding relies on shared schemas documented in the Reference Guide.

Merchant onboarding request (full)

• Schema: InitiateOnboardingRequest

• Used by POST /merchant-onboarding/applications

Contains:

• signerInfo with signer details

• merchantData which includes:

  • Merchant identity and contacts

  • Ownership and control information

  • Banking details for settlement

  • Fee configuration, including tender fees and settlement fees

Merchant onboarding request (minimal)

• Schema: defined by InitiateEmptyOnboardingRequest plus the fee configuration fields described in the current specification

• Used by POST /merchant-onboarding/applications-short

Contains at least:

• Merchant identity and partner references

• signerInfo

• Fee configuration for the merchant

The hosted onboarding flow will collect any remaining required details from the signer.

Merchant onboarding response

• Schema: MerchantOnboardingResponse

• Returned by both application types

Contains:

• applicationId

• envelopeId

• status such as unsent, sent, completed, or declined

• signingUrl string, may be null

You should always store applicationId and envelopeId so you can query status and reconcile with other systems. If you plan to use signingUrl, design your flow to handle the case where it is null and rely on email delivery as the primary mechanism.

Subpages in this section

The Onboarding section is structured as a set of task-based pages.

• Submit Application

  • How to call POST /merchant-onboarding/applications for a full application

  • How to call POST /merchant-onboarding/applications-short for a minimal or empty application

  • Required fields, example payloads, and typical responses for each pattern

• Get Status

  • How to call GET /merchant-onboarding/applications/{applicationId}

  • How to interpret status values and completeness indicators

  • How to tell when an application is ready for production use

• Resume Signing

  • How to re-engage a signer who abandons the flow

  • Recommended patterns for follow-up emails and reminders

• Webhooks for Application Events

  • Event types such as submitted, under review, needs info, approved, and declined

  • Payload format and best practices for idempotent processing and retries

• Manual Risk Feedback

  • How feedback from risk and compliance appears in APIs and webhooks

  • How to surface needs-more-information states to your merchants

• Sample Payload

  • Example request bodies for both the full and minimal application patterns

  • Useful as a starting point for your own integration or test harness

Use these pages alongside the Merchant Onboarding schemas in the Reference Guide when you implement your onboarding flow.

Relationship to other areas

Onboarding and Entity Management

• Onboarding collects and reviews merchant data.

• Entity Management creates and maintains merchants, locations, and terminals once onboarding is approved.

• Identifiers created or referenced during onboarding should be reused when you call Entity Management so the same merchant is represented consistently.

Onboarding and Payments, Reporting, Settlement

• Payments use merchantId, locationId, and terminalId created after onboarding.

• Reporting uses those identifiers to return payment history at partner, merchant, and terminal scopes.

• Settlement uses the same merchant identifiers to generate settlement batches and settlement line items.

A common pattern is:

1. Implement Onboarding and Entity Management for merchant lifecycle.

2. Implement Payments for transaction capture.

3. Implement Reporting and Settlement for reconciliation and funding visibility.

Getting started

Before you use the Onboarding APIs:

1. Obtain your onboarding API key and send it as:

X-Api-Key: {apiKey}

1. Review the Merchant Onboarding schemas in the Reference Guide to understand required and optional fields for both full and minimal application requests, including fee configuration fields.

2. Decide whether you will rely entirely on Bead’s email delivery for the onboarding invitation or also use signingUrl within your own messaging when it is available.

3. Plan how status changes will be handled in your system, either through polling or webhooks, and how manual risk feedback will be surfaced to your users.

4. Decide when to use the full application versus the minimal application path for your program, and how you will handle fee configuration and signer assignment in your own UI.