---
title: "POST /find_payments"
method: POST
path: "/find_payments"
tags: ["Payments"]
---

# POST /find_payments

`POST /find_payments`

## Request

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

A dedicated endpoint for retrieving an order's payment history with explicit control over sorting, limiting, and pagination. This endpoint allows clients to retrieve a list of payments for a specific order directly via the <code>site_order_identifier</code> or the <code>pnm_order_identifier</code> or for a specific customer directly via the <code>pnm_customer_identifier</code> or the <code>site_customer_identifier</code>. This endpoint is only for returning regular consumer payments and not disbursements (use the [/find_disbursements](https://apidocs.paynearme.com/devdocs/reference/find_disbursements) endpoint for push payments).

## Request body

- union: Retrieves payment history for specific orders or customer accounts with explicit control over sorting, limiting, and pagination.
  - 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 PayNearMe-created ID for the order.
    - `site_order_identifier` string: An arbitrary string that the client uses to refer to an order.
    - `pnm_customer_identifier` string: A unique PNM-defined ID for the consumer..
    - `site_customer_identifier` string: A unique, client-defined ID for the consumer.
    - `sort` 'asc' | 'desc': Sort direction: 'asc' (oldest first) or 'desc' (newest first). Default: 'desc'
    - `limit` integer: Used for pagination, this parameter specifies the maximum number of payments to return. Default value is <code>10</code>.
    - `offset` integer: Used for pagination, this parameter specifies the number of payments to skip within the response. Default value is <code>0</code>.
    - `start_date` string, date: Filter payments on or after this date (YYYY-MM-DD)
    - `end_date` string, date: Filter payments on or before this date (YYYY-MM-DD)
  - 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: The unique, PayNearMe-defined identifier for this order.
    - `site_order_identifier` string, required: The arbitrary string that the client uses to refer to an order.
    - `pnm_customer_identifier` string: A unique PNM-defined ID for the consumer..
    - `site_customer_identifier` string: A unique, client-defined ID for the consumer.
    - `sort` 'asc' | 'desc': Sort direction: 'asc' (oldest first) or 'desc' (newest first). Default: 'desc'
    - `limit` integer: Used for pagination, this parameter specifies the maximum number of payments to return. Default value is <code>10</code>.
    - `offset` integer: Used for pagination, this parameter specifies the number of payments to skip within the response. Default value is <code>0</code>.
    - `start_date` string, date: Filter payments on or after this date (YYYY-MM-DD)
    - `end_date` string, date: Filter payments on or before this date (YYYY-MM-DD)
  - 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: The unique, PayNearMe-defined identifier for this order.
    - `site_order_identifier` string: An arbitrary string that the client uses to refer to an order.
    - `pnm_customer_identifier` string, required: A PayNearMe-assigned ID for the customer.
    - `site_customer_identifier` string: A unique, client-defined ID for the consumer.
    - `sort` 'asc' | 'desc': Sort direction: 'asc' (oldest first) or 'desc' (newest first). Default: 'desc'
    - `limit` integer: Used for pagination, this parameter specifies the maximum number of payments to return. Default value is <code>10</code>.
    - `offset` integer: Used for pagination, this parameter specifies the number of payments to skip within the response. Default value is <code>0</code>.
    - `start_date` string, date: Filter payments on or after this date (YYYY-MM-DD)
    - `end_date` string, date: Filter payments on or before this date (YYYY-MM-DD)
  - 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: The unique, PayNearMe-defined identifier for this order.
    - `site_order_identifier` string: An arbitrary string that the client uses to refer to an order.
    - `pnm_customer_identifier` string: A unique PNM-defined ID for the consumer..
    - `site_customer_identifier` string, required: A unique, client-defined ID for the consumer.
    - `sort` 'asc' | 'desc': Sort direction: 'asc' (oldest first) or 'desc' (newest first). Default: 'desc'
    - `limit` integer: Used for pagination, this parameter specifies the maximum number of payments to return. Default value is <code>10</code>.
    - `offset` integer: Used for pagination, this parameter specifies the number of payments to skip within the response. Default value is <code>0</code>.
    - `start_date` string, date: Filter payments on or after this date (YYYY-MM-DD)
    - `end_date` string, date: Filter payments on or before this date (YYYY-MM-DD)

## Response `200`

Payments Found

