# Account setup & onboarding

Before you can accept live payments you must complete three sequential phases: **sign-up** (a short REST wizard that ends with a Demo account), optionally **additional company entities** (added in the Fynex dashboard), and **KYB** (identity verification via our KYB provider). At the end of KYB approval your account's `operationalMode` flips from `Demo` to `Live`.

> [!NOTE]
> Sign-up and KYB are REST calls to `https://api.fynex.ai` that use no auth header; they rely on an HttpOnly session cookie. Adding further company entities is done in the Fynex dashboard.

---

## Overview

```flow
title: Onboarding phases
caption: Three sequential phases; Phase 2 is optional.
node start 0 0 | Start sign-up | POST /onboarding/start | Phase 1 · REST | end
node steps 0 1 | Wizard steps ×N | PATCH /onboarding/step
node verify 0 2 | Verify email | POST /verify-email
node complete 0 3 | Complete sign-up | POST /onboarding/complete | Demo seller | ok
node ent 1 0 | Add company entities | In the Fynex dashboard | Phase 2 · Dashboard | ok
node kyb 2 0 | Initiate KYB | POST /api/v1/kyb/initiate | Phase 3 · REST+KYB
node sdk 2 1 | KYB Web SDK | Customer fills the form
node review 2 2 | Fynex staff review | Review and approve | | warn
node live 2 3 | operationalMode → Live | | | end ok
edge start steps | cookie set
edge steps verify
edge verify complete
edge kyb sdk | KYB token
edge sdk review
edge review live | approved
```

`POST /onboarding/complete` creates the organization, legal entity, organization profile and a
Demo seller account, and provisions the sandbox.

---

## Phase 1 — Sign-up (draft → verified → complete)

Sign-up is a short, resumable wizard over REST. Four calls, all on
`https://api.fynex.ai`, all cookie-authenticated after the first:

| # | Call | What it does |
|---|------|--------------|
| 1 | `POST /api/v1/onboarding/start` | Creates a **draft** user from `email` + `password`, sets the HttpOnly `dashboard_session` cookie, and e-mails a verification code. No auth header. |
| 2 | `PATCH /api/v1/onboarding/step` | Saves one wizard step: `{ "step": "<name>", "data": { … } }`. Steps must be submitted in order; a step may be re-submitted to edit it. |
| 3 | `POST /api/v1/verify-email` | Consumes the e-mailed code: `{ "code": "123456" }`. `POST /api/v1/verify-email/resend` sends a fresh one. |
| 4 | `POST /api/v1/onboarding/complete` | Turns the draft into a real account: organization, legal entity, organization profile and a **Demo** seller account, pre-provisioned as a sandbox. Refused with `403 emailNotVerified` until step 3 is done. |

> [!NOTE]
> `start` already sets the session cookie — there is no separate sign-in step
> during sign-up. `POST /api/v1/login/dashboard` is for **returning** sessions.

### Step names and what each collects

The step sequence depends on `legalEntityType`, chosen in the first step:

```flow
node type 0 0.5 | legal_entity_type | Company or Individual | | end
node personal 1 0.5 | personal_details
node company 2 0 | company_details
node business 3 0 | business_details | | | end ok
node individual 2.5 1 | individual_details | | | end ok
edge type personal
edge personal company | Company
edge company business
edge personal individual | Individual
```

The last step of each track (`business_details`, `individual_details`) is where
`complete` is called from; KYB is not part of sign-up.

Every `data` object is a partial of one form; send only the fields the step
collects. The fields are camelCase and match the wizard: `legalEntityType`
(`Company` or `Individual`), `firstName`, `lastName`, `phone`, `role`,
`businessName`, `industry`, `businessModel`, `country` (ISO 3166-1 alpha-2),
`businessWebsite`, `registrationNumber`, `registeredAddress`,
`estimatedMonthlyVolume`, `averageTransactionSize`, `employeeCount`,
`paymentFlowsDescription`.
`country` is screened against the supported jurisdictions when it is submitted;
an unsupported country answers `422 countryNotSupported`.

Required per step (a missing or out-of-range value answers `400` naming the field):

