Overview

When agents working in your CRM system need to complete a task in the PayNearMe Agent Interface, they normally have to open PayNearMe, search for the consumer's account, and then find the right task button. Deep links remove those steps.

Deep links already take agents directly to a customer or order. Targeted deep links go one step further: the link names the workflow the agent needs and takes the agent directly to the relevant page in the Agent Interface.

For example, a borrower calls their lender and asks to set up automatic payments. The agent clicks one button in the lender's own system. A new browser tab opens with the agent signed in to PayNearMe, on that borrower's account, and with the AutoPay setup window already open. No searching, no navigation, and nothing to memorize.

Targeted deep links add optional parameters to the existing /agent_sso API call. Agents do not need any new training and nothing changes for consumers.

Before You Begin

To use targeted deep links, make sure the following are in place:

1. Agent SSO is set up for your site. Your PayNearMe Technical Account Manager (TAM) must have configured your site and users for Agent SSO Token Authentication. See Using SSO with the API.
2. You are using a version 3.0+ API key. Agent SSO is not available with earlier versions.
3. Targeted deep links are enabled for your site. This setting is off by default. Contact your TAM to enable it.

How It Works

1. Your system sends an /agent_sso request that includes a deep_link value and, for some workflows, a record identifier.
2. PayNearMe validates the request and returns an sso_url.
3. Your system opens the sso_url in the agent's browser.
4. The agent is signed in, lands on the order, and the workflow you named is already open or on screen.

Each link works once for the order specified in the request. If the agent refreshes the page or returns to the link later, they see the normal order page and the workflow does not re-open.

The sso_url in the response already contains everything the Agent Interface needs. Pass it to the agent's browser as returned, and do not rebuild or edit it.

Choosing a Workflow

Set the deep_link parameter to one of the following values. Some workflows also require a record identifier.

Every targeted deep link also requires the order_identifier parameter, because the workflow opens on that order. The order_identifier can be one of the following parameters:

• pnm_order_identifier
• site_order_identifier
• site_customer_identifier

Additional Parameters

Include these optional parameters, along with the required parameters, when you make an /agent_sso call.

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

Example Request

The following example creates a link that opens the refund form for a specific payment. The examples use the Sandbox environment. See Request URLs for Production.

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=refund \
     -d payment_identifier=PAYMENT_IDENTIFIER \
     -d site_identifier=S5101017669 \
     -d version=3.0 \
     -d timestamp=1679423246 \
     -d signature=SIGNATURE

{
  "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&deep_link=refund&payment_id=PAYMENT_IDENTIFIER"
}

When a Link Cannot Open the Workflow

PayNearMe is designed so that an agent never reaches an error page because of a deep link. Problems are caught at one of two points.

When You Request the Link

If the workflow details are missing or invalid, the API refuses the request and returns an error that explains why. Examples include:

• The deep_link value is not recognized.
• A required identifier is missing or too long.
• An identifier is sent without a matching deep_link.
• Targeted deep links are not enabled for your site.
• For refund and schedule workflows, the order cannot be found for your site.

Because these are hard errors, a broken link is never handed to an agent.

When the Agent Opens the Link

If something changes between the time you create the link and the time the agent opens it, the agent lands on the consumer's Account page where the task can be completed manually. In some cases the agent also sees a short message/alert banner explaining why.

Security and Privacy

• Links are intended for one use and expire quickly. The sign-on token lasts about a minute, so a forwarded or bookmarked link does not keep working.
• A workflow can only open on the order the link was created for. A link cannot be redirected to a different consumer's order.
• Refund and schedule pages keep all of their normal permission and eligibility checks. A deep link is a shortcut to a page, never a way around eligibility rules or agent permissions. The agent's role must still allow the action. For example, refunds require the Refund Electronic Payments permission.
• If targeted deep links are turned off for your site, workflows stop opening immediately and links behave like plain order links.

Frequently Asked Questions

Related Pages

• Using Single Sign-On with the Agent Interface
• Using SSO with the API
• /agent_sso API Reference
• One-Time Payments in the Agent Interface
• Autopay Schedules in Agent Interface
• Refunds in the Agent Interface