How do I make sure that an old successful session cannot approve a new withdrawal?

Create a session for each operation, give it a client key that combines the account and the operation, and read the status of that session only. Your server holds the operation until that session is final.

Does the platform decide which operations need a check?

No. The rule is yours. Your own system notices the withdrawal, the beneficiary change or the amount, holds the operation and starts the session.

What does the platform compare?

A returning user is compared with a stored reference face. The scenario settings include a required face match with a reference session. How a reference is set up for your flow is a conversation with the team. The liveness step asks the user to move the face closer through two ovals.

Who can settle a held operation by hand?

A reviewer whose role allows changing a session status by hand, in the dashboard. Your system reads the status again afterwards.

Re-authentication before payments and withdrawals

The job

A customer opened an account weeks ago and passed the checks on the day. Today a request arrives to withdraw to a destination that has never been used, or to change the beneficiary, or to send an amount larger than any before. The earlier verification says who the account belongs to. It cannot say who is asking now. A check at the moment of risk can show that a live person is there now: a fresh selfie with liveness. Where your flow adds the comparison with a stored reference face, it can also show that this is the person you know.

This page is about the returning customer and the single operation that is being protected. The check of a person before a large amount is released, with AML screening, is described on the page for high-value payments and payouts. Use that page for the screening side, and this one for the step-up.

Which operations to protect

The list is yours, and it should be short. Typical entries:

A withdrawal to a destination the customer has not used before.
A change of beneficiary or payout details.
A payment above a threshold that your risk team sets.
The first payment after a change of email address or phone number. See account takeover re-authentication.

A check that fires on every small payment is friction without a gain. Put it where a thief would take the value.

Tie the check to the operation

Three rules keep an old result from approving a new action.

One session for each operation. Start a new verification session when the operation arrives. Do not reuse the session of the sign-up, or of an earlier payment.
A client key that names the operation. The client key is your own identifier. The documentation suggests a combination such as user and application when the check belongs to an application, an order or a contract, and the raw value is at most 36 characters. Use an opaque identifier of your own that combines the account and the operation, never a name or an email address. See working with clientKey.
A short lifetime. The session lifetime is a setting of the scenario, from minutes up to a year. For a check that protects a single operation, choose minutes. A session that nobody finishes reports expired, and the operation stays held.

If you open the widget with the stickySession option, the widget remembers the client key in the browser for 15 minutes and resumes the previous session when the user reopens within that time. That is helpful for a user who closed the tab by mistake, and wrong for a new operation. Leave the option off for operation checks. See installation.

The flow

The request. The customer asks for the withdrawal, the change or the payment. Your system recognises a protected operation and holds it.
The session. Your server encrypts the operation client key and your page opens the widget for the re-authentication scenario. If the customer is at a computer, a QR code moves them to a phone. See QR hand-off.
The check. The customer takes a selfie and moves the face closer through two ovals. See liveness.
The comparison. A returning user is compared with a stored reference face. The scenario settings include a required face match with a reference session. The set-up of the reference for your flow is agreed with the team, so talk to us before you rely on this step.
The result. A webhook tells your server that the session is complete, and your server reads the status of that session by its client key. See webhooks and session status.
The release. Your system releases the operation, keeps it held, or sends it to a reviewer.

The decision

Read the session on your server. Do not decide from the callbacks of the widget, which run in the browser of the user.

One release rule applies to every path. An operation is released only when all of the following hold at the same time:

The session status is success, and the status of the liveness step is success.
The latest outcome.class of the liveness step is success. Only if your policy for this amount allows it, a latest class of unverified on a step whose status is success is accepted instead.
The required reference comparison passed. Read it from faceReference.reason of the session: matched is the passing value, and mismatch is the failing verdict. Every other reason, and a missing faceReference block, means the faces were not compared, which is not a pass and does not mean a different person. Do not decide from a boolean alone.

Everything else is a hold or a refusal. A table row that does not meet all three conditions never releases.

What your server reads	What happens to the operation
Session `success`, the liveness step `success`, latest `outcome.class` of `success`, and `faceReference.reason` of `matched`	Release it.
The same, but the latest `outcome.class` is `unverified` (the attempt passed without the verifying services)	Release it only if your policy for this amount allows an unverified pass. Otherwise hold it for a reviewer.
Session `success`, but `faceReference.reason` is `mismatch`	Hold it and send it to a reviewer, or refuse it.
Session `success`, but `faceReference.reason` is any other value, or the block is missing	The faces were not compared. Hold it. Fix the reference set-up with the team, or offer another route.
`outcome.class` of `verdict`	The attempt was refused on a judgement about the person and is spent. Keep it held and send it to a reviewer.
`outcome.class` of `technical`	The machinery failed and the attempt is given back. Offer another attempt.
`outcome.class` of `exhausted`, or `triesLeft` of zero	The step is over. Keep it held, and refuse it or offer another route.
`failed`	Keep it held. Offer another attempt if your policy allows it, or refuse it.
`suspicious`	Hold it for a reviewer.
`expired` or `exception`	Keep it held. Offer a fresh session.

A reviewer can change a session status by hand, so a status of success that a person set is not the same as a machine result. Release on the liveness step and the reference reason as read above, and record a manual decision as a decision of that person.

When a person decides

Some held operations need a human. A reviewer opens the session in the dashboard, looks at the selfie, the faces result and the liveness result, and changes the status by hand after a confirmation. The same change is available to your tooling through the status change method. Only roles with that permission can do it, and the dashboard keeps a log of who signed in. See access rights.

Your system should read the status again after the reviewer acts. This page does not assume that a manual change sends a webhook. Keep the status that the platform gave and your own decision in separate fields, so that the record shows both.

Scenario setup

In the scenario editor build a lean scenario for the step-up: the selfie step and the liveness step, a short session lifetime, and the callback to your server. That scenario does not by itself compare the user with an earlier face. If you want the comparison, agree the reference set-up with the team first. Add repeat-user search and your blocklists if you want the face checked against them in the same flow. See face search.

What your system receives

A session status and a list of results for each step, including a liveness entry. See session statuses.

Talk to us about the operations that your risk team wants to protect, or look at the selfie and liveness screens in the interactive tour.