Proxy Site API: Integration Guide

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 v2.0+ endpoints.
• PayNearMe must explicitly enable the API Proxy feature for the partnership.
• 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:

If proxy_site_identifier is missing from a request, PayNearMe returns an Unrecognized API Call error. See the Error Handling Reference below.

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

Available Endpoints

Orders & Discovery

Payments

Scheduled Payments & Autopay

Notifications

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

1. Call /find_payments to see whether a payment has already been made toward the order.
2. If no payment exists, call /get_fees to retrieve the fees that apply, based on client configuration and/or consumer location.

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

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

1. With a tokenized payment method, call /schedule_payment.
2. Manage it with /find_scheduled_payment and /cancel_scheduled_payment.
3. 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

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)

Error handling reference

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.

1. The 3PPP requests access through Merchant Services, Account Management, or another PayNearMe contact, who opens a standard compliance request.
2. PayNearMe's Compliance Team requires written confirmation (e.g., email) from the client authorizing the 3PPP.
3. Once approved, the 3PPP receives API keys.
4. PayNearMe configures the client's system to allow proxy access per these guidelines.
5. The 3PPP and client test the required flows against the predefined use cases above.
6. The client coordinates go-live in the production environment.

For the underlying account setup (Site Admin account, Key Identifier/Secret Key pair, Base URIs, Authentication), see Getting Started with PayNearMe.

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.