Preview

Suspend participant

POST
/providers/{providerID}/participants/{participantID}/suspensions

Suspend your provider’s relationship with a participant. From the next attempt, the participant cannot send payouts or create requests through your provider, including from a session that is already open. Money that a payer sends for one of their existing requests is not paid out to them until you reactivate them or the request expires. Signing in, payments that already started, reversals, and refunds are not affected. The suspension does not change the global participant status or the participant’s relationships with other providers.

Send the relationship.versionID from your latest participant read as expectedVersionID. Returns a 409 version-conflict problem when the value is stale. Read the participant again before you retry. Returns a 409 state-conflict problem when the participant is already suspended. Both 409 problems use the same status code, so check type to tell them apart.

Returns 201 with the committed relationship state. Returns 422 when reasonCode or expectedVersionID is missing, when reasonCode is unrecognized, when reasonCode is other and note is missing, or when note is empty or longer than 512 characters. Returns 404 when neither key matches a participant within your provider.

Send an X-Idempotency-Key header so a retried suspension is processed once. The server echoes that header on the response. Replaying the same key with the same request body within 24 hours returns the original 201 response. Replaying it with a different body returns a 409 with error code idempotency-key-reused. Returns a 409 with error code idempotency-request-in-progress when a request with this key is still running. Returns 400 when the header is missing or malformed.

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

Request
cURL
curl -X POST https://api.moov.money/providers/{providerID}/participants/{participantID}/suspensions \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedVersionID": "relationship-v3",
  "note": "Unusual activity reported by the customer",
  "reasonCode": "suspected-fraud"
}'
Responses
201 400 401 403 404 409 422
The resource was successfully created.
{
  "relationship": {
    "actor": {
      "applicationKeyID": "5f0c3b2a-8d4e-4b7a-9c1f-2e6d7a8b9c0d",
      "callingAccountID": "acc_01HF5J9ZKQT4RXP8M2VYBN3D",
      "kind": "user",
      "userID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43"
    },
    "externalID": "customer-abc-123",
    "note": "Unusual activity reported by the customer",
    "participantID": "3v2whagmwvbujhwbt7v3nl6ffq_user",
    "reasonCode": "suspected-fraud",
    "suspended": false,
    "suspendedOn": "2026-10-06T16:00:00Z",
    "versionID": "relationship-v3"
  }
}
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.
The request conflicts with the current state of the target resource.
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.

X-Idempotency-Key

string required
Client-supplied key that identifies this create request, 1 to 255 characters. Send the header once. Retries with the same key are processed once for 24 hours after the request completes.

Path parameters

providerID

string required
Your provider account ID.

participantID

string required
The participant’s participantID, or your externalID for them. Both resolve to the same participant.

Request

application/json
A suspension of your provider’s relationship with a participant. A reasonCode of other requires a note.

reasonCode

string<enum> required
Why you are suspending the participant.
Possible values: suspected-fraud, account-compromise, customer-request, compliance-review, legal-hold, policy-violation, other

note

string [1 to 512] characters
Explanation of the suspension, 1 to 512 characters. Required when reasonCode is other.

expectedVersionID

string required
The relationship.versionID from your latest participant read. A stale value returns a 409 version-conflict problem.

Response

Response envelope for suspend and reactivate; the relationship is nested under relationship.

relationship

object required
The committed relationship state.
Show child attributes

relationship

participantID

string required
Unique identifier for the participant.

externalID

string required
Your identifier for the participant.

suspended

boolean required
Whether you suspended this participant. A suspended participant cannot send payouts or create requests through your provider. Money that a payer sends for one of their existing requests is not paid out to them until you reactivate them or the request expires. Signing in, payments that already started, reversals, and refunds are not affected.

versionID

string required
Opaque version of the relationship state. Send it as expectedVersionID on your next suspension or reactivation. It is not a relationship ID.

suspendedOn

string<date-time>
When the current suspension took effect.

reasonCode

string<enum>
Why you suspended the participant. Present while suspended is true.
Possible values: suspected-fraud, account-compromise, customer-request, compliance-review, legal-hold, policy-violation, other

note

string
Note supplied with the current suspension. Omitted when none was supplied.

actor

object
Who made the current suspension.
Show child attributes

relationship.actor

kind

string<enum> required
Kind of actor.
Possible values: user, application, system

userID

string
Moov user ID of the person who acted. Present when kind is user. Omitted when kind is application or system.

applicationKeyID

string
ID of the application key that acted. Present when kind is application. Omitted when kind is user or system.

callingAccountID

string
Moov account ID that the actor acted from. Present when kind is user or application. Omitted when kind is system.