At Zeney Pay we build a mobile app for cross-border money transfers and real-time currency conversion. A fintech backend is mostly flows: sign-in with 2FA, registration, KYC, "forgot my PIN", setting up a transaction PIN, sending money. None of them fit in a single HTTP request.

For a while we handled them the way most teams do, and it went badly. This post covers what went wrong, how we changed our thinking, the design decisions behind the result, and the package that came out of it: na2axl/laravel-api-flow.

How it went wrong

Our flows were spread out in two ways:

• On the backend, one flow was split across several controllers. AuthController@login, OtpController@verify, PinController@check... Each endpoint had to work out for itself whether the caller had actually gone through the earlier steps.
• On the frontend, the mobile app held the rest. It decided which screen came next, when to skip the OTP screen, and what "back" meant.

This gave us several sources of truth for the same business process. Changing the order of two steps meant a backend deploy and a mobile release, with app store review in between. Old app versions kept following the old order. Each "is the user allowed to call this now?" check was written by hand, a little differently each time, and sometimes forgotten.

The turning point came when I saw what we were really doing: we were fitting business requirements into technical constraints. You do need an HTTP controller to handle a request. But the requests weren't standalone. They were transitions in a bigger state machine, and the backend had to be the only party that processes those transitions and decides whether they're valid.

Starting with sign-in

We started with authentication because it's the flow where getting it wrong hurts most. Here is sign-in as the business sees it:

Even this "simple" login has branches. The user may or may not have 2FA. 2FA can be an SMS OTP or a TOTP app. A user who lost their device can use a recovery code. Some users have to change their PIN before they get a session. Some never set a transaction PIN and get handed off to a different flow. If a client can reach check-pin without passing check-mfa, you've built a 2FA bypass.

Before writing code, we designed the API. For the backend to really be the source of truth, it had to meet five criteria:

1. Knowledge of the steps. The backend knows every step and how to process it.
2. Knowledge of the position. At any moment the backend knows where the machine currently is.
3. Memory. The state collected along the way (who is signing in, whether 2FA passed, which OTP was sent) lives across steps, on the server.
4. Navigation. For each step, the frontend knows which steps it can go to next and which earlier steps it can go back to.
5. Security. The backend rejects any wrong or illegal transition. It does this by construction, not through checks someone has to remember to write.

Each of these criteria led to a concrete design decision.

The package in 60 seconds

This is a complete flow:

use Na2axl\LaravelApiFlow\FlowController;
use Na2axl\LaravelApiFlow\FlowResponse;
use Na2axl\LaravelApiFlow\FlowState;

class SignupFlowController extends FlowController
{
    public const FLOW_ID = 'signup';

    protected string $flowStateClass = SignupState::class;
    protected string $flowId = self::FLOW_ID;
    protected ?int $staleTimeInMinutes = 15;

    public function stepInitiate(): FlowResponse
    {
        return $this->initiateFlow();
    }

    public function stepSetEmail(SetEmailRequest $request): FlowResponse
    {
        $this->validateStep($request->flowKey(), 'set-email'); // 410 if expired, 409 if illegal
        $this->appendState($request->flowKey(), ['email' => $request->validated('email')]);

        return $this->answer($request->flowKey(), 'set-email');
    }

    public function stepSetPlan(SetPlanRequest $request): FlowResponse
    {
        $this->validateStep($request->flowKey(), 'set-plan');
        $this->appendState($request->flowKey(), ['plan' => $request->validated('plan')]);

        return $this->answer($request->flowKey(), 'set-plan');
    }

    protected function nextSteps(string $current, FlowState $state): array
    {
        return match ($current) {
            'initiate'  => ['set-email'],
            'set-email' => ['set-plan'],
            'set-plan'  => [], // empty = the flow is finished, state is discarded
            default     => [],
        };
    }

    protected function backSteps(string $current, FlowState $state): array
    {
        return $current === 'set-plan' ? ['set-email'] : [];
    }

