Outside of the BillPay API resources, 3rd party single sign-on protocols are supported for the BillPay platform. This section defines the considerations and how to implement this functionality with BillPay.

Determine user account maintenance and login options

Merchants can use their own login page and SSO credentials to control both Merchant and Buyer user access to the BillPay Portal.

Merchants can also choose to use the BillPay Portal login page and give users the option to sign-in using a BillPay account OR their Merchant SSO account. This option is called mixed mode and is part of the BillPay single sign-on configuration settings.

If you enable mixed mode

Users will have the option to login using BillPay credentials or the Merchant SSO credentials.

When a user is created in BillPay or Merchant Portal (for Merchant BillPay user), he/she will receive a new user email to set the BillPay Portal password.

If email receipts are enabled, the user will receive an email receipt whenever making a payment.

If you do NOT enable mixed mode

Users will only be able to login to BillPay via the Merchant’s SSO site.

If a user is created in BillPay or Merchant Portal (for Merchant BillPay user access), he/she will NOT receive a new user email from BillPay as there is no need to set a password.

Even if email receipts are enabled, the user will NOT receive an email receipt when making a payment unless you maintain a Buyer user record in BillPay Portal via the API.

Note that regardless of whether you enable mixed mode or not, if users are maintained in BillPay Portal (for Buyer users) and Merchant Portal (for Merchant users), you only need to send the email address field when authenticating to the BillPay platform. This is because the user's profile in BillPay will have his/her permission and access information. If you are maintaining your own user accounts, then additional fields are required. This is further defined in the next section, "Implementing BillPay Single Sign-On".

Implementing BillPay single sign-on

The merchant must have an identity provider and BillPay-supported SSO protocol determined and in place. The identity provider supplies details on integrating the merchant's SSO functionality and how to obtain the identity token that will get passed to BillPay as part of the authentication.

As of this publication date, BillPay platform supports the following SSO protocols defined in the following table. Authentication varies slightly depending upon the protocol used. The following table also indicates which protocols require a certificate be provided to B2B Payments.

SSO protocol

Certificate required?

OpenID Connect

No

SAML 2.0

Yes

WS-Federation

Yes

You need to code your login page accordingly to send the appropriate user information to BillPay depending upon whether or not the user also has an account in BillPay in addition to the merchant SSO account.

BillPay AND Merchant SSO User Account: If the User account exists in BillPay, the merchant only needs to send the email address in the SSO call to the BillPay platform. His/her permissions are then controlled by the BillPay user account settings.

Merchant SSO Account ONLY: If the User does NOT have an account in BillPay and is using the merchant's SSO account ONLY, the merchant needs to provide additional information in the SSO call to the BillPay platform. The SSO request packet must include the following fields:

Field name

Description

Type

Either Buyer or Merchant

Email

User's email address

First Name

User's first name

Last Name

User's last name

Roles

An array of assigned permission roles

Either standard Admin, Reporting, or custom roles defined by the merchant in Merchant Portal

Buyers

An array of buyers the user can access. Use the buyerMerchRef value