# 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

* OAuth access to the non production or production environment
* Partner or integrator account configured
* Merchant contact name and email ready
* Basic business profile details gathered

### End to end flow

| Step | Actor      | Interface | What happens                                                                                              | Output                                           |
| ---- | ---------- | --------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| 1    | Integrator | API       | Submit KYB payload to `POST /merchant-onboarding/application` with business, contact, banking, and owners | `applicationId`, `onboardingUrl`                 |
| 2    | Bead       | System    | Sends onboarding email to merchant contact using the submitted details                                    | Merchant receives secure onboarding link         |
| 3    | Merchant   | Web       | Completes missing details, uploads documents, e signs                                                     | Application ready for review                     |
| 4    | Bead       | Review    | Compliance review and decisioning                                                                         | Approval or request for more info                |
| 5    | Integrator | APIs      | After approval, provision Location then Terminal                                                          | Terminal credentials available for payment flows |

### 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

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
* Store `onboardingUrl` from the response so you can resend it if the merchant loses the email
* If you need to change the contact email later, submit an update through your standard process and resend the link

### Authentication and tokens

* Obtain an OAuth access token before calling the onboarding endpoint
* Cache tokens per account until expiry and refresh on demand
* Recommended pattern
  * Attempt the API call with the cached token
  * If you receive an unauthorized response, fetch a new token and retry once
  * 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 is complete but the merchant cannot accept payments until you:

1. Create a Location for the merchant
2. Create a Terminal for that location
3. Set the terminal webhook URL

### Operational tips

* Maintain a simple tracker for each application
  * `applicationId`, merchant legal name, primary contact, `onboardingUrl`, 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 OAuth token 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**\
Use the stored `onboardingUrl` or contact support to issue a fresh link if the prior one has expired.

**When are credentials available**\
Credentials arrive with Terminal creation as part of entity management. They are not returned by the onboarding endpoint.

### Checklist

* Payload includes business, contact, banking, and owners
* OAuth token obtained and cached
* `applicationId` and `onboardingUrl` stored
* Merchant completes documents and signing
* Location created
* Terminal created and webhook set


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.