Connect Merchants With SSO

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.

WePay’s 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). WePay recommends 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 WePay.

In addition to standard claims (discussed below), you’ll need to create a custom claim in the OpenID ID token and follow WePay’s 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}”). WePay recommends 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:

1. Use the auth0 rule feature to add properties under user_metadata into the ID token’s claim

2. Log in to Auth0 dashboard -> Rules -> Create Rule -> Empty rule

3. Add the below JavaScript code snippet to the new empty rule:

   context.idToken["https://{platform_domain}/wepay_account_id"] = user.user_metadata.wepay_account_id;
   

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 WePay 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 WePay in the Partner Center.

Onboard A Merchant

WePay requires 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 (read more about identifying a controller here)
• 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 'Accept: application/json'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --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}"
    }
  }'

The API response will include the Legal Entity’s 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 'Accept: application/json'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "legal_entity": "{id-value-from-previous-step}",
  "name": "{input-from-user}",
  "description": "{input-from-user}"
  }'

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}"
}'

For additional users who should access the Account in the Merchant Center, repeat the above process with that same 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. Use https://home.wepay.com/sso/oidc/{app_id} as the CTA URL.

{
  "access_token": "{access-token}",
  "token_type": "Bearer",
  "refresh_token": "{refresh-token}",
  "expires_in": 3600,
  "id_token": "{encoded-id-token}"
}

If the Merchant Center loads with the error page, WePay 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.

Questions? Need help? Visit our support page!