    protected function onRewind(string $step, FlowState $state): void
    {
        if ($step === 'set-email') {
            $state->plan = null; // re-answering the email discards the plan
        }
    }
}

Route::flow('signup', SignupFlowController::class);

Every step follows the same three beats: validateStep() -> do the work -> answer(). The client only ever sees this:

POST /signup/set-email  { "flow_key": "01J8Q0ZK...", "email": "a@b.c" }
-> 200 { "data": {}, "next_steps": ["set-plan"], "back_steps": [] }

POST /signup/set-plan  (jumping ahead on a fresh flow)
-> 409 { "message": "Unexpected step.", "code": "FLOW_UNEXPECTED_STEP" }

POST /signup/set-email  (stale flow key)
-> 410 { "message": "Flow expired.", "code": "FLOW_EXPIRED" }

Now for the reasoning behind each of those choices.

The design decisions (and what we didn't pick)

1. The flow is a controller, and each step is a real route

Each public stepXxx method is a step. Route::flow() reflects over the controller and registers one route per step: stepInitiate becomes GET /{prefix}/initiate, and every other stepFooBar becomes POST /{prefix}/foo-bar, named flow.{prefix}.foo-bar.

Route::flow('sign-in', SignInFlowController::class);
// GET  /sign-in/initiate
// POST /sign-in/authenticate
// POST /sign-in/check-mfa
// POST /sign-in/check-recovery-code
// POST /sign-in/check-pin

What we didn't pick: a single RPC-style endpoint (POST /flows/{flow} with {"step": "...", "payload": {...}}). It looks elegant, but you lose everything Laravel gives you per route: one FormRequest per step, per-route middleware and rate limits, route names, and OpenAPI generation. Our doc generator reads FlowRequest rules directly, so every step shows up documented with no extra work.

Also not picked: symfony/workflow or model-state packages. They're great, but they model the lifecycle of an entity that already exists (an order, an invoice). A sign-in flow has no entity yet. Before authenticate succeeds, we don't even know who the user is. Our flows are conversations, not record lifecycles.

2. The graph is a function, not a config file

nextSteps() and backSteps() take the current step and the full state:

abstract protected function nextSteps(string $current, FlowState $state): array;

This is how branching works. After authenticate, the next steps depend on $state->needMfa. We thought about a declarative graph in YAML or arrays, but every real flow needs conditions. Once a DSL grows conditions, you're writing a worse PHP. A match expression is readable, type-checked, and covered by your static analysis.

The order of the list matters: the first entry is the default the UI should show, and the rest are alternatives. ['check-mfa', 'check-recovery-code'] means "show the OTP screen, and offer an 'I lost my device' link".

3. Explicit back-edges and destructive rewind

Going back isn't a generic "undo". Each step says which earlier steps can be re-answered from it. Re-answering one rewinds the flow: onRewind() clears everything downstream.

The rewind is deliberately destructive. A partial merge would keep decisions made on outdated answers. Suppose a user changes their destination country after picking a payout method. That payout method may not exist in the new country, and silently keeping it is how bugs get into production.

One subtle point: the rewind only changes the in-memory state until the step commits.

if ($isBack) {
    // The rewind mutates the memo only: if the body later fails (e.g. a
    // throttle refusal), the cached flow must stay untouched, so the
    // write-through happens when the body commits via setState().
    $this->onRewind($stepName, $state);
}

If a re-answered step fails halfway (validation, rate limit, provider timeout), the user's flow in the cache is left exactly as it was.

4. The flow key is a ULID in the request body, not a session

initiateFlow() generates a ULID flow_key, stores the initial state, and returns it. Every later step sends it back.

What we didn't pick: server sessions or cookies. Our main client is a mobile app talking to a stateless API, users sometimes have two flows in progress at once, and we run on FrankenPHP workers. A flow key in the body is explicit, easy to test, and scoped to one flow. The ULID format is also validated cheaply (required|string|ulid) before we go to the cache.

5. State lives in the cache with a TTL, not the database

protected function setState(string $flowKey, FlowState $state): void
{
    $ttl = now()->addMinutes($this->staleTimeInMinutes ?? LaravelApiFlow::staleTime());

    $this->cache()->put("{$this->flowId}:{$flowKey}", $state->toArray(), $ttl);
    // ...
}

Flow state is ephemeral by design. An abandoned sign-in shouldn't leave a half-written row anywhere. The TTL also acts as a security boundary: an OTP challenge stored in a sign-in flow dies with the flow. Each write refreshes the TTL, so the timeout is "X minutes of inactivity", not "X minutes in total". When nextSteps() returns [], answer() calls forgetState() and the flow deletes itself.

The store is configurable (FLOW_CACHE_STORE). We used Redis as our storage.

6. Typed state

The state is a class, not an array:

class SignInState extends FlowState
{
    public ?string $customerId = null;
    public bool $needMfa = false;
    public ?MfaMode $mfaMode = null;
    public bool $verified = false;
    // constructor hydrates from the raw cached array, toArray() serialises back
}

Our first internal version used plain arrays described by a PHPStan array{...} shape. It worked, but typos in keys got through code review, and the "rules" of the flow ended up scattered across the arrays. More on that below.

7. Three layers of guards, each with its own status code

A step request goes through three checks, in this order:

The order is intentional. If a flow has expired, the client should get a 410 and restart, not a 422 about a field on a screen it shouldn't be on. Each code maps to one client reaction: 410 -> restart the flow, 409 -> resync with the last next_steps, 422 -> show field errors. No more guessing from error messages.

A step request only declares its own fields:

use Na2axl\LaravelApiFlow\Http\FlowRequest;

class CheckMfaRequest extends FlowRequest
{
    protected bool $defaultAuthorize = true; // guest flow

    protected function stepRules(): array
    {
        return ['code' => ['required', 'string', 'regex:/^[0-9]{6}$/']];
    }
}

The flow id is resolved from the controller the route points to, so you don't have to repeat it.

8. Octane-safe memoization

This one is subtle. Laravel's Route objects keep their controller instance, so on long-lived runtimes (Octane, FrankenPHP workers) a controller can outlive a request. A naive $this->state cache on the controller would leak one user's flow into the next request.

State is memoized per request, and the memo resets when a new request arrives:

private function resetMemoOnNewRequest(): void
{
    $current = request();

    if ($this->memoRequest !== $current) {
        $this->stateMemo = [];
        $this->memoRequest = $current;
    }
}

How we handled authentication

Authentication shows up in two ways: flows that run before the user is authenticated (sign-in, register, forgot password), and flows that require an authenticated user (enable MFA, change password, set up a transaction PIN).

Guest flows: the flow key is a short-lived capability

For guest flows, the step requests set $defaultAuthorize = true. The only thing tying the steps together is the flow_key. That's acceptable because the key:

• has 80 bits of randomness (ULID),
• is scoped to one flow type ({flowId}:{flowKey} in the cache),
• expires after a few minutes of inactivity,
• only allows the transitions currently listed in next_steps.

So a stolen key from a sign-in flow that's sitting on check-mfa gives you the right to... guess a 6-digit OTP, on a rate-limited route, for a few minutes. It never gives you the right to skip to check-pin.

Authenticated flows: ownership is bound to the flow

For flows behind auth:sanctum, set $flowGuard on the controller:

class MfaEnableFlowController extends FlowController
{
    protected ?string $flowGuard = 'customer';
    // ...
}

Route::middleware('auth:sanctum')->group(function () {
    Route::flow('mfa-enable', MfaEnableFlowController::class);
});

Every time the flow commits state for an authenticated user, it also caches the owner's id next to it ({flowId}:{flowKey}:owner). FlowRequest::authorize() then compares that owner with the current user:

$user = $this->user($this->flowGuard);

if ($user) {
    return LaravelApiFlow::cache()->get("{$flowId}:{$flowKey}:owner") === $user->getAuthIdentifier();
}

return $this->defaultAuthorize;

Alice can't advance Bob's MFA setup even if she gets hold of his flow key: she gets a 403.

Sign-in itself: the token comes out of the last step

The main rule: a Sanctum token is only created in a terminal step. Here is a simplified version of our sign-in written against the package:

enum SignInStep: string
{
    case Initiate = 'initiate';
    case Authenticate = 'authenticate';
    case CheckMfa = 'check-mfa';
    case CheckRecoveryCode = 'check-recovery-code';
    case CheckPin = 'check-pin';
}

/** @extends FlowController<SignInState> */
final class SignInFlowController extends FlowController
{
    protected string $flowId = 'sign-in';
    protected string $flowStateClass = SignInState::class;
    protected ?string $flowGuard = 'customer';

    public function stepInitiate(): FlowResponse
    {
        return $this->initiateFlow();
    }

    public function stepAuthenticate(AuthenticateRequest $request): FlowResponse
    {
        $key = $request->flowKey();
        $this->validateStep($key, SignInStep::Authenticate);

        $customer = $this->customers->findByLogin($request->validated());

        if (! $customer || ! Hash::check($request->validated('password'), $customer->credential->password)) {
            // Nothing is committed: the flow stays on `authenticate`, the client can retry.
            throw new SignInFailed('wrong_password');
        }

        $needMfa = $customer->credential->tfa_enabled;

        if ($needMfa && $customer->credential->tfa_mode === MfaMode::PASSCODE) {
            $this->sendOtp->execute($request->validated('phone_number'), MessageChannel::SMS);
        }

        $this->appendState($key, [
            'customer_id' => $customer->id,
            'need_mfa' => $needMfa,
            'mfa_mode' => $customer->credential->tfa_mode,
            'verified' => ! $needMfa,
        ]);

        return $this->answer($key, SignInStep::Authenticate, ['need_mfa' => $needMfa]);
    }

    public function stepCheckPin(CheckPinRequest $request): FlowResponse
    {
        $key = $request->flowKey();
        $state = $this->validateStep($key, SignInStep::CheckPin);

        $customer = $this->customers->retrieve($state->customerId);
        $this->pins->check($customer, $request->validated('code')); // throws on failure

        // Terminal step: next_steps is empty, so answer() forgets the flow.
        return $this->answer($key, SignInStep::CheckPin, [
            'token' => $customer->createToken('mobile')->plainTextToken,
            'customer' => CustomerResource::make($customer),
        ]);
    }

    // stepCheckMfa / stepCheckRecoveryCode omitted for brevity

    protected function nextSteps(string $current, FlowState $state): array
    {
        return match (SignInStep::from($current)) {
            SignInStep::Initiate => [SignInStep::Authenticate->value],
            SignInStep::Authenticate => $state->needMfa
                ? [SignInStep::CheckMfa->value, SignInStep::CheckRecoveryCode->value]
                : [SignInStep::CheckPin->value],
            SignInStep::CheckMfa,
            SignInStep::CheckRecoveryCode => [SignInStep::CheckPin->value],
            SignInStep::CheckPin => [],
        };
    }

    protected function backSteps(string $current, FlowState $state): array
    {
        // "Use another account" from the 2FA screen
        return in_array($current, ['check-mfa', 'check-recovery-code'], true)
            ? [SignInStep::Authenticate->value]
            : [];
    }

    protected function onRewind(string $step, FlowState $state): void
    {
        if ($step === SignInStep::Authenticate->value) {
            $state->customerId = null;
            $state->needMfa = false;
            $state->verified = false;
        }
    }
}

A few things to notice:

• The 2FA bypass can't happen. When needMfa is true, check-pin isn't in next_steps until check-mfa or check-recovery-code has committed. A client calling it early gets a 409, and nobody had to write an if.
• A failed step doesn't commit. Wrong password, wrong OTP: we throw before answer(), so the machine stays where it was and the user can retry. Rate limiting is a normal route middleware.
• The flow deletes itself at the end. Once the token is issued, the flow key is useless.
• Cross-cutting context goes in the state too. In production, authenticate also records which data region the customer's records live in, so every later step talks to the right database without looking it up again.

The real flow has two more exits, which you can see in the diagram. A customer whose PIN was reset by support must choose a new one before getting a session. A customer who never set a transaction PIN gets handed off to the separate pin-code-setup flow. Flows can chain like this: one flow's terminal answer is another flow's entry ticket.

What we got out of it

• One source of truth. The flow graph exists in exactly one place: a PHP match. You can read the whole business process in a single file.
• The mobile app is a renderer. The mobile app maps a step name to a screen and shows next_steps[0]. Adding a branch, reordering steps or making a step conditional is a backend deploy, with no app store review, as long as the screen already exists. Old app versions follow the new graph automatically.
• Secure by construction. Skipping, replaying or reordering steps is rejected by the engine, not by checks sprinkled around the code.
• A consistent contract. Auth, KYC, transfers, PIN reset: every flow has the same envelope (data, next_steps, back_steps, flow_key) and the same error codes. The client handles 409 and 410 once, for all of them.
• No dead rows. Abandoned flows expire from the cache. The database only ever sees finished business actions.
• Tests that read like the spec. One feature test per edge: "from authenticate with 2FA, check-pin is a 409". The graph is also the test plan.
• Routing and docs for free. One Route::flow() line per flow, and every step is a normal route with its own FormRequest that the OpenAPI generator already understands.

On the client side, the core loop looks roughly like this (simplified):

final res = await api.post('/sign-in/$step', {'flow_key': flowKey, ...payload});

switch (res.statusCode) {
  case 200:
    final next = List<String>.from(res.data['next_steps']);
    if (next.isEmpty) return onFlowCompleted(res.data['data']);
    router.go(screenFor(next.first), extra: FlowContext(
      flowKey: flowKey,
      alternatives: next.skip(1).toList(),
      back: List<String>.from(res.data['back_steps']),
    ));
  case 409: resyncWithLastKnownSteps();
  case 410: restartFlow();
  case 422: showFieldErrors(res.data['errors']);
}

The honest part: trade-offs

• The cache is now critical infrastructure. If Redis is down, nobody can sign in. We accept that because the same is already true of sessions and rate limiting.
• Flows are short-lived by design. A KYC review that waits two days for a compliance officer is not a flow. It's an entity with a lifecycle in the database. We use flows for the interactive part (collecting documents) and hand off to a persisted model at the end.
• More round trips. One request per step instead of one big submit. On flaky mobile networks (pretty common in Africa), we found the extra round trips worth it, because each one returns immediate, specific feedback instead of a giant form failing at the end.
• The client still has to know the screens. Server-driven navigation doesn't mean server-driven UI. The app needs a screen for every step name it might receive.

Wrapping up

The biggest change was a way of thinking, not code: stop mapping business processes one-to-one onto endpoints. An endpoint is how a transition reaches you. The process is the state machine, and it belongs on the server, in one place, enforced by default.

The first version lived in Zeney's shared package, and 22 flows across our services run on it today: sign-in, registration, password and PIN recovery, five KYC flows, wallet creation, payments, remittances, refunds, payment method setup, and more. Its guards were written by hand, as per-request checks on flags like verified === true. That was an implicit state machine: it worked, but the graph only existed in people's heads. Extracting it into a package was the chance to make the graph explicit, add proper back-navigation, and give every rejection its own status code.

The package supports PHP 8.2+ and Laravel 12/13, is MIT licensed, and is on GitHub:

composer require na2axl/laravel-api-flow

I'd love to hear how you model multi-step flows. Do you keep them on the server, the client, or somewhere in between? Issues, PRs and strong opinions are all welcome.