Skip to main content
This guide provides a technical walkthrough on programmatically creating a business customer account within your Busha Business account using the Busha API. By automating customer creation, you can streamline your onboarding processes and prepare to perform transactions on behalf of your customers.
What You’ll Achieve:
  1. Understand the basic structure for creating a business customer.
  2. Learn how to structure API requests for the business customer type.
  3. Successfully create and verify business customer accounts programmatically.

​
Prerequisites

Before you begin, ensure you have:

​
Creating a Business Customer Account

1

Understand Customer Creation Parameters

The essential parameters for creating a business customer are:
ParameterTypeExample ValueDescription
emailstringbusiness​@​gmail.comThe primary email address for the business contact.
has_accepted_termsbooleantrueIndicates if the terms and conditions have been accepted.
typestringbusinessThe type of customer being created.
country_idstringNGThe ISO 3166-1 alpha-2 country code of the business’s operation.
phonestring+234 8012345678The business’s primary contact phone number, including country code.
birth_datestring01-01-2015The incorporation date or a key date associated with the business.
addressobjectSee details belowThe business’s physical address details.
business_namestringABC CorporationThe legal registered name of the business.
business_industrystringBIN_C4UvTYR5V8jsOx5LmwQA unique identifier representing the business’s industry.
business_incorporation_datestring2015-06-15The date on which the business was officially incorporated.
For business_industry, the list of supported sectors and their unique identifier can be retrieved from Supported Business Industries.Address Object:The address field requires:
"address": {
  "country_id": "NG",
  "address_line_1": "123 Business Avenue",
  "city": "Lagos",
  "state": "Lagos"
}
Know Your Business (KYB)For full verification, business customers require additional sections:
  1. Documents - Business registration documents
  2. Business Owners - Information about directors and beneficial owners
  3. Business Transaction - Expected transaction patterns
  4. Business Registration - Legal and regulatory information
Files uploaded for KYB must be in Base64 format and have a file size less than 4MB.
Business Owners:
"business_owners": [
  {
    "first_name": "John",
    "last_name": "Doe",
    "role": ["director"],
    "percentage_ownership": 100,
    "is_pep": false,
    "nationality": "NG",
    "bvn": "12345678901"
  }
]
Business Transaction:
"business_transaction": {
  "purpose": "international trade",
  "monthly_transaction_value": "above_1m_usd",
  "monthly_transaction_count": "100_to_200",
  "client_transaction_status": "self-owned",
  "api_access_needed": true,
  "api_integration_url": "https://yourbusiness.com"
}
Business Registration:
"business_registration": {
  "business_type": "type_registered_company",
  "business_structure": "limited_liability_company",
  "business_regulation_status": "regulated",
  "registration_number": "RC1234567",
  "tax_identification_number": "TIN1234567",
  "corporate_group_status": "standalone_company",
  "exchange_listing_status": "not_listed_on_exchange",
  "license_number": "LIC123456"
}
Documents:
"documents": [
  {
    "purposes": ["certificate_of_incorporation"],
    "file": "{{base64 string}}"
  }
]
For a full list of acceptable documents, please refer to the Compliance Guide.
2

Create a Business Customer (Without KYB)

Business customers represent legal entities that utilize your offerings. Start with basic information and add KYB details later.To create a business customer without KYB documents:
  1. Open your terminal or command prompt.
  2. Use the POST request below to the /v1/customers endpoint.
  3. Replace YOUR_BASE_URL with your chosen environment’s URL and {YOUR_SECRET_KEY} with your actual key.
    $ curl -i -X POST https://YOUR_BASE_URL/v1/customers \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "[email protected]",
        "has_accepted_terms": true,
        "type": "business",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "birth_date": "01-01-2015",
        "address": {
          "country_id": "NG",
          "address_line_1": "123 Business Avenue",
          "city": "Lagos",
          "state": "Lagos"
        },
        "business_name": "Basic Corp",
        "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
        "business_incorporation_date": "2015-06-15"
      }'
