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

# POST /find_payments

`POST /find_payments`

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/post_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, required — 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.
    - `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, required — 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.
    - `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, required — 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.
    - `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, required — 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.
    - `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 `201`

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' — 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).

---

[API](https://skmtc.net/paynearme/apis/paynearme-api-v3-0.md) · [All operations](https://skmtc.net/paynearme/apis/paynearme-api-v3-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/paynearme/paynearme-api-v3-0/revisions/44cba4f8b80f/schema)