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 user access token for the user you’re verifying (see Generate a User Access Token).

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

Step 1 — Create a test user

Verification applies to one user. Create a fresh staging user with the registerUser mutation, then generate a user access token for it.

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.

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"
}

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
`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

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.
forceRetry: true on verifyUserInformation re-runs verification for a user and bypasses the duplicate check.
Already verified users return ERROR with User is already KYC verified. Treat this as success in your integration, not a failure.
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.

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 a test user

Step 2 — Use the approved test identity

Step 3 — Run the verification

Step 4 — Understand each outcome

Attempts, retries, and resets

Next steps

KYB testing

User KYC verification

​Step 1 — Create a test user

​Step 2 — Use the approved test identity

​Step 3 — Run the verification

​Step 4 — Understand each outcome

​Attempts, retries, and resets

​Next steps

KYB testing

User KYC verification

Step 1 — Create a test user

Step 2 — Use the approved test identity

Step 3 — Run the verification

Step 4 — Understand each outcome

Attempts, retries, and resets

Next steps