​
Business Account Opening Flow

This guide demonstrates the complete sequence of API calls required to implement a business account opening process using the FinHub Embedded Finance API.

​
Overview

Opening a business bank account involves several steps including business verification (KYB), director verification (KYC), and account creation. The diagram below illustrates the complete flow:

​
Step 1: Create Business Profile

The first step is to create a business profile with basic company information.

curl -X POST https://api.finhub.cloud/embedded-finance/businesses \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Corporation",
    "registrationNumber": "12345678",
    "incorporationCountry": "GB",
    "businessType": "LIMITED_COMPANY",
    "registeredAddress": {
      "addressLine1": "123 Business Street",
      "city": "London",
      "postalCode": "EC1A 1BB",
      "country": "GB"
    },
    "contactEmail": "contact@acmecorp.com",
    "contactPhone": "+44123456789"
  }'

​
Step 2: Upload KYB Documents

Next, upload the necessary business verification documents.

curl -X POST https://api.finhub.cloud/embedded-finance/businesses/bus_12345abcde/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "documentType=CERTIFICATE_OF_INCORPORATION" \
  -F "file=@/path/to/certificate.pdf"

​
Step 3: Add Directors and Shareholders

Add all directors and significant shareholders to the business profile.

curl -X POST https://api.finhub.cloud/embedded-finance/businesses/bus_12345abcde/persons \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "1980-01-15",
    "email": "john.smith@acmecorp.com",
    "phone": "+44123456789",
    "roles": ["DIRECTOR", "SHAREHOLDER"],
    "shareholdingPercentage": 75,
    "nationality": "GB",
    "address": {
      "addressLine1": "456 Residential Street",
      "city": "London",
      "postalCode": "NW1 6XE",
      "country": "GB"
    }
  }'

​
Step 4: Upload KYC Documents for Each Person

For each director and significant shareholder, upload identity verification documents.

curl -X POST https://api.finhub.cloud/embedded-finance/persons/per_54321zyxwv/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "documentType=PASSPORT" \
  -F "file=@/path/to/passport.jpg"

​
Step 5: Check Verification Status

After submitting all required documents, check the verification status of the business.

curl -X GET https://api.finhub.cloud/embedded-finance/businesses/bus_12345abcde/verification \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Step 6: Create Business Account

Once verification is complete, create the business bank account.

curl -X POST https://api.finhub.cloud/embedded-finance/businesses/bus_12345abcde/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "BUSINESS_CURRENT",
    "currency": "GBP",
    "accountName": "Acme Corporation Operations"
  }'

​
Step 7: Set Up Account Access

Finally, configure access permissions for the account.

curl -X POST https://api.finhub.cloud/embedded-finance/accounts/acc_24680pqrst/access \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "per_54321zyxwv",
    "accessLevel": "FULL",
    "permissions": ["VIEW", "PAYMENT", "ADMIN"]
  }'

​
Error Handling

During the account opening process, you may encounter various errors. Here are common error scenarios and how to handle them:

Error CodeDescriptionResolution
BUSINESS_ALREADY_EXISTSA business with the same registration number already existsRetrieve the existing business profile or use a different registration number
DOCUMENT_UPLOAD_FAILEDDocument upload failed due to file size or formatEnsure the file is in an accepted format (PDF, JPG, PNG) and under 10MB
VERIFICATION_FAILEDBusiness or person verification failedCheck the specific reason in the response and request additional information or documents
PERSON_ALREADY_EXISTSA person with the same details already existsRetrieve the existing person profile or check for duplicate entries

​
Testing the Flow

You can test this entire flow in the sandbox environment without submitting real documents. Use the following test data:

  • Business Registration Number: TEST12345
  • Test Person Details: Use John Doe with date of birth 1990-01-01
  • Test Document: Use our sample test documents

​
Next Steps