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:

  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.

Partner Center IdM Fields


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:

Copy
Copied
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}"
    }
  }'
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:

Copy
Copied
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
There may be a 3-5 second delay between calling 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.
Copy
Copied
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.
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:
ParameterValue WePay will send
Client IDYour client ID with your IdM that you provided in the Partner Center
Scopeopenid email profile
StateRandom string
Response Typecode - Indicates to your IdM that they need to attach the code parameter to the Redirect URI
Redirect URIMerchant 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:
ParameterWhere WePay gets the value
CodeThe URI parameter set by your IdM in the previous step
Client IDFrom the Partner Center
Client secretFrom the Partner Center
Grant typeauthorization_code
Redirect URIMerchant Center callback URI
The token response should look like this:

The decoded ID token must contain the following properties:

ParameterDetails
platform_url/wepay_account_idThe WePay Account ID associated with this user
given_nameCurrent user's first name
family_nameCurrent user's last name
emailCurrent user's email address
email_verifiedThis 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.
issIssuer 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.
subSubject 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.
audAudience 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.
iatTime 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.
expExpiration 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.
Read more about the ID token spec here

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:

SSO Console Error

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.

SSO Merchant Center with Chase Branding