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
passkeySessionandfido2optionsfrom the step-up passkey challenge, runnavigator.credentials.get()(or the native equivalent) and send the result asassertion, 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: Bearertoken: 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 always422, with a code that says why:
Branch on
code, never on message: the wording can change.
By method
Other statuses
400 VALIDATION_ERROR: theconfirmationobject is malformed or incomplete, for exampletotpwithoutaccessToken. Fix the request; asking the customer again won’t help.401and403are never a refused confirmation. A missingAuthorizationheader is a401; an expired or invalid bearer token is a403({"message":"Forbidden"}, nocode). 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 still403with 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.