Multifactor Authentication

WePay’s MFA API makes it easy for partners to:

Dramatically increase security of payment operations.
Integrate setup of MFA into a platform’s own user experience via APIs.
Protect payment operations both executed via APIs on their own platform and on WePay.com.
Leverage WePay’s MFA to protect as much of a platform’s other operations as desired.

Why MFA is important

Multifactor authentication is a defense against Account Take Over (ATO) fraud. Despite the best efforts of WePay and partners, some users are not careful enough with password management. Those users run the risk of falling victim to social engineering, phishing sites, etc. The second factor of authentication requires users to have something they hold (a phone or physical code sheet) in addition to something they know (their password). MFA virtually eliminates the risk of ATO by requiring two factors of authentication.

Waiting until a user wants to withdraw money may be too late to prevent ATO fraud. The only way to ensure security is to establish a second factor before any payments have been processed. The ideal opportunity for this is during a user’s initial account setup on a partner platform. WePay provides APIs that let a partner integrate MFA setup into their platform’s existing user experience (UX). In doing so, partners can control the timing and the experience as needed without sacrificing security.

How It Works - User Perspective

User Provides A Second Factor

As part of the account setup process on a partner platform, the user is asked to provide a means of second factor authentication – something they hold. WePay supports:

Text messages.
Voice calls (reads a code to a phone).
The Google Authenticator app.

WePay also supports a single physical code sheet that may be printed once to be kept as a backup.

User Confirms Their Factor

The user receives a challenge to confirm their selected factor. Once a factor is confirmed, the user indicates if the device they are using should now be trusted for the next 30 days.

Additional Challenges

If a user attempts to log on from an unrecognized device or after the 30 day trust period has expired, WePay will challenge the user upon login. In addition to the login challenge, partners should use the MFA APIs to test the MFA status before using any sensitive APIs (such as changing the financial owner) and challenge the user if appropriate.

Caution

Because platforms and WePay operate in separate domains, each domain has its own 30 day trust period. However, the vast majority of user flows would only require a user to be challenged once or twice in their lifetime of using WePay.

How It Works - System Perspective

WePay’s MFA service guards:

Access to WePay.com
Access to the partner platform (A partner has the choice to only use MFA to guard WePay’s most sensitive operations (see below) when accessed on-site via API or to integrate MFA into partner login to cover the partner’s entire site)

There are two components to the MFA system:

Factors: Methods that a user canuse to confirm their identity.
Devices: Those that have been confirmed as owned by the user. A device can optionally be trusted for 30 days.

The MFA APIs allow platforms to let users select from available factors to establish trust on a device. The APIs also allow users to create and delete factors.

Trusted devices are tracked by cookies. The MFA API provides a cookie upon confirming a user via one of that user’s MFA methods. Platforms store these cookies in the user’s browser, making that browser a trusted device.

Testing A Device

Anytime a partner wants to test to see if a request is still from a trusted device, just take the trusted device cookie and verify it with the MFA API. If there is no cookie or it does not validate, use the /user/mfa/send_challenge API call to challenge the user using their preferred (or alternate) MFA factor, obtain their code, and pass that to WePay to validate.

WePay gives partners a great deal of flexibility as far as when test a device must be tested. At a minimum, partners need to test before making any sensitive API calls such as changing the current financial owner of an account.

Trusting Devices

Users have 2 options when confirming a challenge:

Trust this device: The cookie is stored persistently and is good for 30 days
Don’t trust: The cookie is stored as part of a browser’s session, and is good until the browser is closed, or after 10 minutes, whichever occurs first.

Sensitive Operations

The following operations can directly lead to redirecting money. Partners should always test the current device for trust before making these API calls:

Changing financial owner using the Membership APIs
Adding a new MFA factor

Typical Flow

This section presents a typical sequence of events for signing up, and later completing KYC and bank account info.

Sign up on a partner site:
- Create a user using /user/register or /oAuth.
- Create a merchant account using /account/create
Set up MFA. This should happen before any action that could lead to a checkout, and it can be done before sending a confirmation email and establishing a WePay password:
- Check if this user already has MFA with /user/mfa/find.
- If user is new to WePay, set up MFA using /user/mfa/create.
- Challenge the user to ensure they actually control this factor using /user/mfa/send_challenge.
- Confirm code and the ask user if their device should be trusted for 30 days with /user/mfa/confirm.
Complete setup:
- Send a confirmation email with /user/send_confirmation.
- The user clicks through and sets their password on WePay.
- WePay challenges the user for MFA.
- The user completes KYC and bank account setup.
- The user returns to partner site.
Reconfirm after 30 days or before executing sensitive operations:
- Test the user’s cookie, and /user/mfa/validate_cookie returns invalid.
- Get a list of available MFA factors from /user/mfa/find.
- Proactively send the default challenge /user/mfa/send_default_challenge.
- Display a UX that allows user to enter the code and also shows alternate methods from /user/mfa/find. If the user clicks on an alternate, issue that challenge with /user/mfa/send_challenge using the requested mfa_id. Otherwise, test the code entered by the user via /user/mfa/confirm.
- Save the trusted device cookie in the user’s browser.