Submit Application

Create a new onboarding application. On success, Bead emails the signer and returns applicationId and onboardingUrl.

Request

POST /merchant-onboarding/application Content-Type: application/json Auth: Bead OAuth access token

Body shape (top level)

• signer: email, name, position

• merchantData: business info, contacts, owners, banking, and fees

Minimal required fields (recommended starter set)

• signer.email, signer.name

• merchantData.merchantName or merchantData.registeredName

• merchantData.legalEntityType

• merchantData.federalTaxIdType, merchantData.federalTaxId

• merchantData.registrationDate (ISO 8601)

• merchantData.registeredLegalAddress{address1, city, region, country, postalCode}

• merchantData.mainPointOfContact{firstName, lastName, email, phoneNumber}

• merchantData.stakeholders[] with at least one controlling owner or parent entity

• merchantData.bankName, routingNumber, accountNumber, accountType

Fee fields and units

• transactionRate.sellRate is a percentage (example: 3.50 = 3.50%).

• perItemFee.sellRate and fixed fees are USD amounts (example: 0.49 = 49 cents).

• Use isBilledByPartner to indicate whether you bill the merchant directly.

Example request (curl)

curl -X POST "https://api.test.devs.beadpay.io/merchant-onboarding/application" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

Example request body (minimal)

{
  "signer": {
    "email": "[email protected]",
    "name": "Jane Owner",
    "position": "Owner"
  },
  "merchantData": {
    "partnerId": "PARTNER_ID",
    "partnerExternalId": "YOUR_INTERNAL_PARTNER_MID",
    "registeredName": "Sample Co LLC",
    "dbaName": "Sample Co",
    "registrationDate": "2025-08-25T00:00:00Z",
    "legalEntityType": "llc",
    "federalTaxIdType": "ein",
    "federalTaxId": "12-3456789",
    "registeredLegalAddress": {
      "address1": "123 Main St",
      "city": "Austin",
      "region": "TX",
      "country": "US",
      "postalCode": "73301"
    },
    "mainPointOfContact": {
      "firstName": "Jane",
      "lastName": "Owner",
      "email": "[email protected]",
      "phoneNumber": "[phone]"
    },
    "stakeholders": [
      {
        "firstName": "Jane",
        "lastName": "Owner",
        "ownershipPercentage": 100,
        "taxIdType": "ssn",
        "taxIdNumber": "123-45-6789",
        "address": {
          "address1": "123 Main St",
          "city": "Austin",
          "region": "TX",
          "country": "US",
          "postalCode": "73301"
        }
      }
    ],
    "bankName": "Example Bank",
    "routingNumber": "011000015",
    "accountNumber": "000111222333",
    "accountType": "checking"
  }
}

Response example

{
  "applicationId": "app_01JABCDEF1234567",
  "status": "PENDING_REVIEW",
  "onboardingUrl": "https://onboard.beadpay.io/signup/xyz123",
  "signer": { "email": "[email protected]" }
}

Notes

• The signer email is sent automatically after a successful POST.

• Keep applicationId for status checks and support tickets.

• Use partnerExternalId for your internal Partner MID reference.