Expected Response:A successful response will return a Customer object with status: "inactive" until KYB is completed.
    {
      "status": "success",
      "message": "Created customer successfully",
      "data": {
        "address": {
          "address_line_1": "123 Business Avenue",
          "city": "Lagos",
          "country_id": "NG",
          "state": "Lagos"
        },
        "business_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
        "business_incorporation_date": "2015-06-15",
        "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
        "business_name": "Basic Corp",
        "country_id": "NG",
        "created_at": "2026-01-27T13:00:16.152775472Z",
        "deposit": true,
        "display_currency": "NGN",
        "email": "[email protected]",
        "has_accepted_terms_of_service": true,
        "id": "CUS_B912WgfXH0I4U",
        "level": "0",
        "payout": true,
        "phone": "+234 8012345678",
        "status": "inactive",
        "type": "business",
        "updated_at": "2026-01-27T13:00:16.152775472Z"
      }
    }
The default status of a customer is inactive until they complete their Know-Your-Business (KYB) process.
3

Create a Business Customer (With Complete KYB)

Create a fully verified business customer by including all required KYB sections at creation.To create a business customer with complete KYB:
  1. Open your terminal or command prompt.
  2. Use the POST request below to the /v1/customers endpoint.
  3. Replace YOUR_BASE_URL with your chosen environment’s URL and {YOUR_SECRET_KEY} with your actual key.
    $ curl -i -X POST https://YOUR_BASE_URL/v1/customers \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
      -H 'Content-Type: application/json' \
      -d '{
        "email": "[email protected]",
        "has_accepted_terms": true,
        "type": "business",
        "country_id": "NG",
        "phone": "+234 8012345678",
        "birth_date": "01-01-2015",
        "address": {
          "country_id": "NG",
          "address_line_1": "123 Business Avenue",
          "city": "Lagos",
          "state": "Lagos"
        },
        "business_name": "ABC Corporation",
        "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
        "business_incorporation_date": "2015-06-15",
        "documents": [
          {
            "purposes": ["certificate_of_incorporation"],
            "file": "{{base64 encoded certificate}}"
          }
        ],
        "business_owners": [
          {
            "first_name": "Abdulazeez",
            "last_name": "Abdulazeez",
            "role": ["director"],
            "percentage_ownership": 100,
            "is_pep": false,
            "nationality": "NG",
            "bvn": "12345678901"
          }
        ],
        "business_transaction": {
          "purpose": "international trade",
          "monthly_transaction_value": "above_1m_usd",
          "monthly_transaction_count": "100_to_200",
          "client_transaction_status": "self-owned",
          "api_access_needed": true,
          "api_integration_url": "https://abccorp.com"
        },
        "business_registration": {
          "business_type": "type_registered_company",
          "business_structure": "limited_liability_company",
          "business_regulation_status": "regulated",
          "registration_number": "RC8828228",
          "tax_identification_number": "2277711991",
          "corporate_group_status": "standalone_company",
          "exchange_listing_status": "not_listed_on_exchange",
          "license_number": "8383838"
        }
      }'
Expected Response:
    {
      "status": "success",
      "message": "Created customer successfully",
      "data": {
        "address": {
          "address_line_1": "123 Business Avenue",
          "city": "Lagos",
          "country_id": "NG",
          "state": "Lagos"
        },
        "business_id": "BUS_CQr0jPzGGzmn1uW5W7OVs",
        "business_incorporation_date": "2015-06-15",
        "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
        "business_name": "ABC Corporation",
        "country_id": "NG",
        "created_at": "2026-01-27T13:00:16.152775472Z",
        "deposit": true,
        "display_currency": "NGN",
        "email": "[email protected]",
        "has_accepted_terms_of_service": true,
        "id": "CUS_BstLqfzSrdQEd",
        "level": "0",
        "payout": true,
        "phone": "+234 8012345678",
        "status": "inactive",
        "type": "business",
        "updated_at": "2026-01-27T13:00:16.152775472Z"
      }
    }