| Step | Required |
|---|---|
| `personal_details` | `firstName`, `lastName` |
| `company_details` | `businessName`, `country` |
| `business_details` | `businessModel` (`marketplace`, `mor_marketplace`, `creator_platform`, `saas`, `service_aggregator`, `investment_platform`, `crowdfunding`, `professional_services`, `home_services`, `other`), `estimatedMonthlyVolume` (`no_revenue_yet`, `under_10k`, `10k_50k`, `50k_250k`, `250k_1m`, `over_1m` — USD per month), `averageTransactionSize` (`not_known_yet`, `under_50`, `50_200`, `200_1k`, `over_1k` — USD), `employeeCount` (`just_me`, `1_10`, `11_50`, `51_200`, `201_1000`, `over_1000`). The first value of each is for a business that has not started trading |
| `individual_details` | `country` |

#### curl

```bash
# 1 — start the draft; -c saves the session cookie, -b sends it on later calls
curl -sS -c cookies.txt -X POST https://api.fynex.ai/api/v1/onboarding/start \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "s3cur3-P@ssw0rd"}'

# 2 — the wizard steps, in order
curl -sS -b cookies.txt -X PATCH https://api.fynex.ai/api/v1/onboarding/step \
  -H "Content-Type: application/json" \
  -d '{"step": "legal_entity_type", "data": {"legalEntityType": "Company"}}'

curl -sS -b cookies.txt -X PATCH https://api.fynex.ai/api/v1/onboarding/step \
  -H "Content-Type: application/json" \
  -d '{"step": "personal_details", "data": {"firstName": "Alice", "lastName": "Smith", "phone": "+447700900000", "role": "owner"}}'

curl -sS -b cookies.txt -X PATCH https://api.fynex.ai/api/v1/onboarding/step \
  -H "Content-Type: application/json" \
  -d '{"step": "company_details", "data": {"businessName": "Acme Ltd", "country": "GB", "businessWebsite": "https://acme.example", "registeredAddress": "1 High St, London", "registrationNumber": "12345678"}}'

curl -sS -b cookies.txt -X PATCH https://api.fynex.ai/api/v1/onboarding/step \
  -H "Content-Type: application/json" \
  -d '{"step": "business_details", "data": {"businessModel": "saas", "estimatedMonthlyVolume": "10k_50k", "averageTransactionSize": "50_200", "employeeCount": "1_10"}}'

# 3 — the code from the verification e-mail
curl -sS -b cookies.txt -X POST https://api.fynex.ai/api/v1/verify-email \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

# 4 — complete: organization, legal entity, profile and a Demo seller account
curl -sS -b cookies.txt -X POST https://api.fynex.ai/api/v1/onboarding/complete
# Response: { "userId": "42", "organizationUuid": "…", "legalEntityIds": [77],
#             "organizationProfileIds": [12], "permissionTypes": [...] }
```

