API
Log In Support
  • Clear

    • Get Started

      • Overview

      • Platform Sign Up

      • API Basics

    • Integration

      • Setup Platform

      • Onboard Merchants

      • Enable Merchants

      • Process Payments

      • Payout Merchants

      • Manage Payment Operations

      • Test and Launch

  • Link

    • Get Started

      • Overview

      • Platform Sign Up

      • API Basics

    • Integration

      • Setup Platform

      • Onboard Merchants

      • Process Payments

      • Manage Payment Operations

      • Test and Launch

    • CARD PRESENT SOLUTIONS

      • Get Started

        • Overview

      • Terminals

        • Acquire Terminals

        • Onboard Terminals

        • Authorize Cards

        • Process Payments

        • Test and Launch

      • Mobile Card Readers

        • Build Mobile App Prerequisites

        • Acquire Mobile Card Readers

        • Pair A Device

        • Authorize Cards

        • Process Payments

        • Test and Launch

      • Card Present Resources

        • Provide Receipts

    • API Reference

    • Resources

      • Payment Life Cycles

      • Server to Server Integration

      • Platform Legal Certification

      • Security Certification

      • Risk Certification

      • CIP and KYC Certification

      • Card Network Rules

      • Disputes Deep Dive

    • Cookbooks

      • Build Payment Support Tools

      • Reporting

      • Implement Merchant IC+ Pricing Model

      • Recurring Billing

      • Level 2 & Level 3 Processing

      • Style Credit Card iFrames

      • Support Merchants Outside the United States

      • Connect Merchants With SSO

      • Design A Retry Strategy

    • Release Notes

Home / Cookbooks / Connect Merchants With SSO

 

Connect Merchants With SSO

In This Section
  • Set Up Identity Management
  • Integrate Your IdM With WePay
  • Onboard A Merchant
  • Direct Users To The Merchant Center

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.

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.

Partner Center IdM Fields


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

Important

There may be a 3-5 second delay between calling POST /accounts 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}"
}'

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 WePay authorizes users

Step 1:

WePay constructs 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
WePay expects your IdM to use the redirect URI present in the GET request and then WePay will use the token request.

Step 2:

After your IdM reaches the redirect URI, WePay 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 token response should look like this:
{
  "access_token": "{access-token}",
  "token_type": "Bearer",
  "refresh_token": "{refresh-token}",
  "expires_in": 3600,
  "id_token": "{encoded-id-token}"
}
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.
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, WePay 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

 


Questions? Need help? Visit our support page!

Company

  • About
  • Careers
  • Blog
  • News & Events

Resources

  • Knowledge Center
  • Terms of Service
  • Privacy Policy
  • Security
  • Support

Developers

  • Documentation
  • Engineering Blog

Customers

  • Case Studies

Product

  • Link
  • Clear
  • Core
  • Contact Sales
© 2020 WePay Inc.