Bead Developers
  • Introduction
  • Quick Start
  • Authentication
  • Payments
    • Create Payment
    • Payment Statuses
    • Payment Webhooks
    • Test Transactions - Crypto
  • Entity Management
    • Onboarding
    • Merchant Management
    • Location Management
    • Terminal Management
      • Terminal Lifecycle (Concepts)
      • Create Terminal
      • Get Terminal
      • List Terminals
      • Update Terminal
      • Delete Terminal
      • Webhook Management
      • Changelog
  • Settlement
    • Batches
    • Settlement Details
  • Reporting
    • Payment History Concepts
      • Pagination and Sorting
    • Partner Payments
    • Merchant Payments
    • Terminal Payments
    • Changelog
  • Reference Guide
Powered by GitBook
On this page
  1. Entity Management

Onboarding

API endpoints in redesign — technical specs coming soon Workflows and business logic described below are final; the exact request/response formats are being updated.

What Onboarding Will Cover

  1. Submit KYB — one JSON payload with business identity, owners/officers, banking, and contacts.

  2. Hosted Sign-Up — generate a branded URL for e-signature and document upload.

  3. Status Tracking — poll or subscribe to onboarding status (NEEDS_INFO, PENDING_REVIEW, APPROVED, REJECTED).

  4. Credential Activation — retrieve production API keys once the merchant is approved.

End-to-End Flow (unchanged)

Phase
Action
Outcome

Submit KYB

POST payload (endpoint spec coming soon)

Merchant profile created.

Generate link

Receive onboardingUrl (field name stable)

Merchant completes docs and e-signs.

Track status

GET status (endpoint spec coming soon)

Shows missing info or approval.

Fetch credentials

GET credentials (endpoint spec coming soon)

Returns live keys after approval.

Key Status Codes

Code
Meaning

NEEDS_INFO

Missing / invalid KYB data.

PENDING_REVIEW

Compliance review in progress.

APPROVED

KYB passed; credentials ready.

REJECTED

KYB failed (see reason).

Best-Practice Reminders

  • Validate required KYB fields client-side to avoid NEEDS_INFO loops.

  • Store the onboardingUrl so you can resend it.

  • Automate reminders if a merchant stays in NEEDS_INFO for 48 h.

  • After approval, provision Locations ➔ Terminals via the Entity Management APIs.

Coming Soon: API Reference

PreviousEntity ManagementNextMerchant Management

Last updated 14 days ago

A fully revised set of endpoints and JSON schemas will be published here. Want early access or to influence the design? Contact .

developers@bead.xyz