What `complete` leaves you with is a working **Demo** account: the sandbox
auto-provisioning that runs on completion adds wallets, a demo card terminal, a
demo counterparty payee, a pre-set split rule and three test customers, and
issues the account's first API key pair (retrieve the secret from
**Developers → API keys** in the dashboard — see [Getting your API key](#getting-your-api-key)).
Nothing here moves real money; Phase 3 is what takes the account live.

---

## Phase 2 — Additional company entities (Fynex dashboard)

> [!IMPORTANT]
> **Most integrations don't need this phase.** `POST /api/v1/onboarding/complete` (Phase 1)
> **already creates** the organization, legal entity, and organization profile for you in a
> single transaction. Its response returns `organizationUuid`, `legalEntityIds` and
> `organizationProfileIds`. To get an **API key**, you don't need this phase; see
> [Getting your API key](#getting-your-api-key) below.

If you manage **additional** legal entities or organization profiles under one account, add them in the Fynex dashboard, signed in with the account created in Phase 1. These steps are not available through a public API. If a step fails part-way, contact your Fynex representative to clean up before you retry.

---

## Getting your API key

Your API credential belongs to a **seller account**. The dashboard issues it: open **Developers**,
find the **API keys** card and click **New secret key** — the `sk_test_…` key is shown once.

A seller account can hold several keys and revoke them one at a time. The legacy token can only be regenerated (the **Regenerate** button in the Fynex dashboard), which stops the old value immediately, so prefer secret keys for anything that will run for a while. See [Authentication](https://docs.fynex.ai/payments-api/v2/docs#tag/authentication).

> [!IMPORTANT]
> A new seller account is created in `Demo` mode and **activated automatically**, so the key
> works immediately for **sandbox** payments. **KYB approval** is what flips the account to `Live`
> for real-money processing (with a Fynex-assigned live terminal); the account's `sk_test_…` keys
> stop working then and you issue an `sk_live_…` key. If a sandbox call returns
> `403 seller account is not active`, the key is still valid — the account just isn't active
> yet. See [Authentication](https://docs.fynex.ai/payments-api/v2/docs#tag/authentication).

---

## Phase 3 — KYB (Know Your Business)

Fynex uses a third-party KYB provider. Your integration obtains a short-lived KYB access token from Fynex, embeds the provider's Web SDK in your UI, and lets the customer fill the verification form. Fynex staff then review the submission and approve the account.

All KYB endpoints require the `dashboard_session` cookie.

| Endpoint | Purpose |
|----------|---------|
| `POST /api/v1/kyb/initiate` | Start a KYB application. Returns `{ token, status }`. |
| `GET /api/v1/kyb/token` | Refresh an existing KYB access token (tokens expire). |
| `GET /api/v1/kyb/status` | Poll the current KYB state. |
| `POST /api/v1/kyb/sdk-events` | Optional. Report the Web SDK's progress so Fynex can see which step a verification stopped at. Body `{ "event": "step_initiated" \| "step_completed" \| "applicant_submitted" \| "error", "step"?: "<document set type>", "error_code"?: "<code>" }` (`step` and `error_code` up to 64 characters; `error_code` only with `error`). Returns `204`, or `400` for a malformed body. Fire-and-forget: never block the form on it. |

1. **Initiate KYB and obtain the KYB access token**

```bash
curl -sS -b cookies.txt \
  -X POST https://api.fynex.ai/api/v1/kyb/initiate \
  -H "Content-Type: application/json"
# Response: { "token": "_act-...", "status": "pending" }
```

2. **Embed the KYB provider's Web SDK in your UI**

   Pass the token to the [provider's Web SDK](https://developers.sumsub.com/web-sdk/) to render the verification form. When the token expires (these tokens are short-lived), refresh it:

   ```js
   // When the SDK calls your token refresh handler:
   const refreshRes = await fetch('https://api.fynex.ai/api/v1/kyb/token', {
     credentials: 'include',
   });
   const { token: newToken } = await refreshRes.json();
   return newToken; // return to the SDK
   ```

   A minimal SDK integration:

   ```html
   <div id="sumsub-websdk-container"></div>
   <script src="https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>
   <script>
     const snsWebSdkInstance = snsWebSdk
       .init(KYB_TOKEN, () =>
         fetch('/api/kyb/token', { credentials: 'include' })
           .then(r => r.json())
           .then(d => d.token)
       )
       .withConf({ lang: 'en' })
       .withOptions({ addViewportTag: false, adaptIframeHeight: true })
       .on('idCheck.onApplicantSubmitted', () => console.log('Submitted'))
       .build();

     snsWebSdkInstance.launch('#sumsub-websdk-container');
   </script>
   ```

3. **Poll KYB status**

   After the customer submits the form, Fynex staff review the application. Poll `/api/v1/kyb/status` until the status is terminal.

   ```js
   const statusRes = await fetch('https://api.fynex.ai/api/v1/kyb/status', {
     credentials: 'include',
   });
   const { status } = await statusRes.json();
   // status values: "init" | "pending" | "approved" | "rejected"
   ```

   When approved, your `SellerAccount.operationalMode` flips from `Demo` to `Live`.

> [!CAUTION]
> **KYB token expiry.** KYB access tokens are short-lived. If you get a `401` or `invalid token` error from the SDK, call `GET /api/v1/kyb/token` to refresh. Pass the refresh function directly to the SDK's token-provider callback so it can renew tokens automatically without user interaction.

---

## Common pitfalls

| Pitfall | Fix |
|---------|-----|
| `complete` answers `403 emailNotVerified` | Consume the e-mailed code with `POST /api/v1/verify-email` first; `POST /api/v1/verify-email/resend` sends a fresh one. |
| `step` answers `409 invalidDraftState` | Steps must be submitted in order; you skipped one, or the draft is already completed. |
| KYB token expired | Call `GET /api/v1/kyb/token` and pass the refreshed token to the SDK. |
| Payments still in `Demo` mode after approval | Check `GET /api/v1/kyb/status`; if `approved`, allow a few minutes for the `operationalMode` flip. If it persists, contact support. |

## See also

- **[Going Live](https://docs.fynex.ai/payments-api/v2/docs#tag/going-live)** — Checklist and final steps once KYB is approved and operationalMode is live.
- **[Hosted Checkout](https://docs.fynex.ai/payments-api/v2/docs#tag/hosted-checkout)** — Start accepting payments immediately after your account is active.
