Using SSO with the API
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 |
|---|---|
| Restricted Cannot Cancel Payments | Prevents agents from cancelling processed payments in the Agent Interface. |
| Restricted 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. |
| Restricted No Card Entry | Prevents agents from making card payments in the Agent Interface. |
| Restricted No Agent Interface 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:
| string | O |
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"
}
Updated 5 months ago