> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/operational-guides/merchant-onboarding-guide.md).

# Merchant Onboarding Guide

This guide explains the operational flow for onboarding a merchant with Bead. It complements the API reference and schema pages and is intended for integrators, solution engineers, and project managers.

#### Who this is for

* Integrators submitting merchant data
* Resellers coordinating merchant onboarding and credentials
* Teams planning downstream provisioning of locations and terminals

#### Prerequisites

* API key for the non production or production environment
* Partner or integrator account configured
* Merchant contact name and email ready
* Basic business profile details gathered
* Partner fee schedule floor resolved via `GET /Partners/{id}/fee-schedule` — merchant fee `sellRate`s below this floor will be rejected

#### End to end flow

<table><thead><tr><th width="79">Step</th><th width="116">Actor</th><th width="113">Interface</th><th>What happens</th><th>Output</th></tr></thead><tbody><tr><td>1</td><td>Integrator</td><td>API</td><td>Submit KYB payload to <code>POST /merchant-onboarding/applications</code> with business, contact, banking, and owners</td><td><code>applicationId</code></td></tr><tr><td>2</td><td>Bead</td><td>System</td><td>Sends onboarding email to merchant contact using the submitted details</td><td>Merchant receives secure onboarding link</td></tr><tr><td>3</td><td>Merchant</td><td>Web</td><td>Completes missing details, uploads documents, e signs</td><td>Application ready for review</td></tr><tr><td>4</td><td>Bead</td><td>Review</td><td>Compliance review and decisioning</td><td>Approval or request for more info</td></tr><tr><td>5</td><td>Integrator</td><td>APIs</td><td>After approval, retrieve the default Location and Terminal(s) Bead created and read off their credentials</td><td>Terminal credentials available for payment flows</td></tr></tbody></table>

#### What to send in the initial payload

* Business identity and address
* At least one contact with name and email
* Banking details for settlement
* Owner and officer details for KYB
* Fee configuration priced at or above the partner's fee schedule floor — see [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md)

See Reference Guide → Enumerations and Schemas → Merchant Onboarding Schema for field definitions.

#### Email and link handling

* The onboarding email is sent automatically to the contact you submit; the signing link is delivered by DocuSign directly to that contact and is not returned to you in the API response
* If the merchant loses the email or the link expires, use `PUT /merchant-onboarding/applications/{applicationId}` to resend — this regenerates the signing envelope rather than reissuing the original link, so treat it as a fresh request rather than a nudge
* If you need to change the contact email later, submit an update through your standard process and resend using the same endpoint

#### Authentication

* Authenticate using your API key — include it on every onboarding request
* Log the `requestId` from error responses for support

#### Handling errors and duplicates

* Validation issues return a 400 with `fieldErrors` describing which fields failed
* If you see 409 Conflict for an existing application
  * Avoid re submitting the same merchant repeatedly
  * Reuse the existing application indicated by your records
* Use clear customer messaging when requesting missing documents or corrections

#### Merchant approval and next steps

After approval, onboarding continues automatically: when the application reaches `boarded`, Bead creates a default Location and default Terminal(s) for the merchant. The merchant cannot accept payments until you:

1. Retrieve the default Location and Terminal(s) Bead created (see [Location Management](/entity-management/location-management.md#what-boarding-creates) for the full mapping from `locationBusinessType` to what gets created)
2. Verify the terminal(s) match the expected configuration for this merchant
3. Set the terminal webhook URL on each terminal you intend to use

Do not create a new Location or Terminal for the merchant — boarding has already created them. Creating your own duplicates the record Bead created and leaves ambiguity about which terminal's credentials the reseller should receive.

#### Operational tips

* Maintain a simple tracker for each application
  * `applicationId`, merchant legal name, primary contact, current status, documents outstanding
* Automate reminders
  * If an application has no progress for two days, resend the link to the merchant and notify your contact
* Keep roles clear
  * Integrator submits and tracks
  * Merchant completes and signs
  * Bead reviews and approves
* Coordinate early on banking
  * Confirm the business bank details match the legal entity name to reduce rework

#### Frequently asked questions

**Can we onboard using a single integrator login for all merchants**\
Payments authenticate per merchant. For onboarding, you must use a valid API key and submit each merchant individually. There is no one login to act on behalf of every merchant for payments.

**How do we re send the onboarding link**\
Call `PUT /merchant-onboarding/applications/{applicationId}`. This regenerates the signing envelope rather than resending the original link, so the merchant will receive a new email.

**When are credentials available**\
Credentials are available on the default Terminal(s) Bead creates once the application reaches `boarded` — see [Location Management](/entity-management/location-management.md#what-boarding-creates). They are not returned by the onboarding endpoint.

#### Checklist

* Payload includes business, contact, banking, and owners
* Partner fee schedule floor resolved and fee configuration priced at or above it
* API key configured for the target environment
* `applicationId` stored
* Merchant completes documents and signing
* Application reached `boarded`; default Location and Terminal(s) confirmed
* Terminal webhook set on the terminal(s) you're using


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/reference-guide/operational-guides/merchant-onboarding-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.