List Payments

Retrieve a list of payments from your account.

Parameters
Parameter Type Required Default Description
filters[account_id] Int No N/A Funding source id to filter payments by
filters[file_id] Int No N/A Only return payments uploaded from the file specified. File ID is listed in the Reports > Payment Files page.
filters[method_id] Int No N/A Method to filter payments by. method_id=1 is ACH, method_id=2 is Check
filters[status_id] Int No N/A Only return payments with the specified status. There is a full list of payment statuses under Resources > Payment Statuses in this documentation.
filters[postage_id] Int No N/A Only return payments with the specified postage id. There is a full list of postage ids under Resources > Postage
filters[payee_name] String No N/A Return payments where payee name matches provided string (with wildcard after)
filters[payee_name] String No N/A Return payments where payee name matches provided string (with wildcard after)
filters[payee_address] String No N/A Return payments where address matches provided string (with wildcard after)
filters[memo] String No N/A Return payments where memo matches provided string (with wildcard after)
filters[is_digital] Int (Boolean) No N/A 1 to only return digital payments (digital checks/ach), 0 to only match printed checks.
filters[by_date] String No N/A To filter by date, you specify the date field you want to filter by here as well as the date parameter (outlined next). The date field should be one of the following..
  • created_ts - date payment was created
  • updated_ts - date the payment was last updated
  • deleted_ts - date a payment was deleted
  • issue_ts - date a payment should be issued on (used when payments had an issue date set on them on add
  • sent_ts - date a payment was actually sent
  • cancelled_ts - date a payment was cancelled
  • returned_ts - date a payment was marked as returned
  • cleared_ts - date a payment was marked as posted/cashed
  • claimed_ts - date a digital check was claimed
filters[date] String or Array No N/A This can be passed as a string or an array, if it's an array then the payments are filtered by the daterange and the first item in the array is the beginning date, the second is the end date. If it's a single string passed it'll return all payments where the date field is that day.
include_tracking Boolean No false Pass true to include the metadata.tracking_data object (with tracking_number, carrier_id, carrier_code, and carrier_service) on each returned payment. When omitted or false, the tracking_data object is not added to metadata. The legacy metadata.tracking string (tracking number only) is always returned for any payment that has a tracking number on file, regardless of this flag.
Sample Response
{"status":0,"errors":[],"error_message":"","payments":{"1":{"id":"1","payee_id":null,"account_id":null,"client_invoice_id":null,"file_id":null, "batch_id":null,"status_id":"2","postage_id":null,"guid":"c4ca4238a0b923820dcc509a6f75849b","created_ts":"2019-09-22 05:46:05","updated_ts":null,"deleted_ts":null,"issue_ts":null, "sent_ts":null,"cancelled_ts":null,"returned_ts":null,"cleared_ts":null,"claimed_ts":null,"payee_name":"A Payee","payee_address":"123 Some St. City, ST 33434", "memo":null,"amount":"100.00","fees":"0.00","flagged":"0","confirmed":"1","claimed":"0","is_digital":"0","deleted":"0", "metadata":{"tracking":"9400110200881234567890","tracking_data":{"tracking_number":"9400110200881234567890","carrier_id":1,"carrier_code":"USPS","carrier_service":"USPS_PRIORITY"}}}}}
Tracking Fields

The legacy metadata.tracking string (just the carrier tracking number) is returned unconditionally for every payment that has a tracking number on file — this matches the long-standing behavior integrations have always relied on. The richer metadata.tracking_data object (carrier id, code, and service) is opt-in: pass include_tracking=true in the request to receive it. When the flag is omitted, the tracking_data object is not added to the metadata object. The response does not include top-level tracking fields. Sub-field values of tracking_data are null when no tracking information is available for that payment.

When a payment belongs to a bundle and the bundle has tracking assigned, that tracking is automatically mirrored onto each payment in the bundle, so every payment in the bundle returns the same tracking_number, carrier_code, and carrier_service as the bundle. Payments that already have their own individually-assigned tracking keep that override.

Field Type Description
metadata.tracking String / absent Legacy scalar mirror of the active tracking number. Always returned when the payment has any tracking number on file (resolved in the same order as tracking_data); omitted from the metadata object when no tracking number is known. This field is independent of the include_tracking flag.
metadata.tracking_data Object Container object for the tracking sub-fields below. Only present when include_tracking=true is passed.
metadata.tracking_data.tracking_number String / null Carrier tracking number for the payment's mailpiece.
metadata.tracking_data.carrier_id Integer / null ID of the tracking carrier stored on the active tracking record. null when only a legacy tracking number is known.
metadata.tracking_data.carrier_code String / null Short carrier code (e.g. USPS, FEDEX, UPS, DHL, OTHER) for the active tracking record. When the tracking row has no carrier we fall back to the carrier implied by the payment's postage (or the bundle's postage for inherited tracking).
metadata.tracking_data.carrier_service String / null Normalized carrier-service code for the active tracking record (e.g. USPS_PRIORITY, FEDEX_2DAY, UPS_GROUND). null when no service is set.

Resolution order (used for both metadata.tracking and metadata.tracking_data): (1) the payment's own tracking record; (2) legacy metadata tracking value (number only); (3) the bundle's tracking record when the payment is bundled; (4) the legacy bundle tracking column (number only). The first non-empty source wins.