Some actions need the customer to confirm it’s really them, even though they’re already signed in: adding or re-enabling a payee, an ad-hoc international payment, submitting a batch, raising a limit, inviting a sub-user, viewing secure card details. Each of these takes a confirmation object in its request body. Every route uses the same object and the same refusal codes. Who must confirm is the same everywhere except secure card details.

The confirmation object

Send exactly one method:
  • Passkey. Get a passkeySession and fido2options from the step-up passkey challenge, run navigator.credentials.get() (or the native equivalent) and send the result as assertion, a JSON string with base64url fields. See Passkey step-up for SSO for the device side.
  • Authenticator code. The current code from the user’s authenticator app, plus the user’s access token from the same sign-in. Send the access token here even if your program uses the ID token as the Authorization: Bearer token: the code is checked against the access token, and an ID token here is refused (SCA_EXPIRED).
  • PIN. Request one first with Request a security PIN. It’s texted to the phone number on the signed-in user’s application.

Who must confirm

Secure card details

View secure card details (POST .../cards/{cardId}/secure) always needs a confirmation, SSO sessions included: a passkey on a program that requires passkey step-up for SSO, any method otherwise. Only the sandbox demo account may leave it out.

How long each proof lasts

Request the challenge or the PIN when the customer acts, not when the screen loads.

When a confirmation is refused

A refused confirmation is always 422, with a code that says why:
Branch on code, never on message: the wording can change.

By method

Other statuses

  • 400 VALIDATION_ERROR: the confirmation object is malformed or incomplete, for example totp without accessToken. Fix the request; asking the customer again won’t help.
  • 401 and 403 are never a refused confirmation. A missing Authorization header is a 401; an expired or invalid bearer token is a 403 ({"message":"Forbidden"}, no code). Refresh the token once and resend: the confirmation in the body isn’t the reason, so it doesn’t need a new proof. If it’s still 403 with a fresh token, the caller isn’t allowed to do this; don’t retry again.
  • 500: the check itself failed, for example because our identity provider is down or rate-limiting us. It says nothing about the customer’s code or passkey. Don’t tell the customer their code was wrong; ask them to try again shortly.
Earlier, some routes answered a refused confirmation with 400 (VALIDATION_ERROR, for a wrong PIN or code), 401 (an expired passkey session) or 500. Batch payments answered INVALID_TOTP. All of these are now 422 with the codes above.