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