Set up your server for the Fluz JS widget

To use the Fluz JS widget, you do two things:

On your page, load the widget JavaScript and bind a UI element (for example, a button) to open the widget modal.
On your server, generate a signed JWT, the pre-approved transaction token (patToken), and pass it to the widget.

This page covers step 2.

What the patToken does

Because the user is moving money into or out of your operator spend account through Fluz, every widget session must carry a signed JWT that pre-authorizes that specific transaction. For example, if user abc123 has $50 in your operator spend account and wants to withdraw it to their Fluz account, your server generates a patToken with transactionType: "WITHDRAW" and amount: 50.00. Fluz validates the token before allowing the transaction. Sign the token with HS256 using your apiSecret, which you can find in your app details under For Developers in Fluz.

Always generate the token on your server. Never expose your apiSecret in client-side code.

Token claims

Required

Claim	Description
`appId`	Your app’s App ID, shown on the Overview tab of your app in the Developer Console.
`transactionType`	One of `DEPOSIT`, `WITHDRAW`, or `ENROLLMENT`. `DEPOSIT`: the user adds money to Fluz, which then moves to your operator spend account. `WITHDRAW`: a payout from your operator spend account to the user’s Fluz account. `ENROLLMENT`: runs account setup instead of a transaction. See Enrollment Widget.
`amount`	The amount, in dollars and cents, the user is approved to transact. Required for `DEPOSIT` and `WITHDRAW`; omit it for `ENROLLMENT`.
`externalId`	Your unique identifier for the user, such as a user ID, account ID, phone number, or email address. Fluz includes it in webhook events so you can map the user back to your system.
`jti`	A UUID v4 generated each time you sign a token. Fluz uses it for idempotency. See the JWT spec.
`exp`	Token expiry as a Unix timestamp. The examples below use 24 hours.
`steps`	Required only when `transactionType` is `ENROLLMENT`; ignored otherwise. An ordered array of setup steps to show: `KYC`, `FUNDING_SOURCE`, `PIN`. Pass `[]` to end the flow at consent. Unknown or duplicate values reject the session.

Never put your API key in the token, and never pass it to the browser. Your API key is your application’s credential: anyone who has it can call the Fluz API as your application. The token is visible in the user’s browser, so identify your application with appId only. The token’s signature, made with your API secret on your server, proves it came from you.

Optional (prefill user details)

Claim	Description
`phoneNumber`	The user’s phone number. If provided, the user skips the Enter the phone number step and goes straight to Enter the two-factor authentication code.
`firstName`	The user’s first name.
`lastName`	The user’s last name.
`email`	The user’s email address.
`username`	The user’s username.

Optional (enrollment)

Claim	Description
`targetFundingSource`	Staging only for now — not yet supported in production. Used only when `transactionType` is `ENROLLMENT`; ignored otherwise. One of `BANK_ACCOUNT`, `BANK_CARD`, `PAYPAL`. Opens that funding source’s flow the first time the user reaches the `FUNDING_SOURCE` step. Requires `FUNDING_SOURCE` in `steps`. An unknown value rejects the session. See Opening a specific funding source.

Generate the token

Pick your language from the dropdown. Each example includes the install command at the top and signs the required claims; add any optional claims to the same payload.

JavaScript (Node.js)

// npm install jsonwebtoken
import jwt from 'jsonwebtoken';
import { randomUUID } from 'node:crypto';

const amount = 0.0;        // Amount in dollars and cents
const transactionType = ''; // DEPOSIT or WITHDRAW
const externalId = '';      // Your unique identifier for the user
const appId = '';           // Your App ID (Overview tab)
const secret = '';          // Your apiSecret

const patToken = jwt.sign(
  {
    amount,
    appId,
    transactionType,
    externalId,
    jti: randomUUID(),
  },
  secret,
  { algorithm: 'HS256', expiresIn: '1d' }
);

console.log(patToken);

# pip install PyJWT
import uuid
from datetime import datetime, timedelta, timezone

import jwt

amount = 0.0           # Amount in dollars and cents
transaction_type = ""  # DEPOSIT or WITHDRAW
external_id = ""       # Your unique identifier for the user
app_id = ""            # Your App ID (Overview tab)
secret = ""            # Your apiSecret

payload = {
    "amount": amount,
    "appId": app_id,
    "transactionType": transaction_type,
    "externalId": external_id,
    "jti": str(uuid.uuid4()),
    "exp": datetime.now(timezone.utc) + timedelta(days=1),
}

pat_token = jwt.encode(payload, secret, algorithm="HS256")
print(pat_token)

