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:

POST/Merchants/import

Authorization

oauth2

Header parameters

Body

application/jsontext/jsonapplication/*+json

registrationEmail*string (email)

partnerId*string

business*MerchantBusiness (object)

profile*MerchantProfile (object)

representative*MerchantRepresentative (object)

paymentGatewayFeesPaymentGatewayFees (object)

Response

200401403

OK

Body

text/plainapplication/jsontext/json

merchantIdnullable string

usernamenullable string

passwordnullable string

onboardingPageUrlnullable string

Request

JavaScriptCurlPython

const response = await fetch('/Merchants/import', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "business": {
        "legalName": "text",
        "mailingAddress": {
          "address1": "text",
          "city": "text",
          "country": "text",
          "postalCode": "text",
          "region": "text"
        },
        "website": "https://example.com"
      },
      "partnerId": "text",
      "profile": {
        "averageVolume": "text",
        "description": "text",
        "monthlyVolume": "text",
        "ownership": "other",
        "registrationDate": "2024-12-21",
        "taxId": "text"
      },
      "registrationEmail": "[e-mail]",
      "representative": {
        "firstName": "text",
        "governmentIdIssuingCountry": "text",
        "governmentIdNumber": "text",
        "governmentIdType": "socialSecurityNumber",
        "lastName": "text",
        "phoneNumber": "text"
      }
    }),
});
const data = await response.json();

Response

200

{
  "merchantId": "text",
  "username": "text",
  "password": "text",
  "onboardingPageUrl": "text"
}

Example request body:

{
  "registrationEmail": "[e-mail]",
  "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:

POST/Partners

Authorization

oauth2

Header parameters

Body

application/jsontext/jsonapplication/*+json

idnullable string

creatednullable string (date-time)

updatednullable string (date-time)

partnerType*PartnerType (enum)

resellerintegrator

name*string

emailnullable string (email)

phoneNumbernullable string (tel)

parentIdnullable string

isEnabled*boolean

paymentGatewayFees*PaymentGatewayFees (object)

Response

200401403

OK

Body

text/plainapplication/jsontext/json

idnullable string

creatednullable string (date-time)

updatednullable string (date-time)

partnerType*PartnerType (enum)

resellerintegrator

name*string

emailnullable string (email)

phoneNumbernullable string (tel)

parentIdnullable string

isEnabled*boolean

paymentGatewayFees*PaymentGatewayFees (object)

Request

JavaScriptCurlPython

const response = await fetch('/Partners', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "isEnabled": false,
      "name": "text",
      "partnerType": "reseller",
      "paymentGatewayFees": {}
    }),
});
const data = await response.json();

Response

200

{
  "id": "text",
  "created": "2024-12-21T13:21:54.751Z",
  "updated": "2024-12-21T13:21:54.751Z",
  "partnerType": "reseller",
  "name": "text",
  "email": "[e-mail]",
  "phoneNumber": "text",
  "parentId": "text",
  "isEnabled": false,
  "paymentGatewayFees": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": {
      "feeFactor": 0,
      "fixedFee": 0
    }
  }
}

Example request body:

{
  "partnerType": "reseller",
  "name": "Howdy Partner",
  "email": "[e-mail]",
  "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": "[e-mail]",
  "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)