Integrate Multi-Factor Authentication

Before you begin

• A signed-in session. Enrolment happens as an authenticated action, never during sign-up from an unauthenticated request.
• A decision about enforcement: optional, required for admins, or required for everyone in an organization.
• A recovery plan. Codes get lost with phones, so either issue backup codes at enrolment or define who may reset a factor.
• A list of the actions that deserve a step-up prompt. Changing an email, moving money, exporting data.

Install

Every example on this page uses the Node.js client. The same calls exist in the Python, Go, Ruby, PHP and Java SDKs, following the naming conventions of each language.

1npm i @paycux/node

Configure

MFA rides on the session you already have. The issuer name below is what appears in the person's authenticator app next to the code, so make it the name of your product.

1PAYCUX_API_KEY=sk_example_7f4c1b9ad2e84c6f
2PAYCUX_CLIENT_ID=client_01HQZX8N4T
3PAYCUX_MFA_ISSUER=Your Product

Then, in the dashboard:

1. 1Open Authentication, then Multi-Factor, and enable the factor types you want: authenticator app, SMS one-time code, or both.
2. 2Set the enforcement policy. Requiring MFA for admin roles only is a reasonable first step and does not block sign-up.
3. 3Set the issuer name and check how it renders in an authenticator app before you ship it.
4. 4Choose whether backup codes are issued automatically at enrolment.
5. 5Decide who may reset a factor: an organization admin, your support team, or both, and note that this decision is itself a security boundary.

Implement

Enrolment is three steps in a fixed order: create a factor, show the QR code, then activate it with a code the person types. A factor is not enrolled until it has been challenged successfully once.

1import { Paycux } from "@paycux/node";
2import { requireSession } from "@/lib/session";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function POST() {
7  const { user } = await requireSession();
8 
9  const factor = await paycux.mfa.enrollFactor({
10    userId: user.id,
11    type: "totp",
12    issuer: process.env.PAYCUX_MFA_ISSUER,
13    accountName: user.email,
14  });
15 
16  return Response.json({
17    factorId: factor.id,
18    qrCode: factor.totp.qrCode,
19    secret: factor.totp.secret,
20  });
21}

1import { Paycux } from "@paycux/node";
2import { requireSession } from "@/lib/session";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function POST(request: Request) {
7  await requireSession();
8  const { factorId, code } = await request.json();
9 
10  const result = await paycux.mfa.activateFactor({ factorId, code });
11 
12  if (!result.valid) {
13    return Response.json({ error: "invalid_code" }, { status: 400 });
14  }
15 
16  return Response.json({ ok: true, backupCodes: result.backupCodes });
17}

1import { Paycux } from "@paycux/node";
2import { requireSession } from "@/lib/session";
3 
4const paycux = new Paycux(process.env.PAYCUX_API_KEY);
5 
6export async function POST(request: Request) {
7  const { user } = await requireSession();
8  const { newEmail, factorId, code } = await request.json();
9 
10  const challenge = await paycux.mfa.verifyChallenge({ factorId, code });
11 
12  if (!challenge.valid) {
13    return Response.json({ error: "step_up_required" }, { status: 401 });
14  }
15 
16  await paycux.userManagement.updateUser({ userId: user.id, email: newEmail });
17 
18  return Response.json({ ok: true });
19}

Verify

Test the enrolment path, then test the ways it goes wrong. Most MFA incidents are recovery problems, not verification problems.

1. 1Enrol a factor with a real authenticator app and confirm the issuer and account name read correctly on the phone.
2. 2Enter a wrong code and confirm the factor stays unactivated rather than half-created.
3. 3Sign out and back in, and confirm the challenge is required at the point your policy says it should be.
4. 4Trigger a step-up action and confirm it refuses without a fresh code, even though the session is already MFA-verified.
5. 5Use a backup code, then use the same one again. The second attempt must fail.

Reference

Request and response shapes for each of these live in the API reference. Paths are relative to https://api.paycux.com.

Next steps