# gem install jwt
require 'jwt'
require 'securerandom'

amount = 0.0           # Amount in dollars and cents
transaction_type = ""  # DEPOSIT or WITHDRAW
external_id = ""       # Your unique identifier for the user
app_id = ""            # Your App ID (Overview tab)
secret = ""            # Your apiSecret

payload = {
  amount: amount,
  appId: app_id,
  transactionType: transaction_type,
  externalId: external_id,
  jti: SecureRandom.uuid,
  exp: Time.now.to_i + (24 * 60 * 60) # 1 day
}

pat_token = JWT.encode(payload, secret, 'HS256')
puts pat_token

// go get github.com/golang-jwt/jwt/v5 github.com/google/uuid
package main

import (
	"fmt"
	"time"

	"github.com/golang-jwt/jwt/v5"
	"github.com/google/uuid"
)

func main() {
	amount := 0.0          // Amount in dollars and cents
	transactionType := "" // DEPOSIT or WITHDRAW
	externalId := ""      // Your unique identifier for the user
	appId := ""           // Your App ID (Overview tab)
	secret := ""          // Your apiSecret

	claims := jwt.MapClaims{
		"amount":          amount,
		"appId":           appId,
		"transactionType": transactionType,
		"externalId":      externalId,
		"jti":             uuid.NewString(),
		"exp":             time.Now().Add(24 * time.Hour).Unix(),
	}

	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	patToken, err := token.SignedString([]byte(secret))
	if err != nil {
		fmt.Println("Error generating token:", err)
		return
	}

	fmt.Println(patToken)
}

// Maven: io.jsonwebtoken:jjwt-api, jjwt-impl, jjwt-jackson (0.12.x)
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.util.Date;
import java.util.UUID;

public class PatTokenGenerator {
    public static void main(String[] args) {
        double amount = 0.0;          // Amount in dollars and cents
        String transactionType = "";  // DEPOSIT or WITHDRAW
        String externalId = "";       // Your unique identifier for the user
        String appId = "";            // Your App ID (Overview tab)
        String secret = "";           // Your apiSecret

        SecretKey key = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
        long oneDayMs = 24L * 60 * 60 * 1000;

        String patToken = Jwts.builder()
                .claim("amount", amount)
                .claim("appId", appId)
                .claim("transactionType", transactionType)
                .claim("externalId", externalId)
                .id(UUID.randomUUID().toString())
                .expiration(new Date(System.currentTimeMillis() + oneDayMs))
                .signWith(key, Jwts.SIG.HS256)
                .compact();

        System.out.println(patToken);
    }
}

<?php
// composer require firebase/php-jwt ramsey/uuid
require 'vendor/autoload.php';

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$amount = 0.0;          // Amount in dollars and cents
$transactionType = "";  // DEPOSIT or WITHDRAW
$externalId = "";       // Your unique identifier for the user
$appId = "";            // Your App ID (Overview tab)
$secret = "";           // Your apiSecret

$payload = [
    "amount"          => $amount,
    "appId"           => $appId,
    "transactionType" => $transactionType,
    "externalId"      => $externalId,
    "jti"             => Uuid::uuid4()->toString(),
    "exp"             => time() + (24 * 60 * 60), // 1 day
];

$patToken = JWT::encode($payload, $secret, 'HS256');
echo $patToken;

// dotnet add package System.IdentityModel.Tokens.Jwt
using System;
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using Microsoft.IdentityModel.Tokens;

class PatTokenGenerator
{
    static void Main()
    {
        decimal amount = 0.0m;         // Amount in dollars and cents
        string transactionType = "";  // DEPOSIT or WITHDRAW
        string externalId = "";       // Your unique identifier for the user
        string appId = "";            // Your App ID (Overview tab)
        string secret = "";           // Your apiSecret

        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secret));
        var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

        var payload = new JwtPayload
        {
            { "amount", amount },
            { "appId", appId },
            { "transactionType", transactionType },
            { "externalId", externalId },
            { "jti", Guid.NewGuid().ToString() },
            { "exp", DateTimeOffset.UtcNow.AddDays(1).ToUnixTimeSeconds() }
        };

        var token = new JwtSecurityToken(new JwtHeader(creds), payload);
        var patToken = new JwtSecurityTokenHandler().WriteToken(token);

        Console.WriteLine(patToken);
    }
}

​What the patToken does

​Token claims

​Required

​Optional (prefill user details)

​Optional (enrollment)

​Generate the token

What the patToken does

Token claims

Required

Optional (prefill user details)

Optional (enrollment)

Generate the token