Complete payments onboarding

Before Fluid can process payments for your company, it needs to know who you are. That means your legal entity, your bank account, the people who own and run the business, where you sell, and how the business operates. This is the form at Settings > Onboarding in the admin. Once you submit it, Fluid’s team reviews it and applies to payment processors for you.

Before you start

Sign in as a company admin with permission to update onboarding. Use fluid login with your own account to submit from the CLI: submitting accepts Fluid’s payments terms in your name, so it needs a person’s sign-in. With a company API token you can fill in everything, and a person submits from the admin’s onboarding form.
Seeing processor progress after you submit also needs permission to view payment accounts.
Have these documents ready as PDF or image files, up to 10 MB each:
- business registration certificate, business license, and articles of incorporation
- IRS form W-9, for a US entity
- the last three months of bank statements, and a bank letter or voided check
- a government ID for each person: a passport photo page, or both sides of a driver’s license or national ID
- proof of residence for each person
- balance sheets, income statements, and cash flow statements (or P&L) for the last two years
Install and sign in to the CLI:

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-payments
fluid login

Every fluid payments onboarding command prints JSON. Failures print a JSON error on stderr and exit with a non-zero code. Tax IDs, account and routing numbers, ID numbers, and dates of birth are masked in every output, and uploaded documents are listed by name, never by link.

Steps

See what's missing

fluid payments onboarding show

show prints the form’s status, each step with a complete flag, and a missing list of every required field that’s still empty. Each entry names the field, explains why it’s needed, and gives a fix: the exact set flags that fill it in, such as --entity 41 --set entity.website=<value>. Add --step underwriting to list one step’s gaps. fluid payments onboarding fields prints the full field schema, with types, choices, and when each field is required.

Filling in the form yourself at a terminal? Run fluid payments onboarding walk instead of the set commands below. It asks each missing question in form order and saves each answer as you go. Type < to go back, > to skip, or ? for a menu that jumps to any step, changes a saved answer, or submits. Agents and scripts use show and set.

Answer the basics

Every set changes your company’s live onboarding form, so the CLI asks for confirmation unless you pass --yes.

fluid payments onboarding set --yes \
  --set info.beneficial_individual_owner=true --set info.user_is_owner=true \
  --set info.beneficial_business_owner=false --set info.other_legal_entities=false \
  --set info.user_has_authority=true --set info.user_is_signatory=true \
  --set underwriting.company_is_mlm=true

Answer info.user_is_owner only when info.beneficial_individual_owner is true. Set underwriting.company_is_mlm to true for a direct-sales company. That turns on the compensation-plan and member questions in the underwriting step.

Add the legal entity

The first entity you add becomes the primary entity, which is the business that holds the merchant account.

fluid payments onboarding options business-types --country US
fluid payments onboarding options mcc-codes
fluid payments onboarding set --yes \
  --set entity.legal_name="Maple Wellness Inc" --set entity.classification=corporation \
  --set entity.business_identification_number=84-2219034 --set entity.registration_number=13377421 \
  --set entity.date_of_incorporation=2016-03-14 --set entity.phone="+1 801 555 0142" \
  --set entity.website=https://maplewellness.com --set entity.primary_mcc=5499 \
  --set entity.address1="220 Thanksgiving Way" --set entity.city=Lehi --set entity.province=UT \
  --set entity.postal_code=84043 --set entity.country_iso=US \
  --file entity.business_registration_certificate=./registration.pdf \
  --file entity.business_license=./license.pdf \
  --file entity.articles_of_incorporation=./articles.pdf --file entity.w_9=./w9.pdf

Take entity.classification and entity.primary_mcc from the two options lists. If the business operates through more than one entity, add each extra one with --entity new, and change one later with --entity <id>. The ids are under records.entities in show.

Add the bank account

The first bank account goes to the primary entity and becomes the primary account.

fluid payments onboarding set --yes \
  --set bank.bank_name="Zions Bank" --set bank.holder_name="Maple Wellness Inc" \
  --set bank.account_number=004417829301 --set bank.routing_number=124000054 \
  --set bank.country_iso=US --set bank.currency_iso=USD --set bank.city="Salt Lake City" \
  --file bank.last_3_months_bank_statements=./statement-jul.pdf \
  --file bank.last_3_months_bank_statements=./statement-aug.pdf \
  --file bank.last_3_months_bank_statements=./statement-sep.pdf \
  --file bank.bank_letter_or_voided_check=./voided-check.pdf

