Proxy Site API: Integration Guide
Learn how to integrate with PayNearMe's Proxy Site API as a Third-Party Proxy Partner, including required parameters, authentication with OAuth 2.0 or HMAC signatures, endpoint reference, integration flows for one-time and recurring payments, and the onboarding and credentialing process.
What is a Proxy Site Integration?
PayNearMe's Proxy Site API lets a Third Party Proxy Partner (3PPP) process payments on behalf of a client without needing direct access to that client's site configuration. PayNearMe enables the proxy relationship on its side; once enabled, the 3PPP can call the standard PayNearMe API on the client's behalf.
Requirements:
- The client must be using PayNearMe API v3.0+ endpoints.
- PayNearMe must explicitly enable the API Proxy feature for the partnership.
- Requests are authenticated with either OAuth 2.0 (API v3.0+) or HMAC signatures. See Authentication.
- All communication uses POST JSON requests, consistent with the standard PayNearMe API framework.
Core concepts you'll work with:
- Order — a payment obligation in the PayNearMe platform (e.g., a loan payment, a citation fine, a deposit to a gaming account). See Learning the Basics.
- Payment Transaction — a payment made using a stored token, a new token, a Smart Link, or a new payment method created at time of payment.
Required Parameters for Every Proxy Call
Every API request made through a proxy integration must include two additional parameters beyond the standard PayNearMe API fields:
| Parameter | Description |
|---|---|
site_identifier | The 3PPP's own assigned site identifier. |
proxy_site_identifier | The site identifier of the client whose transactions are being processed. |
If proxy_site_identifier is missing from a request, PayNearMe returns an Unrecognized API Call error. See the Error Handling Reference below.
The following examples show the same /find_orders call authenticated with each supported method. See Authentication for how to choose.
OAuth 2.0 Example
curl --request POST \
--url https://api.paynearme-sandbox.com/json-api/find_orders \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '
{
"site_identifier": "S2155373459",
"proxy_site_identifier": "S9988776655",
"version": "3.0",
"timestamp": "1739400000",
"pnm_order_identifier": "PNM123456789",
"return_minimal_info": "true"
}
'HMAC Signature Example
curl --request POST \
--url https://api.paynearme-sandbox.com/json-api/find_orders \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"site_identifier": "S2155373459",
"proxy_site_identifier": "S9988776655",
"version": "3.0",
"timestamp": "1739400000",
"signature": "{SIGNATURE_VALUE}",
"pnm_order_identifier": "PNM123456789",
"return_minimal_info": "true"
}
'Authentication
Proxy calls use the same authentication methods as the rest of the PayNearMe API. PayNearMe decides which method applies to each request:
| Method | How to use it |
|---|---|
| OAuth 2.0 | Send Authorization: Bearer {access_token} in the request header and omit the signature parameter from the body. |
| HMAC signature | Send no Authorization header and include a signature parameter generated from your API keys. |
You can use both methods on the same site, so you can move one integration, endpoint, or environment to OAuth at a time. OAuth requires API v3.0+ and must be enabled for your site by your PayNearMe Technical Account Manager (TAM). When authenticating proxy calls with OAuth, keep the following in mind:
- The credentials and token belong to the 3PPP's own site. The
site_identifierin each request must be the site the access token was issued for. The token'sscopehas the formatexternal_id/{site_identifier}. - The client's site is not part of authentication. You don't request a token for the client, and
proxy_site_identifierisn't checked against the token. The client doesn't need to set up OAuth. - Everything else about a proxy call stays the same. Keep sending
site_identifier,proxy_site_identifier,version, andtimestamp, and PayNearMe applies the same proxy rules as for an HMAC-signed call. - Token requests, caching, and refresh work as described in OAuth 2.0 Authentication. Cache your access token and reuse it until it is near expiration. Don't request a new token for every API call.
Callbacks Still Use API KeysCallbacks continue to use API keys and HMAC signatures, even when your API calls use OAuth. Keep your API keys for callback validation. See API Keys and Callbacks.
Available Endpoints
Orders & Discovery
| Endpoint | Purpose | Notes |
|---|---|---|
| /find_orders | Finds/validates a specific order. | Use return_minimal_info=true when you only need to confirm an order exists. Without this flag, the response includes the full orders object — payment tokens, Smart Links, and payment history — which is resource-intensive. Do not use this endpoint just to look up payment methods. |
| /get_smart_token | Generates a Smart Link for consumer self-service. | Can be customized with a specific payment flow, expiration time, and/or post-payment redirect URL. Also confirms the order's existence. |
| /refresh_embedded_js_urls | Retrieves or regenerates the embedded_js_url for one or more orders. | Required to invoke the Embedded Form. |
| /find_payments | Retrieves an order's or customer's payment history, with sorting, limiting, and pagination. | Look up by site_order_identifier, pnm_order_identifier, pnm_customer_identifier, or site_customer_identifier. |
| /find_payment_methods | Finds payment methods saved to an order/account. | More performant than /find_orders when you only need payment methods — it skips the lengthy payment-history payload. |
| /get_fees | Retrieves convenience fees for an order. | Pass site_channel to get channel- and order-specific pricing (e.g., honoring no-fee states) for a given payment method such as IVR. |
Payments
| Endpoint | Purpose | Notes |
|---|---|---|
| /create_payment_method | Creates a new payment method token. | Can also send a payment in the same call. CVV input is required for card payment methods. |
| /make_payment | Sends payment information to PayNearMe for processing. | Use with an existing token from /find_payment_methods or /create_payment_method. |
| /cancel_payment | Cancels a payment already processed by PayNearMe. |
Scheduled Payments & Autopay
| Endpoint | Purpose | Notes |
|---|---|---|
| /schedule_payment | Creates a future-dated, one-time scheduled payment. | Requires a tokenized payment method and either pnm_order_identifier or site_order_identifier. |
| /find_scheduled_payment | Finds the next scheduled payment for an order. | Covers both autopay-driven and one-time, future-dated payments. |
| /cancel_scheduled_payment | Cancels a specific scheduled payment. | Uses pnm_scheduled_payment_identifier. Must be canceled before payment_date. |
| /cancel_scheduled_retry | Cancels a scheduled retry of a declined payment. | Uses pnm_schedule_identifier. Works for both autopay and one-time schedules. |
| /schedule_auto_pay | Creates a recurring autopay schedule. | Only one autopay schedule can exist per order. Supported autopay cadence options include the following:
|
| /skip_auto_pay | Skips the next scheduled autopay payment. | |
| /cancel_auto_pay | Cancels an autopay schedule. | |
| /update_auto_pay | Updates an autopay schedule. | Only auto_pay_amount can be changed. PayNearMe does not notify consumers of the update. |
Notifications
| Endpoint | Purpose |
|---|---|
| /send_sms | Sends an SMS message to the consumer. |
| /send_mail | Sends an email message to the consumer. |
| /send_notification | Sends an order confirmation, payment confirmation, or Disbursement User Query — by email or SMS. |
Integration Flows
Validate an Order
Use one of the following calls to validate that the order exists:
- /find_orders with
return_minimal_info=true— confirms the order exists without the resource-intensive full payload. - /get_smart_token — confirms the order exists and returns a Smart Link in one call.
If the order doesn't exist, expect an error like Order not found for given pnm_order_identifier.
sequenceDiagram
participant P as 3PPP System
participant PNM as PayNearMe API
alt Confirm Order Only
P->>PNM: POST /find_orders (return_minimal_info=true)
PNM-->>P: Order Confirmed
else Confirm Order and Get a Smart Link
P->>PNM: POST /get_smart_token
PNM-->>P: Order Confirmed + Smart Link URL
end
Check Payment History and Fees
- Call /find_payments to see whether a payment has already been made toward the order.
- If no payment exists, call /get_fees to retrieve the fees that apply, based on client configuration and/or consumer location.
Recommended DefaultRather than using
/find_ordersto validate an order, most integrations should pair/get_fees(accurate pricing by payment method) with/find_payment_methods(saved payment methods) and then/make_payment.
sequenceDiagram
participant P as 3PPP System
participant PNM as PayNearMe API
P->>PNM: POST /find_payments
PNM-->>P: Payment History
opt No Existing Payment Found
P->>PNM: POST /get_fees
PNM-->>P: Applicable Fees
end
Take a One-Time Payment
This flow branches depending on how you want to source the payment method, so it's easier to follow as a diagram than a list:
sequenceDiagram
participant P as 3PPP System
participant PNM as PayNearMe API
participant C as Consumer
alt Use a Saved Payment Method
P->>PNM: POST /find_payment_methods
PNM-->>P: Tokenized Payment Methods
P->>PNM: POST /make_payment (Token)
else Create a New Payment Method
P->>PNM: POST /create_payment_method
PNM-->>P: New Token (+ Payment, if included)
else Hand Off to Consumer
P->>PNM: POST /get_smart_token
PNM-->>P: Smart Link URL
P->>C: Deliver Smart Link
C->>PNM: Consumer Completes Payment
end
PNM-->>P: Payment Result
P->>PNM: POST /send_sms, /send_mail, or /send_notification
PNM->>C: Payment Confirmation
One-Time Payment Notes
Saved Payment MethodsYou don't need
/create_payment_methodif you already have a token.
New Payment MethodsYou can send the payment in the same call as
/create_payment_method, or as a separate/make_paymentcall.
Consumer Hand-OffA Secure Smart Link requires having already called
/find_orders; this path keeps sensitive payment data out of the 3PPP's system entirely.
Cancel a Payment
Call /cancel_payment if a payment needs to be reversed.
sequenceDiagram
participant P as 3PPP System
participant PNM as PayNearMe API
P->>PNM: POST /cancel_payment
PNM-->>P: Payment Canceled
Schedule a One-Time Future-Dated Payment
- With a tokenized payment method, call /schedule_payment.
- Manage it with /find_scheduled_payment and /cancel_scheduled_payment.
- Notify the consumer as in step 3.
sequenceDiagram
participant P as 3PPP System
participant PNM as PayNearMe API
participant C as Consumer
P->>PNM: POST /schedule_payment (token, date, amount)
PNM-->>P: Scheduled payment created
opt Manage the schedule later
P->>PNM: POST /find_scheduled_payment
PNM-->>P: Next scheduled payment
P->>PNM: POST /cancel_scheduled_payment
PNM-->>P: Scheduled payment canceled
end
P->>PNM: POST /send_sms, /send_mail, or /send_notification
PNM->>C: Payment confirmation
Future-Dated Payment LimitationsPayNearMe doesn't cap the number of scheduled payments, but avoid creating too many future dated payments — they can interfere with other scheduled payments on the same order.
Manage a Recurring Autopay Schedule
Autopay has more moving parts than a one-time schedule — an ongoing billing loop, decline retries, and several management actions — so a diagram captures the lifecycle better than a numbered list:
sequenceDiagram
participant P as 3PPP System
participant PNM as PayNearMe API
participant C as Consumer
P->>PNM: POST /schedule_auto_pay (Token, Cadence)
PNM-->>P: Autopay Schedule Sreated
loop Each Billing Cycle
PNM->>PNM: Attempt Scheduled Payment
alt Payment Succeeds
PNM->>C: Payment Confirmation
else Payment Declines
PNM->>PNM: Schedule Retry
opt 3PPP Cancels the Retry
P->>PNM: POST /cancel_scheduled_retry
end
end
end
opt Manage the Schedule at Any Time
P->>PNM: POST /skip_auto_pay
P->>PNM: POST /update_auto_pay (Amount Only)
P->>PNM: POST /cancel_auto_pay
end
P->>PNM: POST /find_scheduled_payment (Check Next Payment)
Recurring Autopay Notes
Only one autopay schedule can exist per order.
The
/update_auto_payendpoint can only change theauto_pay_amount. PayNearMe doesn't notify the consumer when this happens, so the 3PPP is responsible for any consumer communication.The
/cancel_scheduled_retryendpoint uses thepnm_scheduled_payment_identifiervalue and works for both autopay and one-time schedules.
3PPP Requirements
Every card payment method created via the
/create_payment_methodendpoint requires CVV input.All payments are initiated through the 3PPP to PayNearMe for processing. PayNearMe does not process payments directly with the end-client in a proxy integration.
Error handling reference
| Error | Cause |
|---|---|
HTTP 401 Unauthorized (OAuth only) | The Authorization header has no Bearer token, or the access token is invalid, expired, or issued for a different site than site_identifier. A site_identifier that doesn't match any site returns the same error. The response doesn't say which cause applies, and the body may not be JSON, so detect this error by the 401 status. Request a new token and retry once. If the retry fails, confirm the token was issued for your own site_identifier. |
Unrecognized API Call | The proxy_site_identifier is missing from the request. |
Order not found for the given __ identifier __ | The order/account value doesn't exist in PayNearMe's system or is incorrect. |
Order not found for given pnm_order_identifier | The order doesn't exist for the given site_identifier/proxy_site_identifier pair. Check for a bad value, or confirm the order has actually been applied to PayNearMe's system yet. |
______ is not a supported parameter for this API call | The request includes a field that isn't defined for that endpoint. |
Timestamp is out of range (+/- 300 seconds) | HMAC only. The timestamp used to generate the request signature falls outside the ±300 second window that PayNearMe allows. |
Signature is not correct — string used for signature verification (redacted): … | HMAC only. The request body couldn't validate the included signature. Usually this occurs because the signature string wasn't alphabetized correctly, or contains characters outside the allowed set (., -, _). |
When you authenticate with OAuth, only a token problem returns HTTP 401. Every other failure, including the proxy errors in the table above, returns HTTP 200 with "status": "error" and the description in the response body. Don't refresh your token for those errors.
If you send a Bearer token and still receive errors about signature or timestamp, PayNearMe is treating the request as HMAC-signed. This happens when the request has no Authorization header, or when your site isn't enabled for OAuth. A Bearer token sent to a site that isn't enabled for OAuth is ignored. Check your request headers, then contact your TAM.
Onboarding and Credentialing
Proxy integrations follow PayNearMe's standard credentialing process, with one addition: the client must confirm in writing that they want the 3PPP added to their site before access is granted.
- The 3PPP requests access through Merchant Services, Account Management, or another PayNearMe contact, who opens a standard compliance request.
- PayNearMe's Compliance Team requires written confirmation (e.g., email) from the client authorizing the 3PPP.
- Once approved, the 3PPP sets up authentication for its own site, using either of the following:
- API keys for HMAC signature authentication.
- OAuth 2.0 client credentials. Your TAM enables OAuth for your site. Then a Business Portal user with both Developer and Admin permissions provisions the site and generates the Client ID, Client Secret, and Audience. See Generating Credentials in the Business Portal. Sandbox and production credentials are separate, and each site can hold up to two credential sets.
- PayNearMe configures the client's system to allow proxy access per these guidelines.
- The 3PPP and client test the required flows against the predefined use cases above. If you use OAuth, test token requests and Bearer-authenticated proxy calls in sandbox first.
- The client coordinates go-live in the production environment. If you use OAuth, provision the site and generate credentials in production first.
For the underlying account setup (Site Admin account, Base URIs, and authentication with either a Key Identifier/Secret Key pair or OAuth 2.0 client credentials), see Getting Started with PayNearMe and OAuth 2.0 Authentication.
Compliance, Security, and Reporting
- Data security: All communication must comply with the compliance and risk management protocols defined during onboarding by the Compliance Team.
- Funds handling: Electronic payments are processed through PayNearMe's standard funding methods; no proxy-specific handling applies.
- Reporting: Clients and 3PPPs can access detailed transaction reports covering all payment types, plus an operations report to mark payments as settled.
Support
Technical support is available through PayNearMe's standard support channels. Regular maintenance and update schedules will be communicated as they occur.
Updated 10 days ago
