This feature is being deprecated in the near future.
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 your own platform and on WePay.com
- Leverage WePay’s MFA to protect as much of a platform’s other operations as desired
Why is MFA important?
Multi-factor 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. These 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). By requiring these two factors of authentication, MFA virtually eliminates ATO risk.
Waiting until a user wants to withdraw money can be too late to prevent ATO fraud, so 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 UX. Thus, partners can control the timing and the experience as needed without giving up security.
How It Works - User Perspective
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 message
- Voice call (reads a code to a phone)
- Google Authenticator app
WePay also supports a single physical code sheet that may be printed once to be kept as a backup.
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.
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.
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 can use 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 a platform 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.
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 MFA API 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 when 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.
Users have 2 options when confirming a challenge:
- Trust this device: Cookie is stored persistently and is good for 30 days
- Don’t trust: 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.
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
- Changing a bank account
This section presents a typical sequence of events for signing up, and later completing KYC and bank account info.
- Sign up on partner site.
- Set up MFA. This should happen before any action that could lead to a checkout, and it can even be done before sending a confirmation email and establishing a WePay password.
- Complete setup
- Send confirmation email with /user/send_confirmation
- User clicks through and sets password on WePay.
- WePay challenges user for MFA.
- User completes KYC and bank account setup.
- User returns to partner site.
- Reconfirm after 30 days or before executing sensitive operations
- Test cookie, and /user/mfa/validate_cookie returns invalid.
- Get list of available MFA factors from /user/mfa/find
- Proactively send the default challenge. /user/mfa/send_default_challenge
- Display a UI 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.