---
title: "POST /agent_sso"
method: POST
path: "/agent_sso"
tags: ["Agent SSO Token Authentication"]
---

# POST /agent_sso

`POST /agent_sso`

## Request

- Base URL: `https://api.paynearme-sandbox.com/json-api`
- URL: `https://api.paynearme-sandbox.com/json-api/agent_sso`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://login.paynearme.com/oauth/token`
  - API key in query parameter `signature`

After your PayNearMe Technical Account Manager has configured your site 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. Optional <code>deep_link</code> parameters can open a specific workflow on that order, such as a refund or an Autopay setup. Targeted deep links are off by default and must be enabled for your site by your PayNearMe Technical Account Manager (TAM).

## Request body

- AgentSso: Returns an authenticating token and SSO URL where an agent can access the Business Portal and/or a specific order. Optional deep-link parameters open a specific workflow on that order. Targeted deep links must be enabled for your site by your PayNearMe Technical Account Manager (TAM).
  - `site_identifier` string, required: Identifies your client site.
  - `timestamp` string, required: The Unix Epoch time of the call
  - `version` string, required: The version of the API. This version must match the version associated with your API key pair.
  - `signature` string: The HMAC signature that is calculated by running your API Secret Key and the alphabetized, concatenated parameters of the request payload through the SHA256 message digest algorithm. **NOTE:** This field is required when authenticating with the HMAC signature method; it is not required when authenticating with OAuth 2.0.
  - `agent_email` string, required: The email address of the agent.
  - `agent_name` string, required: The name of the agent.
  - `agent_role` string, required: The name of the role set for this agent.
  - `order_identifier` string: One of the following order identifiers, which can be used to locate the order after the agent authenticates into the Business Portal<ul><li>`pnm_order_identifier`</li><li>`site_order_identifier`</li><li>`site_customer_identifier`</li></ul>Required when <code>deep_link</code> is included.
  - `deep_link` 'take_payment' | 'schedule_autopay' | 'refund' | 'cancel_future_payment' | 'deactivate_autopay': The workflow to open on the order after the agent signs in. Supported values:<ul><li><code>take_payment</code>: the order page, ready for a one-time payment</li><li><code>schedule_autopay</code>: the order page with the Autopay setup window open</li><li><code>refund</code>: the refund form for the payment named by <code>payment_identifier</code></li><li><code>cancel_future_payment</code>: the scheduled-payment page for the schedule named by <code>schedule_identifier</code></li><li><code>deactivate_autopay</code>: the Autopay schedule page for the schedule named by <code>schedule_identifier</code></li></ul>Requires <code>order_identifier</code>. Targeted deep links are off by default and must be enabled for your site by your PayNearMe Technical Account Manager (TAM). If targeted deep links are not enabled for the site, the call returns an error: "Deep links are not available for this merchant, contact PayNearMe for details." For <code>refund</code>, <code>cancel_future_payment</code>, and <code>deactivate_autopay</code>, <code>order_identifier</code> must be the <code>pnm_order_identifier</code> of an existing order. <code>take_payment</code> and <code>schedule_autopay</code> also accept a <code>site_order_identifier</code> or <code>site_customer_identifier</code>. A <code>site_customer_identifier</code> can match more than one order, and the workflow then opens on whichever order the agent's search finds. Send the <code>pnm_order_identifier</code> when it has to be a specific order.
  - `payment_identifier` string: The <code>pnm_payment_identifier</code> of the payment to refund. Required when <code>deep_link</code> is <code>refund</code>. The value can be up to 64 characters. Sending <code>payment_identifier</code> without a <code>deep_link</code> returns an error. If <code>deep_link</code> names a workflow that does not use this identifier, the value is not included in the returned <code>sso_url</code>. The identifier is not checked when the link is created. If the payment cannot be found or refunded, the call still succeeds, and the agent lands on the order page with a message explaining why the refund did not open.
  - `schedule_identifier` string: The <code>pnm_scheduled_payment_identifier</code> of the scheduled payment or Autopay schedule. Required when <code>deep_link</code> is <code>cancel_future_payment</code> or <code>deactivate_autopay</code>. The value can be up to 64 characters. Sending <code>schedule_identifier</code> without a <code>deep_link</code> returns an error. If <code>deep_link</code> names a workflow that does not use this identifier, the value is not included in the returned <code>sso_url</code>. The identifier is not checked when the link is created. If the schedule cannot be found or acted on, the call still succeeds, and the agent lands on the order page with a message explaining why that workflow did not open.

## Response `200`

API Keys Revoked

- AgentSsoResponse
  - `status` string: Indicates whether or not the SSO authenticating token was successfully created.
  - `token` string: The authenticating SSO token.
  - `token_expires` string: The date and timestamp when this token expires.
  - `sso_url` string: The SSO URL where the agent can access the Business Portal. When the request includes a <code>deep_link</code>, the returned URL also carries the workflow. Use the URL exactly as returned.

## Other responses

- `401`: OAuth 2.0 requests only. The `Authorization` header has no Bearer token, the access token is invalid, expired, or issued for a different site, or the `site_identifier` does not match any site. The response does not say which. If the request is rejected before it reaches PayNearMe, the body may not be JSON, so detect this error by the HTTP status. HMAC-signed requests never receive this status.

## Changes

- **2026-11-03** `907541f733a3`: 1 breaking, 7 info
  - removed the success response with the status `201`
  - api operation id `agent_sso` was added
  - added the new optional request property `deep_link`
  - added the new optional request property `payment_identifier`
  - …4 more

[Operation history](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/changes/agent_sso/post.md)

---

[API](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0.md) - [All operations](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/llms.txt) - [OpenAPI document](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/revisions/907541f733a3?raw)
