# 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