Test KYC flows

Fluz requires users to be KYC verified before they can perform certain transactions or unlock higher limits. In the staging environment you can run the entire verification flow against known test identities. That lets you confirm your integration handles every outcome without using a real person’s information. For the full mutation contract and response reference, see User KYC Verification.

Staging onlyThe identities on this page exist only on the staging endpoint (https://transactional-graph.staging.fluzapp.com/api/v1/graphql). They are synthetic and will not verify in production. Never submit a real person’s name, address, date of birth, or SSN to staging.

Before you start, you’ll need:

an OAuth Integration application that Fluz has moved to ACTIVE, with the VERIFY_KYC scope enabled (see Prepare Your Accounts);
a test user who has completed the OAuth grant for that application (see Client-Facing OAuth Grant Flow);
a user access token for that user (see Generate a User Access Token).

The token decides which staging user the verification applies to. See How accounts work.

Step 1 — Create and connect a test user

Verification applies to one user, and you can only verify a user your application is authorized to act for.

Create a fresh staging user with the registerUser mutation. Leave out deferSeatAssignment.
Send that user through the OAuth grant flow. In staging, no SMS is sent: enter 123456 as the sign-in code.
Generate a user access token for the user with the VERIFY_KYC scope.

Registering a user doesn’t authorize your application. If you skip step 2, generateUserAccessToken and getAccountsByUserId fail with AUTH-0031.

Restricted accessregisterUser must be enabled on your application by Fluz. If it isn’t, calls fail with AUTH-0022. If the application isn’t active yet, calls fail with AUTH-0030 … current status: PERSONAL. Contact your account manager or partnerships@fluz.app for either.

Step 2 — Use the approved test identity

The identity below returns an APPROVED result on staging the first time it is used. Submit it exactly as shown.

Field	Value
First name	John
Last name	Smith
Street address	222333 Peachtree Place
City	Atlanta
State	GA
ZIP / postal code	30318
Date of birth	02/28/1975
SSN	112-22-3333

The API only consumes the last 4 digits of the SSN (ssnLast4). For this identity that’s 3333. Date of birth is formatted as MM/DD/YYYY.

One approved identity verifies one user. Submitting the same identity for a second user returns DUPLICATE, and that second user is not verified. To verify more test users with the same identity, see Verifying more than one test user.

Step 3 — Run the verification

Call verifyUserInformation with the approved identity. Replace <USER_ACCESS_TOKEN> with the token for the user being verified. The token must carry the VERIFY_KYC scope. It isn’t self-serve: Fluz has to enable it on your application first. Without it, the call fails with AUTH-0031.

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -d '{
    "query": "mutation VerifyUserInformation { verifyUserInformation(firstName: \"John\", lastName: \"Smith\", streetLine1: \"222333 Peachtree Place\", streetLine2: \"\", city: \"Atlanta\", state: \"GA\", postalCode: \"30318\", country: \"United States\", dateOfBirth: \"02/28/1975\", ssnLast4: \"3333\") { status message } }"
  }'

const response = await fetch(
  "https://transactional-graph.staging.fluzapp.com/api/v1/graphql",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      query: `
        mutation VerifyUserInformation(
          $firstName: String!
          $lastName: String!
          $streetLine1: String!
          $streetLine2: String
          $city: String!
          $state: String!
          $postalCode: String!
          $country: String!
          $dateOfBirth: String!
          $ssnLast4: String!
        ) {
          verifyUserInformation(
            firstName: $firstName
            lastName: $lastName
            streetLine1: $streetLine1
            streetLine2: $streetLine2
            city: $city
            state: $state
            postalCode: $postalCode
            country: $country
            dateOfBirth: $dateOfBirth
            ssnLast4: $ssnLast4
          ) {
            status
            message
          }
        }
      `,
      variables: {
        firstName: "John",
        lastName: "Smith",
        streetLine1: "222333 Peachtree Place",
        streetLine2: "",
        city: "Atlanta",
        state: "GA",
        postalCode: "30318",
        country: "United States",
        dateOfBirth: "02/28/1975",
        ssnLast4: "3333",
      },
    }),
  }
);

const data = await response.json();
console.log(data.data.verifyUserInformation);

Approved response

{
  "status": "APPROVED",
  "message": "User verification successful"
}

There is no query that returns a user’s KYC status. Take the result from this response, and from the KYC_STATUS_UPDATE webhook, which needs VERIFY_KYC on both your application and the user’s grant.

Step 4 — Understand each outcome

Only APPROVED makes a user verified. Card issuing, and acting as a registerBusiness applicant, both require a successful verification on file.

Status	Message	Counts as verified?	How it happens on staging
`APPROVED`	User verification successful	Yes	The approved test identity, on a user that has never used it
`DECLINED`	Verification declined	No	Any identity that doesn’t match the approved one — for example, a different SSN last 4, date of birth, or name
`DUPLICATE`	Duplicate user verification	No	The identity already verified a different user
`ERROR`	Exceeded user verification limit	No	A 4th verification attempt for the same user
`ERROR`	User is already KYC verified	Already verified	The user was verified earlier; nothing more to do

Applicants for a US business need SSN verification. If this user will register a business as an owner with isUsPerson: true, they must pass the SSN path above. A user verified another way shows up on the business as an owner stuck at PENDING_CIP with verificationType: SSN. See KYB Testing.

Attempts, retries, and resets

Three attempts per user. A user can be submitted at most 3 times; the next submission returns ERROR. Plan your tests so you don’t use up attempts on a user you still need.
“Already verified” isn’t an attempt. An ERROR with User is already KYC verified doesn’t count toward the 3. Treat it as success in your integration, not a failure.
forceRetry: true on verifyUserInformation re-runs verification for a user and bypasses the duplicate check.
Resets. There is no API to reset a staging user’s attempts. Register a fresh test user, or ask your Fluz contact to reset one.
Tokens are per user. The access token decides which user is verified. Make sure it belongs to the test user whose identity you’re submitting.

Verifying more than one test user

The approved identity verifies one user per normal submission. To get another test user to APPROVED with the same identity, submit it for that user with forceRetry: true, which bypasses the duplicate check. Make sure the user isn’t already verified first.

Next steps

KYB testing

Test tax IDs and owner verification for business registration.

User KYC verification

The full mutation contract: document verification links, statuses, and responses.

Get started

Fluz dashboard

Quickstarts

Test KYC flows

Step 1 — Create and connect a test user

Step 2 — Use the approved test identity

Step 3 — Run the verification

Step 4 — Understand each outcome

Attempts, retries, and resets

Verifying more than one test user

Next steps

KYB testing

User KYC verification

​Step 1 — Create and connect a test user

​Step 2 — Use the approved test identity

​Step 3 — Run the verification

​Step 4 — Understand each outcome

​Attempts, retries, and resets

​Verifying more than one test user

​Next steps

KYB testing

User KYC verification

Step 1 — Create and connect a test user

Step 2 — Use the approved test identity

Step 3 — Run the verification

Step 4 — Understand each outcome

Attempts, retries, and resets

Verifying more than one test user

Next steps