Preview

List payments

GET
/providers/{providerID}/payments

List the payouts and requests for payment that you own, across all of your participants. Rows have no direction: initiator is the sender or requester, and counterparty is the recipient or payer. Returns an empty list when none match.

A party name is the current participant name when the party is your participant. Otherwise it is the name recorded on the payment, such as the name a recipient gave at claim. Moov Money never uses contact labels, and never reads the profile of a participant that is not yours. Instruments follow the rules on PaymentPartyFunding.

Pagination is cursor-based over (createdOn, paymentID), newest first. Moov Money applies every filter before pagination. Omit cursor to fetch the first page; use nextCursor from each response to fetch the next page. Returns a 400 with problem type invalid-cursor when the cursor is malformed, or when it does not match this provider, the participantID filter, or the other current filters.

Auth: API key or bearer token. Scoped to the calling provider.

Request
cURL
curl -X GET https://api.moov.money/providers/{providerID}/payments \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "X-Moov-Version: v2026.10.00"
Responses
200 400 401 403 422
The request completed successfully.
{
  "payments": [
    {
      "amount": {
        "currency": {
          "code": "USD",
          "decimalPlaces": 2,
          "name": "US Dollar",
          "numericCode": "840"
        },
        "value": "100.00"
      },
      "counterparty": {
        "displayName": "Jane Doe",
        "externalID": "C-2077",
        "funding": {
          "displayName": "Checking",
          "fundingType": "bank_account",
          "last4": "5612"
        },
        "participantID": "counterparty-id_user",
        "phoneNumber": "+15555551234"
      },
      "createdOn": "2026-10-06T15:00:00Z",
      "hold": {
        "active": true,
        "expiresOn": "2026-10-06T17:00:00Z"
      },
      "initiator": {
        "displayName": "Jane Smith",
        "externalID": "C-1042",
        "funding": {
          "displayName": "Checking",
          "fundingType": "bank_account",
          "last4": "5612"
        },
        "participantID": "participant-id_user"
      },
      "memo": "Rent split",
      "paymentID": "pay_01HF5J9ZKQT4RXP8M2VYBN3D",
      "referenceNumber": "7K2Q9X4FC",
      "status": "initiated",
      "type": "payout"
    }
  ]
}
Malformed request: the body or headers failed validation.
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.
Authentication missing, invalid, or insufficient.
Authentication present but the action is forbidden for this principal/claim.
The request was well-formed but couldn’t be processed (e.g. card declined).
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.

Headers

X-Moov-Version

string
Set this header to the API version being targeted (e.g. v2026.10.00). When omitted, the server applies its default version.

Path parameters

providerID

string required
Your provider account ID.

Query parameters

q

string
Case-insensitive search over the memo and the party names that you can see. An exact participant ID (it ends in _user) or your exact external ID for a participant also matches the payments of that participant. A value that contains only digits and phone punctuation, with at least three digits, also matches the phone number the payment was addressed to, by its digits: (555) 123 matches +15551234567. Contact labels and emails never match. Leading and trailing spaces are ignored. Returns 422 with problem type invalid-request when the trimmed value is longer than 100 characters, or when it contains only digits and phone punctuation with fewer than three digits.

type

string
Return only payouts or only requests. Omit to return both.
Possible values: payout, request

status

array
Return payments in any of these raw statuses. Repeat the parameter to select more than one, for example status=initiated&status=authorized. A status matches only payments of the family that defines it. Unrecognized values return 400. Omit to return all statuses.

onHold

boolean
true returns only payments with an active risk hold (hold.active). false returns only payments without one. Omit to return both.

createdFrom

string <date-time>
Return payments created at or after this time (inclusive).

createdTo

string <date-time>
Return payments created before this time (exclusive). Must be later than createdFrom; otherwise returns 400.

paymentID

string
Return only the payment with this payout ID or request ID.

referenceNumber

string
Return only the payment with this support reference.

participantID

string
Return only payments in which this participant is the initiator or the counterparty. Takes a participantID, not your external ID. Returns an empty list when the participant has no payments that you own.

cursor

string
Opaque pagination cursor from a previous response’s nextCursor. Omit to fetch the first page.

limit

integer <int32>
Maximum number of payments to return. Defaults to 25; values outside 1-100 return 400.

Response

Response envelope for GET /providers/{providerID}/payments.

payments

array<object> required
The page of your payments, newest first.
Show child attributes

payments[]

Matches exactly one of the following, determined by type:

Payouttype: "payout"
A payout row in the provider-wide payment list. type is always payout and paymentID is a payout ID. Provider-wide rows have no direction: initiator is the sender and counterparty is the recipient.

type

string<enum> required
Type discriminator.
Possible values: payout

paymentID

string required
The payout identifier.

amount

object required
Amount and currency.
Show child attributes

payments[].amount

value

string required
Decimal amount as a string.

currency

object required
ISO 4217 currency descriptor.
Show child attributes

payments[].amount.currency

code

string required
Uppercase 3-letter ISO 4217 currency code.

decimalPlaces

integer<uint8> required
Number of minor-unit decimal places for code. Required.

numericCode

string
ISO 4217 numeric currency code, if known. Informational only.

name

string
Human-readable currency name, if known. Informational only.

status

string<enum> required
Current lifecycle status of the payout.
Possible values: initiated, authorized, accepted, claiming, completed, failed, payout_failed, cancelled, expired, denied

referenceNumber

string required
Short support reference for the payout.

memo

string
Free-form note attached by the sender.

initiator

object required
The participant who sent the payout.
Show child attributes

