Step-up authentication

The revised Payment Service Directive, more commonly known as PSD2, outlines regulations to improve customer authentication processes that better protect customers from fraud.

PSD2 defines that strong customer authentication (SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).) via a two-factor authentication solution needs to be in place for when end-users are:

• Accessing their payment account information, as well as
• Initiating transactions

Using the Weavr API you can enroll your customers to different SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). options in line with PSD2 and step-up their authentication to perform certain operations.

Sandbox OTP code

In sandbox, no SMS is actually sent. Use 123456 as the verification code wherever an OTP is requested - both for factor enrolment (/authentication_factors/otp/SMS/verify) and for step-up challengesStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. (/stepup/challenges/otp/SMS/verify).

How to step-up a token

An active user can step-up their token by completing a second authentication factor. Weavr supports the following second factors:

• One-time password via SMS
• Embedded biometrics

Step-up a token using an OTP via SMS

A 6 digit one-time password is sent via text message on the end-user's registered mobile number. The one-time password needs to be submitted via the Weavr API to complete the step-up.

The following are the steps required to complete a step-up via an OTP sent via an SMS:

1. Initiate a challenge
2. Confirm the challenge

Device enrollment required

In order to complete challenge, the logged-in user must have enrolled their mobile device for strong customer authentication.

1. Initiate a challenge

You can trigger the step-up process by calling the step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. API. The user receives a text message (SMS) on the mobile number associated with their credentials.

The endpoint allows the end-user to re-send a new OTP up to one time, if the first step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. attempt was unsuccessful.

To be able to issue another step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations., you need to wait a minimum of 15 seconds from the first attempt.

Triggering the step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. API after 15 seconds from the first attempt invalidates the first challenge, and the user needs to respond to the new challenge.

• Triggering the step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. API within 15 seconds returns a 409 RETRY_IN_15SEC.

• The step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. can be retried once, after which a 400 INVALID_REQUEST is returned. The user has to logout and login again to issue a new step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations..

  If the end-user receives both the first SMS and the second one at the same time (e.g. a delay in telecom delivering the messages), only the more recent OTP works.

For root usersRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user., this is the mobile number provided when creating the corporate or consumer identity, while for authorized usersAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_., this is the mobile number provided when onboarding the user.

POST/stepup/challenges/otp/SMSTry it

Response

{
  "code": "string",
  "message": "string"
}

2. Verify the challenge

You must build a page in your app where the user can enter the verification code they received in the text message, then submit it through the challenge verify API.

Challenge expiry and attempts

The challenge expires after 5 minutes and the number of incorrect OTP attempts is limited to reduce the risk of fraud; the challenge remains in a Pending state until the last incorrect attempt has been consumed within the 5 minutes. A successful verification returns 204 No Content and steps up the user's current session, allowing access to the endpoints that require a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.. The 204 response is itself the confirmation — no payload, stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge., or expiry timestamp is returned, so clients should treat the successful HTTP status as the signal that step-up succeeded.

POST/stepup/challenges/otp/SMS/verifyTry it

Request

{
  "verificationCode": "string"
}

Response

{
  "code": "string",
  "message": "string"
}

Step-up a token using biometrics

The access token returned after a successful login via biometrics is already stepped up and gives you access to the endpoints listed below.

Re-enrollment requires un-enrollment first

Once a device has been enrolled for biometrics, it cannot be enrolled again, unless you un-enroll it first.

Actions requiring a stepped-up token

There are three levels of SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). for Payment Account Information which is being enforced depending on the endpoint being used.

Access to account details

The /managed_accounts and /managed_accounts/{id} endpoints only require the end-user to have enrolled and completed a two-factor authentication once.

Access to transaction details

Statement or transaction endpoints require the user to have completed a successful step-up in the last 180 days. If the active token is not stepped up, then only transactions executed in the last 180 days are returned. If transactions older than 180 days are required, the active token must be stepped-up.

Access to sensitive information

All card related operations require a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.. This includes viewing sensitive card information and updating the password or passcode of the end-user.

See the full list of endpoints and UI components requiring a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge. in the following tables.

Timing of two-factor authentication

You can control at which point the two-factor authentication is completed on the end-user, as long as a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge. is provided when calling the following endpoints.

Transaction verification doesn't count as SCA

Two-factor authentication done for the purpose of verifying a transaction does not count towards SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). for the purpose of payment account information.

Endpoints requiring a stepped-up token

Authorised users

Endpoint

Requirement

POST /users

Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.

Statements

Endpoint	Requirement
GET /managed_accounts/{id}/statement	Requires a step-up completed in the last 180 days
GET /managed_cards/{id}/statement	Requires a step-up completed in the last 180 days

Managed accounts

Endpoint	Requirement
GET, POST /managed_accounts	First-time access requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
GET, PATCH /managed_accounts/{id}	First-time access requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.

Managed cards

Endpoint	Requirement
GET, POST /managed_cards	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
GET, POST /managed_cards/{id}	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
POST /managed_cards/assign	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
PATCH /managed_cards/{id}	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
POST /managed_cards/{id}/physical	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
POST /managed_cards/{id}/physical/activate	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
GET /managed_cards/{id}/physical/pin	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
POST /managed_cards/{id}/physical/replace_lost_stolen	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
POST /managed_cards/{id}/physical/replace_damaged	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.

Transactions

Endpoint	Requirement
GET /sends	Requires a step-up completed in the last 180 days
GET /sends/{id}	Requires a step-up completed in the last 180 days
GET /transfers	Requires a step-up completed in the last 180 days
GET /transfers/{id}	Requires a step-up completed in the last 180 days
GET /outgoing_wire_transfers	Requires a step-up completed in the last 180 days
GET /outgoing_wire_transfers/{id}	Requires a step-up completed in the last 180 days

UI components requiring a stepped-up token

Authentication components

Component	Requirement
Password	Required when changing the password (first-time setup does not require step-up).
Passcode	Required when changing the passcode (first-time setup does not require step-up).

Card components

Component	Requirement
Card Number	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
Capture Card No PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
Show Card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.
CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component.	Requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge.

Error codes

Step-up endpoints — and any endpoint that requires a stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge. — can return the following error codes:

Code	Status	When	Meaning
STEP_UP_REQUIRED	403	Calling a step-up-protected endpoint with a token that has not been stepped up	The session needs to complete a step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. before this call succeeds. See Endpoints requiring a stepped-up token.
RETRY_IN_15SEC	409	Re-requesting an OTP step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. within 15 seconds of the previous attempt	Wait at least 15 seconds, then re-initiate the challenge.
INVALID_REQUEST	400	Re-requesting an OTP step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations. after the one allowed retry is exhausted	Log out and log back in to issue a new step-up challengeStep-up challenge A two-factor authentication challenge required to step-up a user's authentication token for Strong Customer Authentication (SCA) compliance. Users must complete a second authentication factor (such as OTP via SMS, push notification, or biometrics) to access sensitive information or initiate certain transactions as required by PSD2 regulations..