- FindPaymentsResponse: Response to the <code>/find_payments</code> call, which contains a list of payments matching the search request's criteria.
  - `status` string: Response status (e.g., 'ok')
  - `payments` FindPaymentsPayment: Payment object returned by the Find Payments endpoint. Extends the base payment object with order and customer identifiers for cross-referencing.
    - `payment_made` string, date-time: The date and time when the customer made the payment.
    - `payment_amount` number: The total amount of the payment including convenience fees.
    - `payment_currency` string: USD
    - `payment_status` 'approved' | 'authorized' | 'canceled' | 'refunded' | 'rejected' | 'waiting for review' | 'pending' | 'returned' | 'scheduled' | 'cancelled': The status of the payment.
    - `payment_type` 'ach' | 'ach_push' | 'cash' | 'cash_app' | 'credit' | 'debit' | 'paypal' | 'paypal-push' | 'pin4' | 'push-debit' | 'venmo' | 'venmo-push': The type of payment method used for the transaction. Payment methods prefixed or suffixed with <code>push</code> are for disbursement transactions.
    - `payment_account` string: A short description of the payment method.
    - `payment_method_identifier` string: A unique ID for the payment method.
    - `net_payment_amount` number: The payment amount that is settled to the consumer after all client, retailer (if applicable), and PayNearMe fees have been taken out.
    - `net_payment_currency` string: USD
    - `payment_processing_fee` number: The fee amount charged for processing the transaction.
    - `payment_processing_fee_currency` string: USD
    - `pnm_processing_fee` number: The fee amount that PayNearMe charges for processing the transaction.
    - `pnm_processing_fee_currency` string: USD
    - `settled_to_site` string: If set to <code>true</code>, the payment has been settled to the client's account.
    - `date_settled_to_merchant` string, date: The date in <i>YYYY-MM-DD</i> format when the payment was settled to the client.
    - `pnm_payment_identifier` string: A unique string identifier for the payment.
    - `retailer_identifier` string: A unique PayNearMe-assigned ID for a retailer.
    - `pricing_schedule_name` string: Specifies the name of the pricing schedule (e.g.,<code>agent</code>, <code>agent_recurring</code>, <code>consumer</code>, <code>consumer_recurring</code>,<code>consumer_ivr</code>). Supported values can include site-configured pricing schedules.
    - `site_channel` 'agent' | 'agent_waived' | 'consumer' | 'consumer_ivr' | 'kiosk' | 'agent_recurring' | 'consumer_recurring': The payment channel where this payment was created.
    - `payment_receipt_text` string: Custom text that can be returned in the authorization callback response. Up to 75 lines of 40 character each can be included.
    - `card_bin` string: The first six digits of the card (BIN) used for the payment. Only present for card-based payments.
    - `site_order_identifier` string: The client-defined identifier for the order associated with this payment.
    - `pnm_order_identifier` string: The PayNearMe-created identifier for the order associated with this payment.
    - `site_customer_identifier` string: The client-defined identifier for the customer associated with this payment.
    - `pnm_customer_identifier` string: The PayNearMe-created identifier for the customer associated with this payment.
    - `site_payment_identifier` string: A client-defined ID for the payment record, if provided in the <code>/make_payment</code> call.
    - `payment_authorization_memo` string: The date and time when the payment was authorized.
    - `merchant_settlements` MerchantSettlements: The Merchant Settlements object indicates where and for how much a payment was settled.
      - `settlement_method_identifier` string: A unique, PayNearMe-provided ID for the settlement.
      - `settlement_type` 'net_payment' | 'gross_payment': Indicates whether the settlment is a <code>net_payment</code> or a <code>gross_payment</code>.
      - `settlement_amount` number: The amount to be settled
      - `settlement_currency` string: USD
    - `refund` Refund: The Refund object indicates the status of the payment refund.
      - `refund_status` 'started' | 'completed': The status of the refund. Supported options include <code>started</code> and <code>completed</code>.
      - `refund_amount` string: The amount to be refunded.
      - `refund_currency` string: USD
      - `unsettle_to_merchant_amount` string: The amount that will be unsettled from the client account (i.e., the payment amount less the convenience fee)
      - `unsettle_to_merchant_currency` string: USD
      - `unsettled_from_collector_amount` string: The amount that will be unsettled from the collector (if applicable).

## 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_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_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)
