> 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, then reset the API key on each terminal you will use to obtain its terminal payments API key</td><td>Terminal payments API key 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](https://developers.bead.xyz/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 default Location and Terminal(s) exist as soon as the application shows `boarded`, so you can retrieve them right away. The merchant cannot accept payments until you:

1. Retrieve the default Location and Terminal(s) Bead created (see [What boarding creates](https://developers.bead.xyz/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. Reset the API key on each terminal you intend to use and store the returned `apiKey.secret` (see [Reset Terminal API Key](https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key.md)). Terminal records returned by List Terminals and Get Terminal show only the masked key.
4. 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**\
The default Terminal(s) Bead creates exist once the application reaches `boarded` (see [What boarding creates](https://developers.bead.xyz/entity-management/location-management.md#what-boarding-creates)). The terminal payments API key is not returned by the onboarding endpoint or by terminal reads. Obtain it by resetting the terminal API key.

#### 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 API key reset and stored for each terminal you're using
* 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
