Onboard & Verify a Business

This Quickstart is Onboard & Connect a Customer for businesses. You’ll:

configure an application that can only ever land on a business account;
walk an owner through the OAuth grant;
register their legal entity and beneficial ownership roster;
track the KYB case to a decision;
prove the connection by issuing a card on the business account.

The person in front of you is always an individual first. They sign in as themselves, get identity-verified as themselves, and then register a business. The business is a new account next to their personal one, not a conversion of it. Everything below follows that order. See How accounts work.

Prerequisites

A staging login and an application created from Templates → OAuth Integration. See Prepare your accounts.
The application moved to ACTIVE by Fluz, with VERIFY_KYC enabled. Without this, calls fail with AUTH-0030 … current status: PERSONAL.
A client_id, client_secret, and registered redirect_uri. See Configure OAuth App.
Requests go to the sandbox: no real money, no real PII. See Staging vs. Live Environment.

The full flow

Configure the application for businesses

Two permission lists live on the Permissions tab of your app, and they’re edited independently.

List	What to put on it
Permissions	What your app may do on a personal account. Include the permission to register a business. It’s granted by the personal account, so it belongs here and nowhere else.
Business permissions	What your app may do on a business account once one exists.

A non-empty Business permissions list is what makes your app business-enabled. If you leave it empty, users are never offered the option to apply for a business account, whatever else you configure.While you’re in the app editor, register your redirect_uri on the OAuth tab. Also add a webhook URL subscribed to KYB status update; that’s how you’ll learn the review has finished without polling.

The consent screen is built from these lists, not from your authorize URL. A permission you don’t select here is never offered to the user and can never appear on a token. Full detail: Business Accounts in OAuth.

Ask Fluz to activate the app and restrict it to business accounts

Send your application name or ID to your Fluz account manager and ask for two things:

activation (ACTIVE status), required before the app can act for anyone but you;
a business-accounts-only restriction, so the flow never settles on a personal account.

With the restriction in place, a user who has no business account skips the account picker and goes straight into business registration.

Neither is self-serve. Until the restriction is applied, users with no business account are offered their personal account alongside the option to apply for a business one, and some of them will pick the personal account.

Skip the restriction if your app legitimately serves both consumers and businesses. Asking for it says that a personal-account grant is always a bug for you.

Send the owner through the OAuth grant

Build the authorize URL:

Authorization URL

https://uni.staging.fluzapp.com/authorize
  ?response_type=code
  &client_id=<YOUR_OAUTH_CLIENT_ID>
  &redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>
  &state=<UNGUESSABLE_VALUE_YOU_STORED>
  &external_id=<YOUR_ID_FOR_THIS_ACCOUNT>

With the app restricted to business accounts, a first-time user sees sign-in and 2FA, then a consent screen with two groups: the consumer permissions they’re granting now, and the business permissions being pre-approved for the business they’re about to create. The list is read-only; they accept all of it or they don’t finish.They’re redirected back to your redirect_uri with ?code=...&state=.... Validate state, then capture the single-use code server-side.

Give the business its own external_id, derived from your own business record, not from the owning user. An external ID binds to one Fluz account on first use, so an ID you’ve spent on someone’s personal account can’t be reused for their business.

Full parameter reference: Client-Facing OAuth Grant Flow.

Exchange the code for the applicant's token

This is the same exchange as any other grant. Use Basic auth with the base64 of client_id:client_secret:

Exchange (cURL)

curl -X GET "https://uni.staging.fluzapp.com/token/exchange?code=<AUTH_CODE>&redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>" \
  -H "Authorization: Basic <base64 of CLIENT_ID:CLIENT_SECRET>"

The redirect_uri must match the one you used at /authorize exactly, byte for byte.

The business doesn’t exist yet, so this token belongs to the applicant’s personal account. Its account type is CONSUMER. That’s correct, and it’s the token that getBusinessCategories and registerBusiness require. Read the account off the exchange response and persist it, rather than inferring it from your own records of who started the flow.

Verify the applicant's identity (KYC)

KYB verifies the business and the other owners. It doesn’t verify the applicant, so the applicant has to be verified before you register anything. Otherwise registration fails with ARG-0001.Call verifyUserInformation with the applicant’s token. In staging, this test identity returns APPROVED the first time it’s used. Reusing it for another user returns DUPLICATE, which doesn’t count as verified. See Test KYC Flows.

mutation VerifyUserInformation(
  $firstName: String!
  $lastName: String!
  $streetLine1: String!
  $city: String!
  $state: String!
  $postalCode: String!
  $country: String!
  $dateOfBirth: String!
  $ssnLast4: String!
) {
  verifyUserInformation(
    firstName: $firstName
    lastName: $lastName
    streetLine1: $streetLine1
    city: $city
    state: $state
    postalCode: $postalCode
    country: $country
    dateOfBirth: $dateOfBirth
    ssnLast4: $ssnLast4
  ) {
    status
    message
  }
}

{
  "firstName": "John",
  "lastName": "Smith",
  "streetLine1": "222333 Peachtree Place",
  "city": "Atlanta",
  "state": "GA",
  "postalCode": "30318",
  "country": "United States",
  "dateOfBirth": "02/28/1975",
  "ssnLast4": "3333"
}

Which check the applicant needs depends on the isUsPerson value you’ll send for them in the next step. true requires a successful SSN (CIP) verification on file; false requires a successful document verification. See User KYC Verification.

