System Overview

The goal of this product specification is to enable third parties to integrate with PayNearMe’s API efficiently as a partner that acts on behalf of a client. These API updates are designed to simplify and secure third-party communications with our site configurations by using a "proxy-only" feature. To describe these organizations, we will use the term Third Party Proxy Partners or 3PPP.

Proxy-Only Features

Third parties can communicate on behalf of customers without needing direct access to the customer’s site configurations. An essential requirement of this is that PayNearMe must enable the API Proxy partner in the PayNearMe solution. Only clients using the PayNearMe API v3.0 endpoints can use the proxy server solution.

Integration Requirements

API Compatibility

All API communication to PayNearMe will consist of using POST JSON requests related to the PayNearMe API 3.0 framework.

API Documentation

All API documentation can be found online at PayNearMe DevDocs, but specific information related to the proxy solution will be outlined below.

PayNearMe Framework

The PayNearMe Framework has been designed around the two concepts:

Order - An order is a payment obligation in the PayNearMe platform and could be a monthly car payment, a required fine for a citation, or a deposit to an online gaming account.
Payment Transaction - Payments can be completed using a previously stored payment token, creating a new payment token, using a PayNearMe-defined Smart Link (or Secure Smart Link) or by creating a new payment method in the PayNearMe environment.

PayNearMe APIs used for the Proxy Solution are an enhancement to the existing PayNearMe API architecture. The request from the partner to PayNearMe for each of the following API requests, requires adding two parameter to each API call being made:

proxy_site_identifer - This is the site identifier of the client which is having transactions processed by the 3PPP.
site_identifer - This is the 3PPP partner-assigned site identifier.

A Partner connects to PayNearMe and proxies into a client to process transactions on their behalf.

Each of the above values will need to be included in all API calls to PayNearMe.

/find_orders (with return_minimal_info=true) - Finds/Validates a specific order. If the flag is not included, the API returns payment tokens, smart links and the payment history (this is very resource intensive). This API POST method (with the flag) should only be used to validate if an order exists in the system, and not used to find the payment methods.
/create_payment_method - Creates a new card token (can also send payment in 1 step)
/make_payment - send payment information to PayNearMe for processing
/cancel_payment - cancels a payment processed by PayNearMe
/find_payment_methods - To find payment methods associated with a specific order, use one of the following values to search. When retrieving payment methods for a given order, the /find_payment_methods endpoint is more performant than /find_orders and will return only the available payment methods on an account, without including the detailed and lengthy response from /find_orders including payment history.
/get_fees - Retrieves the convenience fees associated with a pnm_order_identifier or a site_order_identifier. When passing in a site_channel, /get_fees will return the channel and order-specific pricing (i.e. honoring no-fee states) for a given order and method of payment (i.e. IVR).
/schedule_payment - Use either the pnm_order_identifier or the site_order_identifier to find the order and then include the following required parameters to make the payment.
/find_scheduled_payment - Use either the pnm_order_identifier or the site_order_identifier to find the next scheduled payment for an order. These payments can include recurring payments from an autopay schedule or a future-dated, one-time payment.
/cancel_scheduled_payment - Use the pnm_scheduled_payment_identifier to specify the scheduled payment you wish to cancel. Scheduled payments must be canceled prior to the payment_date.

Getting Started with PayNearMe

Before you begin development, you will need to set up your Sandbox and Production environments once your organization has been confirmed by the PayNearMe Compliance team by completing the following tasks:

Set up a Site Admin account in your PayNearMe Business Portal.
Create a Key Identifier and Secret Key pair.
Set up your Authentication.
Set up your Base URIs.

To get more information on each of these steps, please refer to Getting Started with PayNearMe.

API Flows and Use Cases

Standard Flow

