Onboarding

The Merchant Onboarding API allows integrators to programmatically submit merchant details to initiate Know Your Business (KYB). Once an application is submitted, Bead automatically emails the merchant contact with a secure link where they can complete missing details, upload documents, and sign electronically.

This is the starting point for merchant setup. After approval, provision Locations and Terminals using the Entity Management APIs.

End-to-End Flow

Phase	Action	Outcome
Submit KYB	POST /merchant-onboarding/application with required merchant payload	Merchant profile created; email invitation sent.
Merchant self-serve	Merchant receives onboarding email and completes application online	Merchant provides docs and signs digitally.
Next steps	Use Location and Terminal APIs once merchant is approved	Locations and terminals provisioned.

Submit KYB

Endpoint

POST https://api.test.devs.beadpay.io/merchant-onboarding/application

Description Creates a new merchant onboarding application. The payload must include:

• Business identity (legal name, DBA, tax ID, address)

• At least one merchant contact with a valid name and email

• Bank account information (for settlement)

• Owner/officer information (for compliance)

When received, Bead automatically emails the designated contact with a unique onboarding link.

Required Fields

Section	Fields
business	legalName, taxId, address.line1, address.city, address.state, address.postalCode, address.country
contacts	At least one entry with firstName, lastName, and email
bankAccount	routingNumber, accountNumber, accountType
owners	At least one entry with firstName, lastName, and ownershipPercent

Request Example

{
  "business": {
    "legalName": "Example Business LLC",
    "dbaName": "Example Store",
    "taxId": "12-3456789",
    "address": {
      "line1": "456 Market Street",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "country": "US"
    }
  },
  "contacts": [
    {
      "type": "PRIMARY",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "5551234567"
    }
  ],
  "bankAccount": {
    "routingNumber": "111000025",
    "accountNumber": "000123456789",
    "accountType": "CHECKING"
  },
  "owners": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "ownershipPercent": 100
    }
  ]
}

Response Example

{
  "applicationId": "app_123456789",
  "status": "PENDING_REVIEW",
  "onboardingUrl": "https://onboard.beadpay.io/signup/xyz123"
}

• applicationId — unique identifier for the onboarding application

• status — initial state after submission (commonly PENDING_REVIEW)

• onboardingUrl — unique link sent to the merchant contact by email; may also be stored/resurfaced by the integrator

Error Handling

The API returns standard HTTP status codes. Common cases include:

400 Bad Request — missing or invalid fields

{
  "error": "InvalidRequest",
  "message": "business.legalName is required"
}

409 Conflict — duplicate application detected

{
  "error": "Conflict",
  "message": "An application already exists for this taxId"
}

500 Internal Server Error — unexpected system error

{
  "error": "ServerError",
  "message": "An unexpected error occurred. Please try again later."
}

Integrators should validate required fields client-side where possible, and gracefully handle 409 responses by reusing the existing application rather than resubmitting.

Best Practices

• Always include a valid merchant contact name and email. This triggers the onboarding email automatically.

• Store the onboardingUrl. You can resend it to the merchant if they lose the email.

• Validate fields client-side. Helps reduce unnecessary resubmissions.

• Automate reminders. If a merchant does not complete their onboarding within your SLA, resend the link or notify them.

• After approval, continue with Locations and Terminals. Credentials and settlement configuration come when terminals are provisioned.