4

Verify the Business Customer

After creating a customer with complete KYB information, verify them to activate their account.To verify a business customer:
  1. Open your terminal or command prompt.
  2. Use the POST request below to the /v1/customers/{customer_id}/verify endpoint.
  3. Replace {customer_id} with the customer ID from the previous response.
  4. Replace YOUR_BASE_URL with your chosen environment’s URL and {YOUR_SECRET_KEY} with your actual key.
    $ curl -i -X POST https://YOUR_BASE_URL/v1/customers/CUS_BstLqfzSrdQEd/verify \
      -H 'Authorization: Bearer {YOUR_SECRET_KEY}'
Expected Response:A successful verification will return:
    {
      "status": "success",
      "message": "Customer verified successfully"
    }
After verification, check the customer status by retrieving their details. The status will change from inactive to in_review or active.
Common Errors:
  • missing_section (Owners): Business owners section is incomplete
  • missing_section (Transaction): Transaction information is missing
  • missing_documents: Required KYB documents are not uploaded
If you receive a missing_section error, update the customer with the required information using the PUT /v1/customers/{customer_id} endpoint, then retry verification.

​
Complete Example: Create and Verify Business Customer

Here’s a complete workflow to create and verify a business customer in one go: Step 1: Create customer with complete KYB 
curl -X POST https://api.sandbox.busha.so/v1/customers \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "has_accepted_terms": true,
    "type": "business",
    "country_id": "NG",
    "phone": "+234 8012345678",
    "birth_date": "01-01-2015",
    "address": {
      "country_id": "NG",
      "address_line_1": "456 Corporate Plaza",
      "city": "Lagos",
      "state": "Lagos"
    },
    "business_name": "Verified Corp Ltd",
    "business_industry": "BIN_C4UvTYR5V8jsOx5LmwQ",
    "business_incorporation_date": "2015-06-15",
    "documents": [
      {
        "purposes": ["certificate_of_incorporation"],
        "file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      }
    ],
    "business_owners": [
      {
        "first_name": "Jane",
        "last_name": "Director",
        "role": ["director"],
        "percentage_ownership": 100,
        "is_pep": false,
        "nationality": "NG",
        "bvn": "12345678901"
      }
    ],
    "business_transaction": {
      "purpose": "e-commerce",
      "monthly_transaction_value": "above_1m_usd",
      "monthly_transaction_count": "100_to_200",
      "client_transaction_status": "self-owned",
      "api_access_needed": true,
      "api_integration_url": "https://verifiedcorp.com"
    },
    "business_registration": {
      "business_type": "type_registered_company",
      "business_structure": "limited_liability_company",
      "business_regulation_status": "regulated",
      "registration_number": "RC9999999",
      "tax_identification_number": "TIN9999999",
      "corporate_group_status": "standalone_company",
      "exchange_listing_status": "not_listed_on_exchange",
      "license_number": "LIC999999"
    }
  }'
Step 2: Verify the customer 
curl -X POST https://api.sandbox.busha.so/v1/customers/CUS_xxx/verify \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Step 3: Check customer status 
curl -X GET https://api.sandbox.busha.so/v1/customers/CUS_xxx \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'
Expected status: "status": "in_review" or "status": "active"

​
Troubleshooting

  • 400 Bad Request / 422 Unprocessable Entity: Review your request body to ensure all required fields are present and correctly formatted for the specified type (individual or business).
  • 401 Unauthorized: Verify that your Secret API Key is correct and included in the header.
  • Email validation error: Use real email domains like @gmail.com instead of generic domains like @example.com.
  • missing_section errors during verification: Ensure all required sections (owners, transaction, registration) are included before calling verify.

​
What’s Next?

Now that you can programmatically create and verify business customers, you can proceed to manage them and perform transactions on their behalf: