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.

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.

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:

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

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

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.

curl
-H "Authorization: Bearer {access_token}"
-X PATCH  -H "Content-Type: application/json"
-d '{
  "user_metadata":"wepay_account_id":"{wepay-merchant-account-id}"
}'

Direct Users To The Merchant Center

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.