payments[].initiator

participantID

string required
The initiator’s participant ID.

externalID

string
Your external ID for the initiator.

displayName

string
The initiator’s current name (given + family). Omitted when unknown.

funding

object
The initiator’s instrument for this payment: the funding source a payout sends from, or the funding destination a request pays into. Omitted until the instrument is known.
Show child attributes

payments[].initiator.funding

fundingType

string<enum> required
Instrument discriminator.
Possible values: card, bank_account

displayName

string
Human-readable display label, such as the account nickname or card brand. Omitted when unknown.

last4

string
Last four digits of the card number for card, or of the bank account number for bank_account. Omitted when unknown. At most 4 characters.

counterparty

object required
The recipient. Only the addressed phone is known until the recipient claims the payout.
Show child attributes

payments[].counterparty

displayName

string
Counterparty display name (given + family) when known.

phoneNumber

string
Counterparty phone number in E.164 form when known.

participantID

string
The party’s participant ID, once the party is bound to the payment. Omitted for an unbound party, such as the recipient of an unclaimed payout or the payer of an open request. The ID does not give access to the record of a participant that is not yours.

externalID

string
Your external ID for the party. Present only when the party is your participant.

funding

object
The instrument the party used for this payment. Omitted until the instrument is known.
Show child attributes

payments[].counterparty.funding

fundingType

string<enum> required
Instrument discriminator.
Possible values: card, bank_account

displayName

string
Human-readable display label, such as the account nickname or card brand. Omitted when unknown.

last4

string
Last four digits of the card number for card, or of the bank account number for bank_account. Omitted when unknown. At most 4 characters.

hold

object required
The current risk hold on the payout.
Show child attributes

payments[].hold

active

boolean required
Whether a risk restriction blocks the payment now.

expiresOn

string<date-time>
When the blocking restriction ends: the latest expiry among the reviews that block the payment. Omitted when active is false, and when any blocking review has no expiry.

createdOn

string<date-time> required
When the payout was created.

expiresOn

string<date-time>
When the payout can no longer be claimed.

completedOn

string<date-time>
When the payout transfer settled. Present only once the payout has completed.
Requesttype: "request"
A request row in the provider-wide payment list. type is always request and paymentID is a request ID. Provider-wide rows have no direction: initiator is the requester and counterparty is the payer. A request moves money from the payer to the requester.

type

string<enum> required
Type discriminator.
Possible values: request

paymentID

string required
The request identifier.

amount

object required
Amount and currency.
Show child attributes

payments[].amount

value

string required
Decimal amount as a string.

currency

object required
ISO 4217 currency descriptor.
Show child attributes

payments[].amount.currency

code

string required
Uppercase 3-letter ISO 4217 currency code.

decimalPlaces

integer<uint8> required
Number of minor-unit decimal places for code. Required.

numericCode

string
ISO 4217 numeric currency code, if known. Informational only.

name

string
Human-readable currency name, if known. Informational only.

status

string<enum> required
Current lifecycle status of the request.
Possible values: created, authenticated, declined, cancelled, expired, paying, funded, disbursing, disbursement_failed, completed, reversing, reversal_failed, reversed, denied

referenceNumber

string required
Short support reference for the request.

memo

string
Free-form note attached by the requester.

initiator

object required
The participant who created the request.
Show child attributes

payments[].initiator

participantID

string required
The initiator’s participant ID.

externalID

string
Your external ID for the initiator.

displayName

string
The initiator’s current name (given + family). Omitted when unknown.

funding

object
The initiator’s instrument for this payment: the funding source a payout sends from, or the funding destination a request pays into. Omitted until the instrument is known.
Show child attributes

payments[].initiator.funding

fundingType

string<enum> required
Instrument discriminator.
Possible values: card, bank_account

displayName

string
Human-readable display label, such as the account nickname or card brand. Omitted when unknown.

last4

string
Last four digits of the card number for card, or of the bank account number for bank_account. Omitted when unknown. At most 4 characters.

counterparty

object required
The payer. Only the addressed phone is known until a payer authenticates; an open request has none.
Show child attributes

payments[].counterparty

displayName

string
Counterparty display name (given + family) when known.

phoneNumber

string
Counterparty phone number in E.164 form when known.

participantID

string
The party’s participant ID, once the party is bound to the payment. Omitted for an unbound party, such as the recipient of an unclaimed payout or the payer of an open request. The ID does not give access to the record of a participant that is not yours.

externalID

string
Your external ID for the party. Present only when the party is your participant.

funding

object
The instrument the party used for this payment. Omitted until the instrument is known.
Show child attributes

payments[].counterparty.funding

fundingType

string<enum> required
Instrument discriminator.
Possible values: card, bank_account

displayName

string
Human-readable display label, such as the account nickname or card brand. Omitted when unknown.

last4

string
Last four digits of the card number for card, or of the bank account number for bank_account. Omitted when unknown. At most 4 characters.

hold

object required
The current risk hold on the request.
Show child attributes

payments[].hold

active

boolean required
Whether a risk restriction blocks the payment now.

expiresOn

string<date-time>
When the blocking restriction ends: the latest expiry among the reviews that block the payment. Omitted when active is false, and when any blocking review has no expiry.

createdOn

string<date-time> required
When the request was created.

expiresOn

string<date-time>
When the request can no longer be paid.

completedOn

string<date-time>
When the request completed. Present only once completed.

nextCursor

string
Opaque cursor for the next page; absent on the last page.

hasMore

boolean required
Whether another page of results follows this one.