Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 sellRates below this floor will be rejected

End to end flow

Step
Actor
Interface
What happens
Output

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.

  • 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 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). 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). 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

Last updated