A US account needs bank.routing_number, and an account elsewhere needs bank.swift_bic. Add another account with --bank new --set bank.entity_id=<entity id>.

Add yourself and the other key people

The first person you add is the onboarding contact: you, the person filling in the form.

fluid payments onboarding set --yes \
  --set owner.full_name="Dana Whitfield" --set owner.work_email=dana@maplewellness.com \
  --set owner.date_of_birth=1984-07-22 --set owner.place_of_birth="Provo, Utah" \
  --set owner.nationality=US --set owner.country_iso=US \
  --set owner.street_address="88 Cedar Hills Dr" --set owner.city="American Fork" \
  --set owner.state=UT --set owner.postcode=84003 --set owner.phone="+1 801 555 0187" \
  --set owner.identification_number=529-41-7730 --set owner.position=CEO \
  --set owner.is_beneficial_owner=true --set owner.percent_ownership=60 \
  --file owner.government_issued_ids=./passport.jpg --id-type passport \
  --file owner.proof_of_residence=./utility-bill.pdf

Then add everyone else who owns 25% or more, manages the business, or signs for it, using --owner new:

fluid payments onboarding set --yes --owner new \
  --set owner.full_name="Marcus Chen" --set owner.is_beneficial_owner=true --set owner.percent_ownership=40 \
  --file owner.government_issued_ids=./license-front.jpg --file owner.government_issued_ids=./license-back.jpg \
  --id-type license

Each person needs the same fields as you. A driver’s license or national ID needs both sides.

Add the countries you sell in

fluid payments onboarding set --yes \
  --set country.US.currency=USD --set country.US.settlement_currency=USD \
  --set country.US.entity_legally_registered=true \
  --set country.CA.currency=CAD --set country.CA.settlement_currency=USD \
  --set country.CA.entity_legally_registered=true

A new country is routed to the primary entity. Pass country.<ISO>.entity_id to route it to another entity. fluid payments onboarding options countries lists the codes. Remove a country with fluid payments onboarding remove country CA --yes.

Answer the underwriting questions

These questions describe how the business runs. Payment processors use the answers to decide whether to accept you.

fluid payments onboarding set --yes \
  --set underwriting.company_description="Plant-based supplements sold through independent members" \
  --set underwriting.management_stability="Founders have run the company since 2016" \
  --set underwriting.uses_third_party_accounting="Yes - Tanner LLC" --set underwriting.financials_audited=true \
  --set underwriting.projected_annual_sales_volume=4800000 --set underwriting.average_order_value=86 \
  --set underwriting.cit_share_percentage=35 --set underwriting.mit_share_percentage=65 \
  --set underwriting.privacy_policy.link=https://maplewellness.com/privacy \
  --file underwriting.balance_sheet_year1=./balance-2025.pdf \
  --file underwriting.balance_sheet_year2=./balance-2024.pdf

Policies and agreements take either a URL (--set <key>.link=<url>) or a file (--file <key>=<path>). The Field reference below lists every question.

Fill in what's left

Every set prints the missing list again. Run each entry’s fix with real values until readyToSubmit is true:

fluid payments onboarding set --yes --set underwriting.bbb_rating=A+ --set underwriting.trustpilot_rating=4.6

Accept the terms and submit

Submitting accepts Fluid’s payments terms & conditions for your company and sends the form for review. It changes live data, so it needs --yes, and it needs --accept-terms to show you’ve read the terms. Run it without --accept-terms to get the terms link.

fluid payments onboarding submit --accept-terms --yes

submit refuses while any required field is missing and prints the list instead. Once it succeeds, status is submitted.With a company API token, submit changes nothing and returns status: "ready_to_submit" with a submitUrl. Open that link, the onboarding form at admin.fluid.app/settings/onboarding, as a person and submit there; everything you filled in is already on the form.

Track the review

fluid payments onboarding show

