Enrollment widget

The ENROLLMENT widget type walks a user through account setup immediately after they authorize your application. It has the same shape as the other widget types — the user is redirected straight into a task after authorizing — with one difference: you choose which setup steps the user sees. Unlike the payout and pay-in types, this widget moves no money. There is no amount to confirm and no transaction to approve.

Prerequisites

A widget application with OAuth settings in place. See Configure App Widget. Any application type can run this widget, including a permissions-only OAuth Integration app.
The user must have granted your application’s scopes. Scopes are checked for the application as a whole, not per step. If any are missing, the widget sends the user through the OAuth consent screen before the first step, the same as the other widget types. No step is skipped or failed because of a scope.
An OAuth user and an access token, same as the other widget types.

Choosing the steps

Pass an ordered steps array in the pre-approved transaction token alongside transactionType: "ENROLLMENT":

import jwt from 'jsonwebtoken';

const generatedToken = jwt.sign(
  {
    appId: '', // Your App ID (Overview tab)
    transactionType: 'ENROLLMENT',
    externalId: '', // Your unique identifier for the user
    steps: ['KYC', 'FUNDING_SOURCE', 'PIN'],
    jti: uuidv4(),
  },
  secret, // Your apiSecret
  { expiresIn: '1 day' }
);

amount is not required for this widget type. Everything else about the token is unchanged — see Set Up Your Server. To link the user and run no setup steps, pass an empty array: steps: []. The widget ends at consent, so you get the grant and nothing else. This is the flow behind registerUser consent mode when you list no steps.

Supported steps

Step	What the user does
`KYC`	Completes personal identity verification, escalating to document capture if needed. See Verify by Widget.
`FUNDING_SOURCE`	Links one or more funding sources — a bank account via Plaid, a bank card, or PayPal.
`PIN`	Sets their Fluz transaction PIN.

This widget runs personal identity verification only. Business verification (KYB) is not one of its steps — use the dedicated KYB widget type for that. See Business Registration.

Order

Steps run in the order you list them. Fluz does not reorder them, and there are no invalid combinations — none of the three steps is a prerequisite for another, so ["PIN", "FUNDING_SOURCE", "KYC"] is as valid as ["KYC", "FUNDING_SOURCE", "PIN"]. List the steps in the order that makes sense for your product.

Skip behavior

A step the user has already satisfied is skipped silently — they never see its screen.

Step	Skipped when
`KYC`	The user has already passed identity verification
`PIN`	The user already has a PIN set
`FUNDING_SOURCE`	Never

The funding-source step is never skipped, because a user who already has one source may want to add another. It always renders, and the user decides when to move on. If every step you requested is already satisfied, or you passed steps: [], the widget completes immediately after consent without rendering a step screen.

Because FUNDING_SOURCE never auto-skips, a steps list that includes it always shows at least one screen. If you want the “nothing to do, complete immediately” outcome to be reachable, request only KYC and PIN.

The funding source step

This step is deliberately open-ended. The user can add as many funding sources as they like in one visit — the screen lists what they have added so far and carries an explicit Continue control, so advancing is their decision rather than something that happens automatically after the first successful link. A user who does not want to add anything can move on without adding a source. Funding-source changes do not emit a webhook yet. A dedicated event is in progress. Until it ships, read the user’s funding sources with the getWallet query after the flow completes. See Funding sources.

Opening a specific funding source

Staging onlytargetFundingSource is currently supported only in the staging environment. Production widgets do not honor it yet; this page will be updated when it is rolled out.

To send the user straight into one kind of funding source, add targetFundingSource to the token alongside steps:

const generatedToken = jwt.sign(
  {
    appId: '', // Your App ID (Overview tab)
    transactionType: 'ENROLLMENT',
    externalId: '', // Your unique identifier for the user
    steps: ['KYC', 'FUNDING_SOURCE', 'PIN'],
    targetFundingSource: 'BANK_ACCOUNT',
    jti: uuidv4(),
  },
  secret, // Your apiSecret
  { expiresIn: '1 day' }
);

Value	Where the funding source step opens
`BANK_ACCOUNT`	Plaid, ready to link a bank account.
`BANK_CARD`	The bank card form.
`PAYPAL`	The funding source type picker, where the user taps PayPal. PayPal opens in a pop-up window, and browsers only allow that after a tap, so the widget cannot launch it for the user.

This happens once, the first time the user reaches the step. After they link the source, they land on the usual funding source screen, which lists what they have added, lets them add another source of any type, and carries the Continue control. If they back out instead, they land on the type picker, where they can choose a different type or go back to the usual screen. targetFundingSource changes only where the step starts. It does not restrict the user to that type, and it does not make adding a source required. The claim is optional. Leave it out and the step opens on the usual screen. It is staging only for now — not yet supported in production.

Completion

When the last step resolves, the widget shows a completion screen. If you supplied a callbackUrl, it carries a button back to your application; otherwise it offers a Done control that closes the widget.

Do not infer success from the widget closing — a user can dismiss it at any point. Rely on the onSuccess and onError callbacks, and on webhooks for the individual steps: identity verification events fire independently of the widget. See Webhooks.

An enrollment that includes KYC only completes once identity verification passes. When a check fails, onError fires with US-0005 and onSuccess does not fire for that attempt. What happens next depends on where it failed: a check that ends with no further step to offer leaves the user on the form, where a retry that passes still completes the enrollment and fires onSuccess once; an account that goes into review is shown the review screen instead, and that session cannot complete. Either way, treat US-0005 as “not verified yet” rather than a final answer, and confirm the outcome from the KYC_STATUS_UPDATE webhook — which reaches you only if your application and the user’s grant both hold the VERIFY_KYC scope. See Outcome callbacks.

Rejected tokens

The steps and targetFundingSource claims are validated when the session opens. These all reject the session rather than degrading to a partial flow:

Problem	Result
`steps` missing entirely	Missing-parameter error
`steps` is not an array	Invalid-parameter error
`steps` contains a value that is not `KYC`, `FUNDING_SOURCE`, or `PIN`	Invalid-parameter error naming the unsupported value and listing the supported ones
`steps` lists the same step twice	Invalid-parameter error naming the duplicate
`targetFundingSource` is not `BANK_ACCOUNT`, `BANK_CARD`, or `PAYPAL`	Invalid-parameter error naming the unsupported value and listing the supported ones
`targetFundingSource` is set but `steps` does not include `FUNDING_SOURCE`	Invalid-parameter error
`targetFundingSource` is a type that is not enabled for your application	Invalid-parameter error naming the value and listing the types your application allows

The user sees a generic “invalid widget link” screen — the specific reason is not shown to them, since a malformed token is an integration problem rather than something they can act on. Check your token generator, and see the error detail delivered to your onError callback.

Next steps

Set up your server

Generate the pre-approved transaction token in your language.

Embed the widget

Script tag, init call, callbacks.

Verify by widget

What the user experiences during the KYC step.

Funding sources

What you can do with a source once it is linked.

​Choosing the steps

​Supported steps

​Order

​Skip behavior

​The funding source step

​Opening a specific funding source

​Completion

​Rejected tokens

​Next steps

Set up your server

Embed the widget

Verify by widget

Funding sources

Choosing the steps

Supported steps

Order

Skip behavior

The funding source step

Opening a specific funding source

Completion

Rejected tokens

Next steps