Flag payment for review

POST
/providers/{providerID}/payments/{paymentID}/reviews

Place one of your payments in review with your reason. The review is pending from the response onward, and it holds the payment at its next admission step until you resolve it or the hold ends.

You can flag a payout in initiated, authorized, accepted, or payout_failed, and a request in created, authenticated, funded, or disbursement_failed. Returns a 409 with error code state-conflict when the payment is in any other state, because it has no admission step left. That problem carries no review member.

The review’s subject is the payment’s sender or requester, taken from the payment; the body does not select a subject.

The hold ends at the returned review’s holdExpiresOn. The hold ending does not resolve the review: the review stays pending until you resolve it.

A payment has one pending review at a time. Flagging again while one is pending returns a 409 with error code review-pending; that problem’s review member carries the existing review.

Returns 201 with the pending review. A payment that is missing or that belongs to another provider returns 404. Returns 422 when reason fails validation.

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

Request
cURL
curl -X POST https://api.moov.money/providers/{providerID}/payments/{paymentID}/reviews \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Payout amount above review threshold"
}'
Responses
201 400 401 403 404 409 422 429 503
The resource was successfully created.
{
  "review": {
    "assessmentLevel": "high",
    "assessmentScore": 0,
    "counterparty": {
      "displayName": "Jane Doe",
      "externalID": "C-2077",
      "funding": {
        "disabledOn": "2026-10-08T12:00:00Z",
        "displayName": "Checking",
        "fundingType": "bank_account",
        "last4": "5612",
        "providerSourceID": "src_01HF5J9ZKQT4RXP8M2VYBN3D"
      },
      "participantID": "counterparty-id_user",
      "phoneNumber": "+15555551234"
    },
    "createdOn": "2026-08-31T12:00:00Z",
    "flaggedParticipantID": "3v2whagmwvbujhwbt7v3nl6ffq_user",
    "flaggedRole": "sender",
    "initiator": {
      "displayName": "Jane Smith",
      "externalID": "C-1042",
      "funding": {
        "disabledOn": "2026-10-08T12:00:00Z",
        "displayName": "Checking",
        "fundingType": "bank_account",
        "last4": "5612",
        "providerSourceID": "src_01HF5J9ZKQT4RXP8M2VYBN3D"
      },
      "participantID": "participant-id_user",
      "status": "active"
    },
    "payout": {
      "amount": {
        "currency": {
          "code": "USD",
          "decimalPlaces": 2,
          "name": "US Dollar",
          "numericCode": "840"
        },
        "value": "100.00"
      },
      "payoutID": "pay_01HF5J9ZKQT4RXP8M2VYBN3D",
      "recipientName": "Jane Doe",
      "status": "initiated"
    },
    "reason": "Payout amount above review threshold",
    "request": {
      "amount": {
        "currency": {
          "code": "USD",
          "decimalPlaces": 2,
          "name": "US Dollar",
          "numericCode": "840"
        },
        "value": "100.00"
      },
      "createdOn": "2026-08-31T12:00:00Z",
      "requestID": "01HF5J9ZKQT4RXP8M2VYBN3D_req",
      "status": "created"
    },
    "reviewID": "prv_01HF5J9ZKQT4RXP8M2VYBN3D",
    "riskAssessmentID": "ras_01HF5J9ZKQT4RXP8M2VYBN3D",
    "status": "pending",
    "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 requested resource was not found.
Returned when the payment cannot be flagged: its state has no admission step left, or a review is already pending. The second case carries that review in the problem’s review member.
Response body application/problem+json
RFC 9457 Problem Details body of the 409 returned when a payment cannot be flagged. review is an extension member of the problem detail, present only when a pending review already exists.

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.

review

object
The existing pending review on this payment.
Show child attributes

review

reviewID

string required
Unique system-assigned review identifier.

type

string<enum> required
Kind of payment under review. payout carries the payout summary; request carries the request summary.
Possible values: payout, request

status

string<enum> required
Current review status.
Possible values: pending, approved, rejected

reason

string
Human-readable reason the payment was placed in review.

riskAssessmentID

string
Risk assessment that produced this review, when available.

payout

object
Payout summary for the queue.
Show child attributes

review.payout

payoutID

string required
Unique system-assigned payout identifier.

amount

object required
Payout amount and currency.
Show child attributes

review.payout.amount

value

string required
Decimal amount as a string.

currency

object required
ISO 4217 currency descriptor.
Show child attributes

review.payout.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.

recipientName

string
Recipient display name when known (given + family), otherwise omitted.

status

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

request

object
Request summary for the queue. Present when the subject is a request.
Show child attributes

review.request

requestID

string required
Unique system-assigned request identifier.

amount

object required
Request amount and currency.
Show child attributes

review.request.amount

value

string required
Decimal amount as a string.

currency

object required
ISO 4217 currency descriptor.
Show child attributes

review.request.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

memo

string
Requester-authored message, when present.

expiresOn

string<date-time> required
When the request expires. Always set: a request carries a fixed expiry from creation.

createdOn

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

createdOn

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

holdExpiresOn

string<date-time>
When the review hold stops blocking the payment. Omitted when the hold has no expiration. Expiration does not resolve the review.

resolvedOn

string<date-time>
When the review was resolved. Omitted while pending.

assessmentScore

number<double>
Known assessment score from 0 to 100. A recorded zero is a real score. Omitted when no score was recorded.

assessmentLevel

string<enum>
Recorded risk level of the linked assessment. Moov Money decides the review from this level, so use it to label the risk. Present whenever assessmentScore is present. Omitted when no level was recorded, for example when the risk check was unavailable.
Possible values: low, medium, high, very_high

flaggedParticipantID

string
Participant who was assessed for this review. Omitted when that subject is unknown.

flaggedRole

string<enum>
Recorded role of the assessed subject. Omitted when the role was not recorded.
Possible values: sender, requester, payer

initiator

object
The participant who started the payment: the sender of a payout or the requester of a request. A name comes from your relationship with the party or from the name recorded on the payment, never from the profile of a participant that is not yours. Fields that are not known are omitted. Omitted when no initiator is recorded.
Show child attributes

review.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.

status

string<enum>
The initiator’s current global participant status, read when you fetch the payment. It does not show your suspension; read the participant for that.
Possible values: active, disabled, pending, denied

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

review.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.

providerSourceID

string
The providerSourceID you registered for this funding source. Present only when the instrument is a registered funding source of your participant. Omitted for a payout that sent a provider source token with no registered funding source.

disabledOn

string<date-time>
When your participant’s registered funding source was removed. Omitted while the source is active, or when providerSourceID is omitted.

counterparty

object
The other party: the recipient of a payout or the payer of a request. The same name rule as initiator applies. Fields that are unbound or not known are omitted. Omitted when no counterparty is recorded.
Show child attributes

review.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

review.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.

providerSourceID

string
The providerSourceID you registered for this funding source. Present only when the instrument is a registered funding source of your participant. Omitted for a payout that sent a provider source token with no registered funding source.

disabledOn

string<date-time>
When your participant’s registered funding source was removed. Omitted while the source is active, or when providerSourceID is omitted.
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.
The request exceeded a rate limit. Retry after the whole number of seconds in Retry-After.
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.
The service is unavailable. The response has no body; retry your request later.

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.

paymentID

string required
Payout ID or request ID.

Request

application/json
Your reason for placing one of your payments in review.

reason

string [1 to 512] characters required
Free-form reason for the flag (1 to 512 characters).

Response

Response envelope for create review; the pending review is nested under review.

review

object required
The pending review summary.
Show child attributes

review

reviewID

string required
Unique system-assigned review identifier.

type

string<enum> required
Kind of payment under review. payout carries the payout summary; request carries the request summary.
Possible values: payout, request

status

string<enum> required
Current review status.
Possible values: pending, approved, rejected

reason

string
Human-readable reason the payment was placed in review.

riskAssessmentID

string
Risk assessment that produced this review, when available.

payout

object
Payout summary for the queue.
Show child attributes

review.payout

payoutID

string required
Unique system-assigned payout identifier.

amount

object required
Payout amount and currency.
Show child attributes

review.payout.amount

value

string required
Decimal amount as a string.

currency

object required
ISO 4217 currency descriptor.
Show child attributes

review.payout.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.

recipientName

string
Recipient display name when known (given + family), otherwise omitted.

status

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

request

object
Request summary for the queue. Present when the subject is a request.
Show child attributes

review.request

requestID

string required
Unique system-assigned request identifier.

amount

object required
Request amount and currency.
Show child attributes

review.request.amount

value

string required
Decimal amount as a string.

currency

object required
ISO 4217 currency descriptor.
Show child attributes

review.request.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

memo

string
Requester-authored message, when present.

expiresOn

string<date-time> required
When the request expires. Always set: a request carries a fixed expiry from creation.

createdOn

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

createdOn

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

holdExpiresOn

string<date-time>
When the review hold stops blocking the payment. Omitted when the hold has no expiration. Expiration does not resolve the review.

resolvedOn

string<date-time>
When the review was resolved. Omitted while pending.

assessmentScore

number<double>
Known assessment score from 0 to 100. A recorded zero is a real score. Omitted when no score was recorded.

assessmentLevel

string<enum>
Recorded risk level of the linked assessment. Moov Money decides the review from this level, so use it to label the risk. Present whenever assessmentScore is present. Omitted when no level was recorded, for example when the risk check was unavailable.
Possible values: low, medium, high, very_high

flaggedParticipantID

string
Participant who was assessed for this review. Omitted when that subject is unknown.

flaggedRole

string<enum>
Recorded role of the assessed subject. Omitted when the role was not recorded.
Possible values: sender, requester, payer

initiator

object
The participant who started the payment: the sender of a payout or the requester of a request. A name comes from your relationship with the party or from the name recorded on the payment, never from the profile of a participant that is not yours. Fields that are not known are omitted. Omitted when no initiator is recorded.
Show child attributes

review.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.

status

string<enum>
The initiator’s current global participant status, read when you fetch the payment. It does not show your suspension; read the participant for that.
Possible values: active, disabled, pending, denied

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

review.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.

providerSourceID

string
The providerSourceID you registered for this funding source. Present only when the instrument is a registered funding source of your participant. Omitted for a payout that sent a provider source token with no registered funding source.

disabledOn

string<date-time>
When your participant’s registered funding source was removed. Omitted while the source is active, or when providerSourceID is omitted.

counterparty

object
The other party: the recipient of a payout or the payer of a request. The same name rule as initiator applies. Fields that are unbound or not known are omitted. Omitted when no counterparty is recorded.
Show child attributes

review.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

review.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.

providerSourceID

string
The providerSourceID you registered for this funding source. Present only when the instrument is a registered funding source of your participant. Omitted for a payout that sent a provider source token with no registered funding source.

disabledOn

string<date-time>
When your participant’s registered funding source was removed. Omitted while the source is active, or when providerSourceID is omitted.