A user can be submitted at most 3 times before returning ERROR. Don’t use up attempts on the user you’re about to make an applicant. ERROR with User is already KYC verified means they’re already done.

First, still using the applicant’s CONSUMER token, resolve the category the entity trades under. Never hardcode these UUIDs:

query {
  getBusinessCategories {
    id
    name
    subCategories { id name }
  }
}

Then submit the entity and the full ownership roster in one call, with the same CONSUMER token. In staging, use taxId: "11-1111111" for an auto-approval (see KYB Testing):

mutation RegisterBusiness($input: RegisterBusinessInput!) {
  registerBusiness(input: $input) {
    accountId
    kybStatus
    success
    error { code message }
  }
}

{
  "input": {
    "businessName": "Acme Corporation",
    "dbaName": "Acme Co",
    "businessStructure": "LLC",
    "businessLegalAddress": {
      "streetAddressLine1": "123 Main Street",
      "city": "San Francisco",
      "state": "California",
      "postalCode": "94102",
      "country": "United States"
    },
    "stateOfIncorporation": "California",
    "taxId": "11-1111111",
    "businessCategoryId": "<FROM_getBusinessCategories>",
    "businessSubCategoryId": "<FROM_getBusinessCategories>",
    "natureOfBusiness": "E-commerce retail",
    "businessAccountUsage": ["CORPORATE_SPENDING_ADMIN"],
    "externalReferenceId": "your-business-id-123",
    "confirm": {
      "allOwnersWith25PercentageOwnershipListed": true,
      "noOwnersMoreThan25Percentage": false
    },
    "owners": [
      {
        "firstName": "John",
        "lastName": "Smith",
        "emailAddress": "john@example.com",
        "phoneNumber": "+14155551234",
        "title": "Chief Executive Officer",
        "ownershipPercentage": 100,
        "isControlPerson": true,
        "isInvited": false,
        "isUsPerson": true
      }
    ]
  }
}

A success response returns an accountId and a kybStatus of SUBMITTED. Store the accountId immediately: it’s your only handle on the application, and you’ll mint the business token with it.These three things reject most first attempts:

isUsPerson is required on every owner, including the applicant and invited owners. It’s the single most common cause of a rejected roster.
Exactly one owner must be the applicant, matched by email or phone against the token’s user. Exactly one must be the control person.
The legal address is checked against an address-validation provider. Invented streets fail with BS-0002; use Test Addresses.

Errors come back inside the response payload, not as GraphQL errors. Branch on success and the error object. Full parameter and error reference: Register a Business.

Get the remaining owners verified, then wait

SUBMITTED means the payload validated and a case opened. It doesn’t mean approved.Mint a BUSINESS token: generateUserAccessToken with the applicant’s userId and the new business accountId. Then read the roster:

query GetBusiness {
  getBusiness {
    accountId
    kybStatus
    owners { id name verificationType status }
  }
}

How each owner verifies depends on their verificationType:

SSN — the owner runs verifyUserInformation with a token for their own user. The business token can’t do it for them.
DOCUMENTS — get a link from requestOwnerDocumentVerificationLink and send it to them. This call returns ARG-0001 for SSN owners.
isInvited: true — Fluz emails the owner, who verifies themselves.

Keep going until kybStatus is final and every owner reports READY.The status moves from PENDING to APPROVED or DECLINED, usually within one to two business days. Take the decision off the KYB status update webhook you configured in Step 1, and use getBusiness for reconciliation: hourly, not per page load.

Show the user an honest “under review” state. Don’t drop them into a business dashboard that can’t transact yet, and don’t auto-retry a decline: a second submission is blocked by BS-0007. Full lifecycle: Register & Verify Businesses.

Fund the business and prove it

A new business account has a zero balance. Fund a spend account first; see Funding a staging wallet.Once kybStatus is APPROVED and funds are in place, run any Fluz operation with the BUSINESS token and it executes against the business. There’s no separate business API.

mutation {
  createVirtualCard(
    input: {
      idempotencyKey: "9f2c4d61-77aa-4b0e-8f2a-1c9d3e5b7a04"
      offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
      spendLimit: 250.00
      lockCardNextUse: true
      cardNickname: "First card on a verified business"
    }
  ) {
    virtualCardId
    virtualCardLast4
    status
  }
}

An ACTIVE card back means the loop is closed: configured, authorized, verified, registered, approved, operating. To read the card’s status and limit later, see Card status, locks & limits.

You’re done 🎉

You’ve taken a business from an empty application to a verified account that can spend. From here:

Business accounts in OAuth

The two permission lists, the account picker, and which account a code resolves to.

Register & verify businesses

Prerequisites, the KYB status lifecycle, and tracking a case to a decision.

Submit business documents

Authorized-signer uploads and responding to documentation requests.

Onboard & connect a customer

The same journey for individuals.

Want to learn more? Contact us at support@fluz.app to speak with our experts or request a demo.

Get started

Fluz Dashboard

Quickstarts

Onboard & Verify a Business

The full flow

You’re done 🎉

Business accounts in OAuth

Register & verify businesses

Submit business documents

Onboard & connect a customer

​The full flow

​You’re done 🎉

Business accounts in OAuth

Register & verify businesses

Submit business documents

Onboard & connect a customer

The full flow

You’re done 🎉