Overview

The /agent_sso endpoint is the simplest method for accessing the Business Portal via SSO. For security considerations, PayNearMe limits agents who access the Business Portal this way to a specific subset of roles, which are listed below. Agents that require more roles than those listed below will need to log into their Agent Interface account using their email and password credentials.

Role	Description
Cannot Cancel Payments	Prevents agents from cancelling processed payments in the Agent Interface.
No ACH Entry	Prevents agents from making ACH payments in the Agent Interface.
Agent Interface	Gives the user access to the Agent Interface where he/she can view customer and payment data. NOTE: All merchant users should have access to the Agent Interface.
No Card Entry	Prevents agents from making card payments in the Agent Interface.
Agent Cannot Edit	Prevents agents from editing the settings of the Agent Interface.
Agent Interface Electronic Payments	Grants the ability to process an electronic payment within the Agent Interface.
Refund Electronic Payments	Grants the ability to initiate a partial or full refund for an electronic payment.
Supervisor	Provides ability to override merchant business rules. For example, if there is a minimum payment requirement set by a business rule, then a supervisor would be able to override this restriction and process the payment.
Schedule Autopay	Grants the ability to set a recurring autopay schedule in the Agent Interface.
Cancel Autopay	Grants the ability to cancel a recurring autopay schedule.
Waive Fees	Grants the ability to waive fees.
Beta Features	Provides access to various beta features.
Communicate	Provides access to the Communications feature where agents can send email or text messages to consumers.
View Orders	Grants agents the ability to view consumer orders.
Edit Orders	Grants agents the ability to edit consumer orders.
View Payments	Provides agents access to the Payments page where they can search for and view consumer payments.

After your PayNearMe TAM has configured your site and users to allow for Agent SSO Token Authentication, you can begin submitting calls to the /agent_sso endpoint. The call returns an authenticating token and the SSO URL where the agent can access the Business Portal and/or the specific order.

📘
API Version
Agent SSO functionality can only be used with the version 3.0+ API keys.

Required Parameters

Use the with the following parameters when making an /agent_sso call:

Parameter	Description	Data Type	Required?
`agent_email`	Email address for the agent. NOTE: Agents must use a unique email address for SSO when accessing the Business Portal. The SSO email address cannot match the one used for logging into their Business Portal account.	string	R
`agent_name`	The name of the agent	string	R
`agent_role`	The role set for this agent	string	R
`site_identifier`	Your site identifier	string	R
`order_identifier`	One of the following order identifiers, which can be used to locate the order after the agent authenticates into the Business Portal: `pnm_order_identifier` `site_order_identifier` `site_customer_identifier`	string	O

Optional Deep Link Parameters

To have the agent land in a specific workflow after signing in, add the following optional parameters to your call.

Parameter	Description	Data Type	Required?
`deep_link`	The workflow to open on the order. Values: `take_payment`, `schedule_autopay`, `refund`, `cancel_future_payment`, `deactivate_autopay`.	string	O
`payment_identifier`	The payment to refund. Required when `deep_link` is `refund`.	string	C
`schedule_identifier`	The scheduled payment or Autopay schedule to act on. Required when `deep_link` is `cancel_future_payment` or `deactivate_autopay`.	string	C

R = required, O = optional, C = conditionally required.

📘
Enabling Targeted Deep Links
Targeted deep links are off by default. Contact your PayNearMe TAM to enable them for your site. For workflow details, behavior when a link cannot open a workflow, and examples, see Using Targeted Deep Links.

Request URLs

Use the following request URLs when making calls.

⚠️
Sandbox vs. Production
The examples provided below are from the Sandbox environment. When moving to Production, you will need to generate a production secret key.

Environment	URL
Sandbox	https://api.paynearme-sandbox.com/json-api/agent_sso
Production	https://api.paynearme.com/json-api/agent_sso

Example Token Requests

Grant Access to the Business Portal

curl -X POST http://dev.paynearme.com:3000/json-api/agent_sso -L \
     -d agent_email=tracey.monroe%2Bamssso%40paynearme.com \
     -d agent_name=Tracey+Monroe \
     -d agent_role=agent \
     -d site_identifier=S5101017669 \
     -d version=3.0 \
     -d timestamp=1679423146 \
     -d signature=603c1db682057596a8d9f21a40fa34c48decaa166a2998ecdd7422cb342efe5e

{
   "status": "ok",
   "token": "Sklb-GelNo-mVwaEgZxkXI-uWc0oFRgOZxScNVEEePA",
   "token_expires": "2023-03-21 11:26:46 -0700",
   "sso_url": "https://pro.paynearme-sandbox.com/single_sign_on/Sklb-GelNo-mVwaEgZxkXI-uWc0oFRgOZxScNVEEePA"
 }

Grant Access to the Business Portal and the Order

curl -X POST http://dev.paynearme.com:3000/json-api/agent_sso -L \
     -d agent_email=tracey.monroe%2Bamssso%40paynearme.com \
     -d agent_name=Tracey+Monroe \
     -d agent_role=agent \
     -d order_identifier=0000001462-1A431845 \
     -d site_identifier=S5101017669 \
     -d version=3.0 \
     -d timestamp=1679423246 \
     -d signature=3c4fdb8073f6e40ced2b223460ed9d6f710ec6ea3e42618001acb79f77d87092

{
  "status": "ok",
  "token": "4kxcNJa52tsA99HfuQi6oHqiJp4_CP2KxM_aFg0diU8",
  "token_expires": "2023-03-21 11:28:26 -0700", 
  "sso_url": "https://pro.paynearme-sandbox.com/single_sign_on/4kxcNJa52tsA99HfuQi6oHqiJp4_CP2KxM_aFg0diU8?RelayState=0000001462-1A431845" 
 }

Grant Access to a Specific Workflow

curl -X POST https://api.paynearme-sandbox.com/json-api/agent_sso -L \
     -d agent_email=tracey.monroe%2Bamssso%40paynearme.com \
     -d agent_name=Tracey+Monroe \
     -d agent_role=agent \
     -d order_identifier=0000001462-1A431845 \
     -d deep_link=schedule_autopay \
     -d site_identifier=S5101017669 \
     -d version=3.0 \
     -d timestamp=1679423346 \
     -d signature=SIGNATURE

{
  "status": "ok",
  "token": "4kxcNJa52tsA99HfuQi6oHqiJp4_CP2KxM_aFg0diU8",
  "token_expires": "2023-03-21 11:30:06 -0700",
  "sso_url": "https://pro.paynearme-sandbox.com/single_sign_on/4kxcNJa52tsA99HfuQi6oHqiJp4_CP2KxM_aFg0diU8?RelayState=0000001462-1A431845&deep_link=schedule_autopay"
}