Claim sandbox payout

POST
/providers/{providerID}/sandbox/payouts/{payoutID}/claims

Claim a sandbox payout as the participant in the body, using the payment method the sandbox card token created. The call runs the payout claim flow and returns the claim outcome.

A committed retry returns the stored result at its original status, even after the transfer resolves. To observe the payout’s current lifecycle status, list the participant’s payments with GET /providers/{providerID}/participants/{participantID}/payments. Returns 200 with status: completed or status: payout_failed, and 202 with status: claiming when the transfer outcome is not known yet.

Send X-Idempotency-Key to identify the attempt. Replaying the key with a changed payout ID or a changed request body returns 409 with problem type idempotency-key-reused; an identical request that is still active returns 409 with problem type idempotency-request-in-progress. The reservation covers the authenticated caller account, the target provider, and this action. Both problems use application/problem+json.

Returns 400 when the body is malformed or the key is missing. Returns 401 when your credentials are missing or invalid. Returns 403 when the target is a production provider. Returns 404 when the payout is not found or belongs to another provider, or when the participant does not belong to the provider or the payment method does not belong to the participant.

Sandbox fraud fixtures. The sandbox fraud provider returns a fixed result for these USD amounts, and it applies no rounding before matching:

  • 10.00: low risk, with a present score of zero.
  • 10.01: medium risk, placed in review.
  • 10.02: high risk, denied without a rail submission.
  • 10.03: the fraud vendor is unavailable, and the configured outage policy applies.

Two participant identity fixtures also apply, matched against the authorized participant’s normalized stored email:

Every other valid amount or currency returns low risk. A participant with no fixture email, including a phone-only participant, falls back to a clean identity. Repeated fixture inputs give the same result. The fixtures apply to sandbox providers only; production uses the normal fraud provider.

Auth: API key or bearer token. Application callers must use an application credential authorized for the provider in the path. An affiliated integrator needs the /accounts/{providerID}/moov-money-participants.write and /accounts/{providerID}/transfers.write grants from the FI.

Request
cURL
curl -X POST https://api.moov.money/providers/{providerID}/sandbox/payouts/{payoutID}/claims \
  -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 '{
  "participantID": "3v2whagmwvbujhwbt7v3nl6ffq_user",
  "paymentMethodID": "pm_01HF5J9ZKQT4RXP8M2VYBN3D"
}'
Responses
200 202 400 401 403 404 409 429 503
The request completed successfully.
{
  "payout": {
    "authorizationCode": "AUTH123",
    "claimedOn": "2026-10-19T15:00:00Z",
    "completedOn": "2026-10-19T15:00:05Z",
    "failedOn": "2026-10-19T15:00:05Z",
    "failureReason": "issuer_decline",
    "institutionName": "Example Bank",
    "paymentMethod": "Visa 1234",
    "paymentMethodType": "push-to-card",
    "status": "completed",
    "transferID": "transfer-id"
  }
}
Accepted response for a sandbox payout claim whose transfer outcome is not known yet. The attempt is nested under payout and stays claiming.
{
  "payout": {
    "authorizationCode": "AUTH123",
    "claimedOn": "2026-10-19T15:00:00Z",
    "completedOn": "2026-10-19T15:00:05Z",
    "failedOn": "2026-10-19T15:00:05Z",
    "failureReason": "issuer_decline",
    "institutionName": "Example Bank",
    "paymentMethod": "Visa 1234",
    "paymentMethodType": "push-to-card",
    "status": "completed",
    "transferID": "transfer-id"
  }
}
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 sandbox action’s X-Idempotency-Key was replayed with a changed payment ID or a changed request body, or when an identical request with the same key is still active. A committed retry returns the original attempt at its original status instead.
Response body application/problem+json
RFC 9457 Problem Details body of the 409 returned by a sandbox claim, pay, or decline replay. type is https://api.moov.money/errors#idempotency-key-reused when the key was replayed with a changed payment ID or a changed request body, or https://api.moov.money/errors#idempotency-request-in-progress when an identical request with the same key is still active.

detail

string
Human-readable explanation of this specific occurrence.

type

string<enum> required
The problem type URI.
Possible values: https://api.moov.money/errors#idempotency-key-reused, https://api.moov.money/errors#idempotency-request-in-progress

title

string required
Short human-readable name of the problem type.

status

integer<int32> required
The HTTP status code of this response, always 409.
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.

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.

payoutID

string required
Identifier of the payout to claim.

Request

application/json
Body for the sandbox payout claim route. The claim runs as the participant in participantID against the payment method in paymentMethodID.

participantID

string required
The recipient participant whose claim is simulated. The participant must belong to the provider in the path.

paymentMethodID

string required
Moov payment method ID to push the payout to. It must belong to the participant’s Moov account. Create it with the sandbox card token, then pass the returned paymentMethodID.

Response

Response envelope for the sandbox payout claim route; the attempt is nested under payout.

payout

object required
The claim attempt.
Show child attributes

payout

transferID

string
Moov transfer ID of the attempt, present once a transfer is known. Omitted while status: claiming.

status

string<enum> required
Attempt status.
Possible values: completed, payout_failed, claiming

claimedOn

string<date-time>
Present when status: completed.

completedOn

string<date-time>
Present when status: completed.

authorizationCode

string
Present when status: completed. Network authorization code for approved card payouts.

paymentMethod

string
Present when status: completed. Recipient-safe display string for the payment method funds were sent to.

paymentMethodType

string
Present when status: completed. Structured payment-method type.

institutionName

string
Present when status: completed. Card issuer or card-brand fallback.

failedOn

string<date-time>
Present when status: payout_failed.

failureReason

string
Machine-readable failure reason when status: payout_failed.