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

Authorizations

Header parameters

api-versionstring

Authorizationstring

Body

application/jsontext/jsonapplication/*+json

registrationEmailstring emailrequired

partnerIdstringrequired

businessobjectrequired

profileobjectrequired

representativeobjectrequired

paymentGatewayFeesobject

Responses

text/plainapplication/jsontext/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/Merchants/import' \
  --header 'Content-Type: application/json' \
  --data '{"registrationEmail":"[e-mail]","partnerId":"text","business":{"legalName":"text","mailingAddress":{"address1":"text","city":"text","region":"text","country":"text","postalCode":"text"},"website":"https://example.com"},"profile":{"ownership":"other","taxId":"text","registrationDate":"2025-02-17","description":"text","averageVolume":"text","monthlyVolume":"text"},"representative":{"firstName":"text","lastName":"text","phoneNumber":"text","address":{"address1":"text","city":"text","region":"text","country":"text","postalCode":"text"},"governmentIdIssuingCountry":"text","governmentIdType":"socialSecurityNumber","governmentIdNumber":"text"},"paymentGatewayFees":{"crypto":{},"card":{}}}'

200

401

403

200

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

OK

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

Authorizations

Header parameters

api-versionstring

Authorizationstring

Body

application/jsontext/jsonapplication/*+json

idnullable string

creatednullable string date-time

updatednullable string date-time

partnerTypeenumrequired

Options: reseller, integrator

namestringrequired

emailnullable string email

phoneNumbernullable string tel

parentIdnullable string

isEnabledbooleanrequired

paymentGatewayFeesobjectrequired

Responses

text/plainapplication/jsontext/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/Partners' \
  --header 'Content-Type: application/json' \
  --data '{"partnerType":"reseller","name":"text","isEnabled":true,"paymentGatewayFees":{"crypto":{},"card":{}}}'

200

401

403

200

{
  "id": "text",
  "created": "2025-02-17T07:48:09.682Z",
  "updated": "2025-02-17T07:48:09.682Z",
  "partnerType": "reseller",
  "name": "text",
  "email": "[e-mail]",
  "phoneNumber": "text",
  "parentId": "text",
  "isEnabled": true,
  "paymentGatewayFees": {
    "crypto": {},
    "card": {}
  }
}

OK

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)