Connect Merchants With SSO
BETA
SSO is in BETA, and this documentation is subject to change. BETA participants have already been selected, and access to SSO will require permission once this feature is generally available.
Rather than building out your own tools for your merchants to manage their payment operations, implement SSO to provide a seamless transition from your own user experience to the WePay Merchant Center. Once you have arranged access to SSO with your WePay team, you can begin following this implementation guide.
Our SSO integration leverages OpenID Connect's identity layer built off of the OAuth2.0 protocol.Set Up Identity Management
You'll need an identity manager (IdM). We recommend auth0 or Keycloak if you don't already have one. If you decide to use a different IdM or to build your own, the solution must support OpenID Connect and custom claims, and your WePay integration team must approve it for use. A list of requirements for an IdM solution you decide to build yourself, should you choose to, is currently being developed and will be published here once complete.
Access your IdM account and generate credentials that will only be used for and shared with us.
In addition to standard claims, you'll need to create a custom claim in the OpenID ID token and follow our claim creation convention to prevent claim collisions. Custom claims must include HTTPS, a domain, and a key-value pair to define WePay merchant Account IDs (i.e."https://platform_domain/wepay_account_id”: “account_id”
). We recommend using your own web application's domain for custom claims to enhance collision-avoidance. Note that the domain does not need to be reachable, but it should be unique to your platform.Here is an example custom claim flow with auth0:
- Use the auth0 rule feature to add properties under
user_metadata
into the ID token's claim - Log in to Auth0 dashboard -> Rules -> Create Rule -> Empty rule
- Add the below JavaScript code snippet to the new empty rule:
Integrate Your IdM With WePay
Once you're set up with your identity manager, collect the following items from them:
- Client ID
- Client secret
- Authorization endpoint
- Token endpoint
- Domain (must match domain used in custom claims)
- Logout URL (where we should direct merchants when they log out of the Merchant Center)
You'll be able to find all the above information (except the logout redirect URI) in your IdM account. The logout redirect URL should be whatever destination you want merchants to go back to on your platform after they log out of the WePay Merchant Center.
Submit that information to us in the Partner Center.
Onboard A Merchant
We require the following information about a financial admin user before they will be able to access the Merchant Center with SSO:
- WePay Legal Entity & Account IDs
- The business controller's email address, and indication that you have verified that email address
- User's electronic signature for ToS acceptance (read more about ToS acceptance here)
Step 1:
To satisfy the above, send a POST /legal_entities
request like this:
curl -X POST \
--url 'https://stage-api.wepay.com/legal_entities' \
-H 'App-Id: {your-WePay-app-id}'\
-H 'App-Token: {your-WePay-app-token}'\
-H 'Api-Version: 3.0'\
--data-raw '{
"country": "{input-from-user}",
"controller": {
"email": "{input-from-user}",
"email_is_verified": true
},
"terms_of_service": {
"acceptance_time": {UNIX-timestamp},
"original_ip": "{IP-of-the-user}"
}
}'
id
field and value. Step 2:
Immediately send a POST /accounts
request with the Legal Entity ID from step 1:
curl -X POST \
--url 'https://stage-api.wepay.com/accounts' \
-H 'App-Id: {your-WePay-app-id}'\
-H 'App-Token: {your-WePay-app-token}'\
-H 'Api-Version: 3.0'\
--data-raw '{
"legal_entity_id": "{id-value-from-previous-step}",
"name": "{input-from-user}",
"description": "{input-from-user}"
}'
Note
POST /account
and the WePay Merchant Center recognizing the returned Account ID. For this reason, we recommend creating the Legal Entity and Account upon platform account creation, before the merchant is able to click on your CTA to access the WePay Merchant Center.A Note on Users and Roles
- Financial Admin: Controller as defined in the Legal Entity. This is the only user who can fill out KYC and set Payout Method. There can only be one financial admin for each Legal Entity.
- Moderator: These users can see transaction and Account details. They are created by granting access in your IdM and tying them to the pre-existing Account ID in a custom claim.
The controller defined on the Legal Entity is the first user to be granted access to the Merchant Center via SSO for any merchant. The first user will have a financial admin role and will be able to fill in KYC and Payout information. Additional users (who the financial admin should designate) can be granted access in your IdM by tying them to the pre-existing Account ID. New Legal Entities and Accounts should not be created to grant non-controllers SSO access.
Step 3:
Associate the WePay Account ID with the user object in your IdM with your IdM's user endpoint.
Here's an example call to Auth0's/api/v2/users/id
endpoint to add the WePay Account ID as a custom claim in the user_metadata
.curl
-H "Authorization: Bearer {access_token}"
-X PATCH -H "Content-Type: application/json"
-d '{
"user_metadata":"wepay_account_id":"{wepay-merchant-account-id}"
}'
wepay-merchant-account-id
.Direct Users To The Merchant Center
Once you've specified the WePay Account ID on the user object with your IdM (step 3 in onboarding merchants), create a call to action (e.g. button) for your merchants to access the WePay Merchant Center. Usehttps://home.wepay.com/sso/oidc/app_id
as the CTA URL.Click for a detailed walk through of how we authorize users
Step 1:
We construct the GET request based on the information that you provided in the Partner Center. The GET request contains the following parameters:
Parameter | Value WePay will send |
---|---|
Client ID | Your client ID with your IdM that you provided in the Partner Center |
Scope | openid email profile |
State | Random string |
Response Type | code - Indicates to your IdM that they need to attach the code parameter to the Redirect URI |
Redirect URI | Merchant Center callback URI |
We expect your IdM to use the redirect URI present in the GET request and then we will use the token request.
Step 2:
After your IdM reaches the redirect URI, we will make a POST request to the token endpoint (provided earlier by you in the Partner Center). The POST request will contain the following JSON body parameters:
Parameter | Where WePay gets the value |
---|---|
Code | The URI parameter set by your IdM in the previous step |
Client ID | From the Partner Center |
Client secret | From the Partner Center |
Grant type | authorization_code |
Redirect URI | Merchant Center callback URI |
The decoded ID token must contain the following properties:
Parameter | Details |
---|---|
platform_url/wepay_account_id | The WePay Account ID associated with this user |
given_name | Current user's first name |
family_name | Current user's last name |
email | Current user's email address |
email_verified | This must be true, and your platform is responsible for user email address verification. Note that this is independent from the info provided to WePay through the Legal Entity API, and is rather managed by the IdM. |
iss | Issuer identifier - Identifies the Issuer of the response. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. |
sub | Subject identifier - A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case-sensitive string. |
aud | Audience identifier -- Identifies the audience(s) that this ID token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case-sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case-sensitive string. |
iat | Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
exp | Expiration time - On or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. |
Step 3:
If all the information received in the token response is correct, then the user will be logged into the Merchant Center.Read more about code flow steps here.
If the Merchant Center loads with the error page, we will return debugging information in the browser console:
Below is what the Merchant Center will look like on a successful connection. The "Mythical Partner" branding will be replaced with your own, and you can update the Merchant Center color theme.