Onboard Merchant/Partner

Before importing a merchant, you must first authenticate.

Import Merchant

Step 1: Create Merchant Account

Initiate the creation of a new merchant account using this API endpoint:

Example request body:

{
  "registrationEmail": "user@beadpay.io",
  "partnerId": "04f991bc3b1a0028df42c25e",
  "business": {
    "legalName": "Serious Business Inc.",
    "dbaName": "Srs Bsns",
    "mailingAddress": {
      "address1": "123 Street Ave",
      "address2": "Unit 123",
      "city": "Los Angeles",
      "region": "CA",
      "country": "US",
      "postalCode": "90210"
    },
    "phoneNumber": "0123456789",
    "website": "https://example.com"
  },
  "profile": {
    "ownership": "other",
    "taxId": "3x4mple123",
    "registrationDate": "2024-06-27",
    "description": "Goods and services of serious nature",
    "averageVolume": "100",
    "monthlyVolume": "1000"
  },
  "representative": {
    "firstName": "Hingle",
    "lastName": "McCringleberry",
    "phoneNumber": "0123456789",
    "address": {
      "address1": "123 Street Ave",
      "address2": "Unit 123",
      "city": "Los Angeles",
      "region": "CA",
      "country": "US",
      "postalCode": "90210"
    },
    "governmentIdIssuingCountry": "US",
    "governmentIdType": "socialSecurityNumber",
    "governmentIdNumber": "123456789",
    "governmentIdIssueDate": "2023-06-27",
    "governmentIdExpiryDate": "2024-06-27"
  },
  "paymentGatewayFees": {
    "crypto": {
      "feeFactor": 0.01,
      "fixedFee": 1
    },
    "card": {
      "feeFactor": 0.01,
      "fixedFee": 0
    }
  }
}

Example response:

{
  "merchantId": "66598ac3a95359338d272c64",
  "username": "",
  "password": "",
  "onboardingPageUrl": "https://hosted-onboarding-app-4.vercel.app/66598ac5a95359338d272c65/onboarding-kyc"
}

The response contains:

  • merchantId Unique identifier for the merchant account

  • username The username required for merchants to access the Bead Portal

  • password The password required for merchants to access the Bead Portal

  • onboardingPageUrl : A unique page created for the merchant to complete their onboarding process.

Note: username and password currently return no values, to be updated in a future version.

Step 2: Merchant Completes Bead Onboarding

After receiving the response, redirect the user to the onboardingPageUrl where the merchant will be guided to complete their Bead onboarding process:

  1. Accept Terms of Use and Privacy agreements

  2. Complete their business registration (KYB)

  3. Complete KYC for all owners with 25%+ ownership

  4. Upon KYB/KYC approval, merchant receives email to connect their bank account

    • Access page from email link

    • Enter bank account info

Upon successful bank account connection, the merchant account is onboarded and ready to accept Bead payments.

If redirection to the onboardingPageUrl is not possible, you can send the merchant their onboarding link. If the KYB process is not completed within 1 hour, Bead will email the merchant at the email provided in the request body.

Step 3: Create Terminal for Merchant

Once the merchant account is fully onboarded, the next step is to create a Terminal from which payments can be initiated.

Create Partner

Before creating a partner, you must first authenticate.

Initiate the creation of a new partner account using this API endpoint:

Example request body:

{
  "partnerType": "reseller",
  "name": "Howdy Partner",
  "email": "user@example.com",
  "phoneNumber": "0123456789",
  "parentId": "04f991bc3b1a0028df42c25e",
  "isEnabled": true,
  "paymentGatewayFees": {
    "crypto": {
      "feeFactor": 0.01,
      "fixedFee": 1
    },
    "card": {
      "feeFactor": 0.01,
      "fixedFee": 0
    }
  }
}

Example response:

{
  "id": "string",
  "created": "2024-07-03T14:24:26.719Z",
  "updated": "2024-07-03T14:24:26.719Z",
  "partnerType": "reseller",
  "name": "Howdy Partner",
  "email": "user@example.com",
  "phoneNumber": "0123456789",
  "parentId": "04f991bc3b1a0028df42c25e",
  "isEnabled": true,
  "paymentGatewayFees": {
    "crypto": {
      "feeFactor": 0.01,
      "fixedFee": 1
    },
    "card": {
      "feeFactor": 0.01,
      "fixedFee": 0
    }
  }
}

The response contains:

  • id Unique identifier for the partner account

  • partnerType

    • reseller

    • integrator

  • paymentGatewayFees

    • feeFactor The total fee percentage added to transactions (Example: if the partner's total percentage-based transaction fee is 2%, feeFactor is represented as 0.02)

    • fixedFee The total fixed fee added to transactions (Example: if the partner's total fixed transaction fee is $0.10, fixedFee is represented as 0.10)

Last updated