This document describes how to integrate an application with WePay so that the application’s own user management system is used for services at WePay, instead of a separate WePay login and password. We call this Single Sign On (SSO) since there is only one set of user credentials: the partner’s application.
Permission required: Please get in touch with your WePay account manager to use this API, or to learn more about WePay’s SSO feature.
WePay’s SSO feature provides 3 key benefits to platforms:
- Simplifies merchant onboarding, removing the need for merchants to verify an email and set a password
- Streamlines integration of WePay.com abilities into your own platform, making them one-click away
- Creates an isolated set of users that are unrelated to any other users from any other platform
Of course, taking on SSO is a significant responsibility. A merchant account involves real money, and with SSO a platform’s own login security is the only defense against hackers taking over an account. That’s why using SSO requires engagement with WePay.
Integrating WePay’s SSO involves these steps:
- Understanding the security implications
- Ensuring your platform can guide users to WePay.com
- Declaring a user will be managed using SSO
- Enabling a user to actually log in to WePay using SSO
- Supporting a redirect from WePay when users come to WePay without coming directly from the partner (e.g. from a form linked from an email WePay sends)
A merchant account should be thought of like a bank account, and so the access it should be guarded the way a bank would. While some platforms already have strong security, others have never had the need. You should consider:
- Password requirements: does your platform require strong passwords?
- Multi-factor authentication (MFA): does your platform use MFA or other techniques to add security beyond passwords?
- Password reset process: How easily could a hacker fake out your password reset process? What if a user has the same password on your site as they use for their web email account?
- Internal security: do your support reps have the ability to “impersonate” users? If so, what would stop them from using SSO to access or change bank transfer information on a user’s merchant account?
These are just some of the things to consider. WePay will review your account security procedures as part of integrating SSO. WePay will generally require your platform to provide MFA, either using WePay’s MFA service or your own.
WePay will require a signed agreement indemnifying WePay from loss due to account take over.
Guiding merchants to WePay.com
Once a merchant is activated for SSO, they can no longer come directly to WePay.com and log in. All access to the WePay merchant center has to originate from within your platform.
At a minimum, your platform will need to host a link or button that will initiate the SSO handshake and then redirect merchants to WePay.com with a SSO token. Consider how your support team will guide merchants to WePay.com and make sure this link to WePay is somewhere they can easily explain.
Settting up merchants to use SSO
Merchants are designated as SSO users when they are created via /user/register. It is not currently possible to change an existing non-SSO user into an SSO user.
WePay requires email addresses to be verified. Platforms using SSO typically handle email verification themselves. WePay can optionally provide an email verification challenge service if a platform is unable to do this itself.
If your platform uses SSO and handles email verification, then merchant setup can be completely seamless:
- There is no WePay email to be confirmed
- The access token is permanent and active from the beginning
Logging a merchant in to WePay.com
The high-level process for performing a SSO login to WePay is:
- Platform rquests a SSO token from WePay: /user/request_sso_token
- Platform signs the token (details in the reference section later in this doc)
- Platform redirects user to WePay’s SSO endpoint, providing the token, signed version of the token, client ID, destination URL on WePay.com
If users come directly to WePay.com, for example, via a link embeded in an email WePay sent, WePay will redirect to a partner-supplied URL. That URL then goes thru the SSO process outlined above.
Global users vs SSO silo’d users
WePay’s default user management is a global space for all partners. If partner-1 and partner-2 both make /user/register calls for a merchant with email address email@example.com, then both partners are sharing the same user object. There will be a single password, and when Joe logs into WePay.com, they will see the accounts from both partners.
If partner-3 makes a /user/register for firstname.lastname@example.org, but uses SSO, then this is a different user object with its own password. When Joe logs in (via partner-3) to WePay.com, Joe will only see accounts from partner-3. Joe can still login directly to WePay.com, using the global password setup via partner 1 & 2.
Creating SSO users
In /user/register, use the
type parameter with the value
sso to create a user as an SSO user.
Verifying email addresses
WePay requires that email addresses be verified. Normally SSO partners do this, but WePay offers a verification service you would rather not have your platform do this.
Note: if your platform originally onboarded users without email verification, but are adding it now as part of your integration with WePay, you will generally need to verify those existing users. You can discuss your setup with WePay to see if an alternate verification mechanism can be used.
If your platform incorporates email verification, then use /user/mark_email_verified to indicate that verification has been done. A user will be moved to state
registered at that point. Your platform can do this at any time after calling /user/register/, and would typically do it immediately after the /user/register call. Your platform must do this within 14 days of the first transaction or 90 days from the time of the /user/register call or the account can be disabled.
If your platform would like to use WePay’s verification service, then use /user/send_confirmation to have WePay send an email to the email address provided in /user/register. The email will ask users to click on a button. When users do this, they will see a message saying thank you - there is no action a user needs to take at that point. The user will move to state registered and your platform will receive an IPN. Your platform can call /user/send_confirmation multiple times, e.g. if a user has lost their email.
Logging users into WePay via SSO
How it works
Logging in via SSO uses these steps:
- Your platform requests an SSO token from WePay - a normal server-to-server API call
- WePay responds with an SSO token
- Your platform signs the token, then redirects the user to WePay’s SSO entry URL, passing along the signed token, the destination, and other info.
WePay’s SSO entry URL will validate all the info, and if successful, create a logged-in user session that works exactly the same as a non-SSO user that had just logged in to WePay. The user can browse around WePay.com without further interaction with your platform as long as their session is valid. Standard idle-timeout policies apply (see below.)
About SSO tokens
Applications obtain SSO tokens from WePay to tell WePay that a user is currently authenticated by the application and WePay should consider them logged-in as well. An SSO token is NOT an access token. SSO tokens:
- Allow only one-time use
Must be used within 10 minutes of being issued
- It is important that your platform clocks are set to the correct time
- Must be signed by the application via the provided SDK so WePay servers know they were sent from the application
Getting an SSO token
Use /user/request_sso_token to request a token. The token must be presented to WePay within 10 minutes.
Note: your platform should always request a new SSO token every time they want to send a user to WePay.com. If the user already has an active session, the new SSO token will still work.
Signing an SSO token
For additional security over the open internet, your platform needs to sign the token received from WePay. The inputs to the token signing process are:
- The token returned from /user/request_sso_token
- The platform’s client ID (can be found logging in as a platform owner to WePay.com)
- THe platform’s client secret (can be found logging in as a platform owner to WePay.com). As always, use care in managing this value.
- Page URI: the URL on WePay.com your platform wants the user to visit
- Redirect URI: the URL on your platform that WePay should return users to when they log out of WePay
WePay provides sample code that illustrates how the signing algorithm works.
Redirecting users to WePay
Once your platform has a signed token, it is ready to redirect the user to WePay.com. Send the user to
and provide the following query string parameters:
- token: the original token
- stoken: the signed token
- client_id: your platform’s client ID
- page: the URL on WePay.com that your platform wants the user to visit
- redirect_uri: the URL on your platform that WePay should return users to when they log out of WePay
WePay provides sample code that will correctly generate a query string.
WePay will validate the signed token against the supplied parameters, and if valid:
- Create a logged-in session for this user
- Redirect the user to the specified page
The user is free to navigate around WePay.com like any non-SSO user.
If there are any errors, as a security precaution, the user will be redirected to the platform’s configured URL, and not to the supplied
WePay needs to initiate login
SSO users cannot come on their own to WePay.com and log in. They must originate from your platform. However, there are cases when WePay sends an email and that email contains a link to a part of WePay.com that requires login. In this case, WePay needs a way to send users to your platform to get logged in and returned to WePay.
WePay requires partners to have a URL that can accept these query string arguments:
- wepay_user_id: the WePay user ID that needs to be logged in
- redirect_uri: the URL on WePay.com that WePay wants the user to be sent to after they are logged in on your platform
The URL supporting this login must be configured by WePay as part of your integration.
When WePay sends users to this URL on your platform, it should:
- Log the user in to your platform (if necessary)
- Initiate the SSO process described above, using the redirect_uri as the destination page
An example of the URL WePay will call is:
If your platform is using WePay’s hosted MFA service, SSO does not change the MFA requirements. If a MFA user is redirected to WePay.com, and the device does not have a trust cookie, they will be challenged by WePay for their MFA code.
Logging out of WePay
There are three ways a user can be logged out of WePay.com:
- Explicitly, by using the signout link on WePay.com
- Implicitly, by being inactive too long (currently 10 minutes)
- Forced by the platform
In the first two cases, WePay will redirect the user to the redir_uri provided when the SSO session was established.
The third case is when your platform decides to log a user out (by request, by timeout, etc.) Your platform should call /user/logout to ensure WePay also cancels any active sessions on WePay.com.
There are some cases where WePay’s API already contains a redirect URI parameter, because with or without SSO, there is a natural end to the user experience at WePay and it makes sense to return users to the platform’s site. The API redirect parameter will be used at the end of the flow. However, if the user times out during the flow, the SSO redirect will be used as for any other timeout.
/account/get_update_uri is used by platforms to guide users thru KYC and settlement using iframes within the platform’s page. KYC and settlement requires login. A typical sequence for SSO partners is:
- /account/get_update_uri to get the iframe URL - passing in the desired
redirect_uriWePay should use at the end of KYC and settlement
- Go thru the standard SSO handshake, giving the iframe URL received above as the page argument, and supplying a
redirect_urito be used if the user times out before finishing.
Although /user/register contains a
redirect_uri, for SSO it is effectively not used. The only time there is any user interaction is if a partner is using WePay to verify email addresses. Even in that scenario, there is no practical way for a user to time out.
Changing a user’s email address
WePay does not currently allow changes via API in a user’s email address for non-SSO users.
For SSO users, use the call /user/change_email.
Note: This is a high-security call. If your platform is using WePay’s hosted MFA service, you will be required to prove current MFA status by passing the trust cookie to the call. If your platform is providing its own MFA service, then WePay will allow this call without a trust cookie.