After you submit, providers lists each payment processor with its onboardingStatus. Fluid’s team moves each one forward as the processor reviews your application, which can take days or weeks. Check back occasionally, and answer any request from Fluid’s team by email.

What the status means

status is where the form stands:

`status`	What it means	What to do
`not_started`	Nothing has been filled in.	Start with the basics.
`in_progress`	Some fields are filled in.	Work through `missing` until `readyToSubmit` is `true`, then submit.
`submitted`	Every step is complete and the terms are accepted. Fluid’s team is reviewing the form.	Track the processors under `providers`.

After you submit, each entry in providers has an onboardingStatus:

`onboardingStatus`	What it means
`not_onboarding`	Fluid isn’t applying to this processor for you.
`pre_onboarding`	Fluid is preparing the application.
`underwriting`	The processor is reviewing your application.
`connecting`	You’re approved, and Fluid is connecting your merchant account.
`live`	The processor is taking payments for you.

Field reference

Keys go to --set (or --file for documents). entity.* fields go to the primary entity unless you pass --entity <id|new>. Likewise, bank.* fields go to the primary account (--bank), and owner.* fields go to you, the onboarding contact (--owner). Run fluid payments onboarding fields for the full schema.

The basics

Key	What it is	Required	Accepted values
`info.beneficial_individual_owner`	Any individual owns 25% or more	Always	`true`, `false`
`info.user_is_owner`	You’re one of those owners	When the previous answer is `true`	`true`, `false`
`info.beneficial_business_owner`	Another business owns 25% or more	Always	`true`, `false`
`info.other_legal_entities`	The business operates through more than one entity	Always	`true`, `false`
`info.user_has_authority`	You’re authorized to act for the business	Always	`true`, `false`
`info.user_is_signatory`	You’re an authorized signatory	Always	`true`, `false`
`underwriting.company_is_mlm`	Direct-sales company; turns on the member and compensation questions	Optional	`true`, `false`

Legal entity

Key	What it is	Required	Accepted values
`entity.legal_name`	Legal company name	Always	Text
`entity.classification`	Business type	Always	A value from `options business-types`
`entity.business_identification_number`	Business tax ID: EIN in the US, VAT ID in VAT countries	Always	Text (masked in output)
`entity.registration_number`	Business registration number	Always	Text
`entity.date_of_incorporation`	Date of incorporation	Always	`YYYY-MM-DD`
`entity.phone`	Business phone	Always	At least 8 digits
`entity.website`	Website	Always	URL starting `http://` or `https://`
`entity.primary_mcc`	Merchant category code	Always	A value from `options mcc-codes`
`entity.address1`, `entity.city`, `entity.province`, `entity.postal_code`	Registered address	Always	Text
`entity.country_iso`	Registered country	Always	Two-letter code, such as `US`
`entity.business_registration_certificate`	Registration certificate	Always	File
`entity.business_license`	Business license	Always	File
`entity.articles_of_incorporation`	Articles of incorporation	Always	File
`entity.w_9`	IRS form W-9	When the country is `US`	File
`entity.trading_name`, `entity.secondary_mcc`, `entity.last_3_months_processing_statements`	Trading name, second MCC, recent card processing statements	Optional	Text, MCC, files

Bank account

Key	What it is	Required	Accepted values
`bank.bank_name`	Bank name	Always	Text
`bank.holder_name`	Account holder	Always	Text
`bank.account_number`	Account number or IBAN	Always	Text (masked in output)
`bank.routing_number`	Routing number	When the country is `US`	Text (masked in output)
`bank.swift_bic`	SWIFT/BIC code	When the country isn’t `US`	Text
`bank.country_iso`	Bank country	Always	Two-letter code
`bank.currency_iso`	Account currency	Always	Three-letter code, such as `USD`
`bank.city`	Bank city	Always	Text
`bank.last_3_months_bank_statements`	Last three months of statements	Always	Files; each `--file` adds one
`bank.bank_letter_or_voided_check`	Bank letter or voided check	Always	File
`bank.entity_id`	Entity that owns the account	Optional	Entity id; defaults to the primary entity

People

