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 feesellRates below this floor will be rejected
End to end flow
1
Integrator
API
Submit KYB payload to POST /merchant-onboarding/applications with business, contact, banking, and owners
applicationId
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, 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
Terminal payments API key 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
Fee configuration priced at or above the partner's fee schedule floor — see Fee Configuration for Onboarding Applications
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 nudgeIf 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
requestIdfrom error responses for support
Handling errors and duplicates
Validation issues return a 400 with
fieldErrorsdescribing which fields failedIf 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:
Retrieve the default Location and Terminal(s) Bead created (see What boarding creates for the full mapping from
locationBusinessTypeto what gets created)Verify the terminal(s) match the expected configuration for this merchant
Reset the API key on each terminal you intend to use and store the returned
apiKey.secret(see Reset Terminal API Key). Terminal records returned by List Terminals and Get Terminal show only the masked key.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). 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
applicationIdstoredMerchant completes documents and signing
Application reached
boarded; default Location and Terminal(s) confirmedTerminal API key reset and stored for each terminal you're using
Terminal webhook set on the terminal(s) you're using
Last updated