---
title: "POST /find_scheduled_payments"
method: POST
path: "/find_scheduled_payments"
tags: ["One-Time Schedules"]
---

# POST /find_scheduled_payments

`POST /find_scheduled_payments`

## Request

- Base URL: `https://api.paynearme-sandbox.com/json-api`
- URL: `https://api.paynearme-sandbox.com/json-api/find_scheduled_payments`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://login.paynearme.com/oauth/token`
  - API key in query parameter `signature`

Use either the <code>pnm_order_identifier</code> or the <code>site_order_identifier</code> 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.

## Request body

- union: Finds the next future-dated, one-time payment or autopay payment that is scheduled to process.
  - object
    - `site_identifier` string, required: Identifies your client site.
    - `timestamp` string, required: The Unix Epoch time of the call
    - `version` string, required: The version of the API. This version must match the version associated with your API key pair.
    - `signature` string: 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.
    - `pnm_order_identifier` string, required: The unique, PayNearMe-defined identifier for this order
  - object
    - `site_identifier` string, required: Identifies your client site.
    - `timestamp` string, required: The Unix Epoch time of the call
    - `version` string, required: The version of the API. This version must match the version associated with your API key pair.
    - `signature` string: 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.
    - `site_order_identifier` string, required: An arbitrary string that the client uses to refer to an order

## Response `200`

Finds the Next Scheduled Payment

- union
  - object
    - `status` 'ok', required
    - `scheduled_payment` ScheduledPayment: The Scheduled Payments object contains the details of future-dated, one-time payments.
      - `pnm_scheduled_payment_identifier` string: The unique, PayNearMe-provided ID of this scheduled payment.
      - `scheduled_payment_date` string, date-time: The date and time when the consumer scheduled the payment.
      - `scheduled_payment_amount` number: The total amount of the scheduled payment including convenience fees.
      - `scheduled_payment_currency` string: USD
      - `scheduled_payment_status` 'active' | 'user_suspended' | 'pending' | 'complete' | 'disabled' | 'declined': The status of the payment.
      - `scheduled_payment_pricing_schedule_name` string: Specifies the name of the pricing schedule (e.g.,<code>agent_recurring</code> or <code>consumer_recurring</code>). Supported values can include site-configured pricing schedules.
      - `scheduled_payment_payment_method` string: A short description of the payment method that will be used for this scheduled payment.
      - `scheduled_payment_service_fee` string: The service fee that will be charged for this scheduled payment.
      - `scheduled_payment_origin` 'consumer' | 'merchant' | 'import' | 'pnm': The origin of the scheduled payment. Supported options include the folloing:<ul><li><code>consumer</code></li><li><code>merchant</code></li><li><code>import</code></li><li><code>pnm</code></li></ul>
      - `scheduled_payment_created_by` string: The name or ID of the creator of this scheduled payment.
      - `scheduled_payment_type` string: Indicates whether this is a <code>recurring</code> autopay payment or a <code>one-time</code> scheduled payment.
      - `scheduled_payment_retry_pending` string: Indicates whether or not there is a pending retry scheduled for this transaction.
  - ErrorEnvelope: Returned with HTTP 200 for every failure except a rejected OAuth 2.0 access token, which returns HTTP 401 with the same shape. Every response carries a status; on failure it is "error" and the errors array describes what went wrong.
    - `status` 'error', required
    - `errors` ErrorDetail[], required: One entry per failure.
      - `description` string, required: Human-readable description of the failure.
      - `message` string: Parameter-validation detail (APPS-17178).
      - `receipt` string: Receipt text, where the failure relates to a payment.
      - `format` string: Expected format, for parameter-validation failures.
      - `example` string: Example of a well-formed value.
      - `details` object: Processor response details (APPS-18223).

## Other responses

- `401`: OAuth 2.0 requests only. The `Authorization` header has no Bearer token, the access token is invalid, expired, or issued for a different site, or the `site_identifier` does not match any site. The response does not say which. If the request is rejected before it reaches PayNearMe, the body may not be JSON, so detect this error by the HTTP status. HMAC-signed requests never receive this status.

## Changes

- **2026-11-03** `907541f733a3`: 1 breaking, 6 info
  - removed the success response with the status `201`
  - api operation id `find_scheduled_payments` was added
  - the request property `site_identifier` with a default value became required
  - the request property `timestamp` with a default value became required
  - …3 more

[Operation history](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/changes/find_scheduled_payments/post.md)

---

[API](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0.md) - [All operations](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/llms.txt) - [OpenAPI document](https://skmtc.dev/paynearme/apis/paynearme-api-v3-0/revisions/907541f733a3?raw)