Key	What it is	Required	Accepted values
`owner.full_name`	Full legal name	Always	Text
`owner.work_email`	Work email	Always	Email address
`owner.date_of_birth`	Date of birth	Always	`YYYY-MM-DD` (masked in output)
`owner.place_of_birth`	Place of birth	Always	Text
`owner.nationality`, `owner.country_iso`	Nationality and country of residence	Always	Two-letter codes
`owner.street_address`, `owner.city`, `owner.state`, `owner.postcode`	Home address	Always	Text
`owner.phone`	Phone	Always	At least 8 digits
`owner.identification_number`	Personal ID number (SSN in the US)	Always	Text (masked in output)
`owner.position`	Job title	Always	Text
`owner.government_issued_ids`	Government ID	Always	Files, with `--id-type passport`, `license`, or `national_id`; a license or national ID needs two
`owner.proof_of_residence`	Proof of residence	Always	File
`owner.is_beneficial_owner`	Owns 25% or more	Optional	`true`, `false`
`owner.percent_ownership`	Ownership share	When `owner.is_beneficial_owner` is `true`	25 to 100
`owner.is_managing_director`, `owner.is_authorized_signatory`	Roles	Optional	`true`, `false`

Countries

Key	What it is	Required	Accepted values
`country.<ISO>.currency`	Currency customers pay in	Always, for at least one country	Three-letter code
`country.<ISO>.settlement_currency`	Currency payouts settle in	Always	Three-letter code
`country.<ISO>.entity_legally_registered`	The entity is registered to sell there	Always	Must be `true`
`country.<ISO>.entity_id`	Entity that sells there	Always	Entity id; defaults to the primary entity

Underwriting

Key	What it is	Required	Accepted values
`underwriting.company_description`	What the company does	Always	Text
`underwriting.management_stability`	How long management has been in place	Always	Text
`underwriting.uses_third_party_accounting`	Uses an outside accounting firm	Always	`Yes - <firm>` or `No`
`underwriting.financials_audited`	Financial statements are audited	Always	`true`, `false`
`underwriting.balance_sheet_year1`, `underwriting.balance_sheet_year2`	Balance sheets, last two years	Always	File each
`underwriting.income_statement_year1`, `underwriting.income_statement_year2`	Income statements, last two years	Always	File each
`underwriting.cash_flow_year1`, `underwriting.cash_flow_year2`	Cash flow statements or P&L, last two years	Always	File each
`underwriting.projected_annual_sales_volume`	Projected annual sales	Always	Number
`underwriting.average_order_value`	Average order value	Always	Number
`underwriting.cit_share_percentage`, `underwriting.mit_share_percentage`	Share of sales from one-time purchases and from subscriptions	Always	0 to 100; the two must total 100
`underwriting.has_compliance_officer`, `underwriting.retains_outside_legal_counsel`	Compliance officer, outside counsel	Always	`Yes - <name>` or `No`
`underwriting.compliance_officer_responsibilities`, `underwriting.distributor_monitoring_policies`, `underwriting.suspicious_activity_escalation_process`	How compliance works, how members are monitored, how suspicious activity is escalated	Always	Text
`underwriting.investigations_description`, `underwriting.negative_media_events`	Regulatory investigations and negative press	Always	Text, or `None`
`underwriting.bbb_rating`, `underwriting.trustpilot_rating`	Review-site ratings	Always	Text, or `N/A`
`underwriting.terms_and_conditions`, `underwriting.refund_or_return_policy`, `underwriting.privacy_policy`	Your storefront policies	Always	URL (`.link`) or file
`underwriting.mlm_ownership_structure`, `underwriting.mlm_ownership_structure_file`	How the business is owned, and an ownership chart	Direct-sales companies	Text; file
`underwriting.commission_payment_method`, `underwriting.commission_payment_channels`, `underwriting.commission_payment_countries`	How, through what, and where members are paid	Direct-sales companies	Text
`underwriting.compensation_plan`	Compensation plan	Direct-sales companies	Files
`underwriting.recruiter_commission_for_recruiting`, `underwriting.all_distributors_can_profit`, `underwriting.provides_average_compensation_report`, `underwriting.distributor_cross_border_sales`	Members earn for recruiting alone; every member can profit; you publish average earnings; members may sell abroad	Direct-sales companies	`Yes - <details>` or `No - <details>`
`underwriting.distributor_identification_requirements`, `underwriting.distributor_pii_collected`, `underwriting.distributor_due_diligence`, `underwriting.distributor_country_restrictions`, `underwriting.distributor_decline_termination_reasons`, `underwriting.distributor_training_description`	How members are identified, vetted, restricted, terminated, and trained	Direct-sales companies	Text
`underwriting.income_disclosure_statement`, `underwriting.distributor_policies`, `underwriting.sample_distributor_agreement`, `underwriting.business_opportunity_disclosures`, `underwriting.fulfillment_agreement`, `underwriting.manufacturing_agreement`	Member-facing documents and supplier agreements	Direct-sales companies	URL (`.link`) or file
`underwriting.sells_health_supplements`	Sells health products or supplements; turns on the health questions	Optional	`true`, `false`
`underwriting.is_product_manufacturer`, `underwriting.marketing_methods_description`, `underwriting.cancellation_methods_description`, `underwriting.scientific_studies_description`, `underwriting.health_product_lawsuit_history`	Who makes the products, how they’re marketed, how customers cancel subscriptions, the evidence behind them, and any lawsuits	When selling health products	Text
`underwriting.contains_<ingredient>`, `underwriting.<ingredient>_product_names`	Whether a product contains kratom, ephedra, cannabis, CBD, aristolochia, or germanium, and which	When selling health products: one `contains_*` (or `underwriting.contains_none_listed`) must be `true`, and each `true` needs its product names	`true`, `false`; text
`underwriting.claims_<disease>_treatment`, `underwriting.<disease>_treatment_products`	Whether a product claims to treat cancer, impotency, Alzheimer’s, or memory loss, and which	When selling health products: one claim (or `underwriting.claims_no_diseases`) must be `true`, and each `true` needs its products	`true`, `false`; text