Validate if an Order exists in the PayNearMe system using the /find_orders API POST command using the flag return_minimal_info=true. This call validates that an order exists in the PayNearMe system. If you do not pass return_minimal_info=true, the response will return additional information that is resource intensive. These additional parameters include the PayNearMe Smart Link, Secure Smart Link, and the pnm_order_identifier, pnm_customer_identifier, and the site_order_identifier if the order exists in the PayNearMe system. If the order does not exist, you should see an error message like "description": Order not found for given pnm_order_identifier.
Use the /get_fees API POST to get the system-configured fees associated with a client and or consumer location.
One-Time Payment options:
1. Use the /find_payment_methods to return payment tokenized values contained within the order/consumer account. The response to the API POST command can be used with Step 3 (/make_payment). Note if you have a payment token value to be used, you do not need to /create_payment_method.
2. Use the /create_payment_method API POST command to create a new payment token and use the /make_payment API POST command to send payment to PayNearMe. The /create_payment_method also allows for the ability to create a new token AND send the payment in one step.
3. With an existing and “Active” payment token (from /find_payment_methods), use the /make_payment API POST command to send payment to PayNearMe.
4. Send the consumer a PayNearMe Smart Link or Secure Smart Link (if the /find_orders is used) . This link allows the consumer to open an order-specific link and for the consumer to use existing payment methods or create new payment methods without the 3PPP having to handle sensitive information.
Cancel Payment: Ability to cancel a payment if needed.
Scheduled Payment Options:
1. Once you have a tokenized payment value, you can use the API POST commands to create a scheduled (future dated payment).
2. PNM has supplied the tools to /find_scheduled_payment, /cancel_scheduled_payment to manage this process.
3. While PNM does not have a restriction of the number of scheduled payments, we would encourage you to exercise caution in creating too many future dated payments as it could interfere with existing potentially scheduled payments.

The standard flow will be to submit these two API calls instead of /find_orders to validate if an Order exist. Calling /get_fees will provide the accurate pricing by payment method for the order and /find_payment_methods will provide the payment methods already saved to the account which can be used to accept payments and finally the /make_payment.

3PPP Specifics:

Each transaction requires CVV input when using /create_payment_method
Payments are initiated through the 3PPP solution to PayNearMe for payment processing.

Error Conditions

An Unrecognized API Call error will return if the proxy_site_identifier is missing in the API message.
An Order not found for the given __ identifier __ implies that an Order/Account value does not exist in our system or is incorrect.
______ is not a supported parameter for this API call implies you are sending a field that is not defined in the API.
Timestamp is out of range ( +/- 300 seconds) implies that the generation of the timestamp used in the signature calculation is outside the window (+/- 300 sec) of when the message was received by PayNearMe.
Signature is not correct -- string used for signature verification (redacted): … implies that the “body of the message” received by PayNearMe could not be used to validate the signature included in the body of the message sent to PayNearMe. In most cases the signature string was not alphabetized correctly or contains special characters (outside the except list of: ., -, _).
A response of "description": Order not found for given pnm_order_identifier, implies that the order does not exist in our system for the given site_identifier and proxy_site_identifier. This could be due to a bad value being passed or as the 3PPP, you are requesting an order which has yet to be applied to our system.

Compliance and Security

Data Security

Ensure all communication is secured and complies with existing compliance and risk management protocols as defined by the onboarding procedure outlined by the Compliance Team.

Funds Handling

Electronic payments are processed through standard PayNearMe funding methods.

Reporting and Analytics

Detailed transaction reports, including all payment types.
Operations report to mark the payment as settled.
Daily reports distinguish 3PPP payments from others (TBD).

Integration Steps

Third parties should request access credentials through Merchant Services, Account Management, or other PayNearMe personnel. The PayNearMe representative will open a standard request within the compliance process for the 3PPP to receive credentials.
The PayNearMe Compliance Team also will need to receive an email, or other form of written communication from the client wishing to add the 3PPP service to their site before credentials and access to the site can be performed.
The 3PPP will, upon approval, receive API keys for system integration for the client in question.
Next PayNearMe staff will set up and configure the client systems to allow access via the APIs in accordance to the outline proxy guidelines.
The 3PPP and the client should evaluate and test the required functions using the predefined API flows.
The client should coordinate the integration in a live environment.

Support and Maintenance

Regular updates and maintenance schedules will be communicated.
Technical Support is available through the standard PayNearMe support channels that are defined for standard troubleshooting.

Certification to PNM

(in progress)

Conclusion

This product specification provides all the necessary details for third parties to integrate with the Proxy API, ensuring a smooth and secure transaction processing experience. Third parties are encouraged to adhere closely to the guidelines for effective integration.