Agent SSO Token Authentication

POST /agent_sso

Changed on

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

  • Base URL
    https://api.paynearme-sandbox.com/json-api
  • Auth
    • OAuth 2
      Client credentials
      Token URLhttps://login.paynearme.com/oauth/token
    • or API key in query parameter signature

Request body

site_identifierstring required

Identifies your client site.

timestampstring required

The Unix Epoch time of the call

versionstring required

The version of the API. This version must match the version associated with your API key pair.

signaturestring

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_emailstring required

The email address of the agent.

agent_namestring required

The name of the agent.

agent_rolestring required

The name of the role set for this agent.

order_identifierstring

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_identifierstring

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_identifierstring

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

API Keys Revoked

statusstring

Indicates whether or not the SSO authenticating token was successfully created.

tokenstring

The authenticating SSO token.

token_expiresstring

The date and timestamp when this token expires.

sso_urlstring

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.

Example response

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

Changes

    • breaking

      removed the success response with the status

    • info

      api operation id agent_sso was added

    • info

      added the new optional request property deep_link

    5 more changes in this revision