Troubleshooting

Pass --yes to confirm. The command changes live data and wasn’t run in an interactive terminal. Re-run it with --yes once you’ve confirmed the change.
Creating an entity needs entity.legal_name or Adding a person needs owner.full_name. A new record needs its name in the same set.
Add the legal entity first. Bank accounts, people, and countries attach to an entity. Add the entity, then retry.
Uploading a government ID needs --id-type. Pass --id-type passport, license, or national_id with the ID files.
A document is over 10 MB. Compress or split it. A multi-file document such as bank statements takes one --file per file. Pass --replace-files to replace the files already uploaded.
Someone else changed the onboarding form since it was read. Someone saved the form in the admin while your command ran. Run the command again.
submit lists missing fields. Run each entry’s fix, then submit again.
submit returns ready_to_submit with a submitUrl. You’re using a company API token. Open submitUrl and submit as a person, or run fluid login with your own account and submit again.
providers is null after you submit. Your account can’t view payment accounts. Ask a company admin who can, or check Payments in the admin.

Use the API directly

The onboarding form itself, meaning its answers, legal entities, bank accounts, people, and document uploads, has no published API reference yet. Use the CLI for those steps. The lookups and the status check are company operations, all authenticated with a Bearer token:

List business types — GET /api/business_types, the choices for entity.classification.
List MCC codes — GET /api/mcc_codes, the choices for entity.primary_mcc.
List countries — GET /api/countries.
List supported currencies — GET /api/currencies.
Get a company’s payments status — GET /api/companies/{id}/payments_status. onboarding.form_submitted is true once the form is submitted. Each processor under providers.psps and providers.apms carries its onboarding_status.

curl "https://api.fluid.app/api/companies/1187/payments_status" \
  -H "Authorization: Bearer <your_token>"

Get started

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Complete payments onboarding

Before you start

Steps

What the status means

Field reference

The basics

Legal entity

Bank account

People

Countries

Underwriting

Troubleshooting

Use the API directly

​Before you start

​Steps

​What the status means

​Field reference

​The basics

​Legal entity

​Bank account

​People

​Countries

​Underwriting

​Troubleshooting

​Use the API directly

Before you start

Steps

What the status means

Field reference

The basics

Legal entity

Bank account

People

Countries

Underwriting

Troubleshooting

Use the API directly