Claim sandbox payout
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:
[email protected]: high signup risk.[email protected]: an AML hit.
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.
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"
}'{
"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"
}
}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"
}
}Response body application/problem+json
application/problem+json.
From v2026.10.00, every error response that has a body uses this schema.type
string
requiredhttps://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
requiredstatus
integer<int32>
requireddetail
stringinstance
stringerrors
array<object>Show child attributes
errors[]
pointer
string
requireddetail
string
requiredX-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
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
stringtype
string<enum>
requiredhttps://api.moov.money/errors#idempotency-key-reused,
https://api.moov.money/errors#idempotency-request-in-progresstitle
string
requiredstatus
integer<int32>
requiredRetry-After.Response body application/problem+json
application/problem+json.
From v2026.10.00, every error response that has a body uses this schema.type
string
requiredhttps://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
requiredstatus
integer<int32>
requireddetail
stringinstance
stringerrors
array<object>Show child attributes
errors[]
pointer
string
requireddetail
string
requiredHeaders
X-Moov-Version
stringv2026.10.00). When omitted, the server applies its default version.X-Idempotency-Key
string
requiredPath parameters
providerID
string
requiredpayoutID
string
requiredRequest
participantID against the payment method in paymentMethodID.participantID
string
requiredpaymentMethodID
string
requiredpaymentMethodID.Response
payout.payout
object
requiredShow child attributes
payout
transferID
stringstatus: claiming.status
string<enum>
requiredcompleted,
payout_failed,
claimingclaimedOn
string<date-time>status: completed.completedOn
string<date-time>status: completed.authorizationCode
stringstatus: completed. Network authorization code for approved card payouts.paymentMethod
stringstatus: completed. Recipient-safe display string for the payment method funds were sent to.paymentMethodType
stringstatus: completed. Structured payment-method type.institutionName
stringstatus: completed. Card issuer or card-brand fallback.failedOn
string<date-time>status: payout_failed.failureReason
stringstatus: payout_failed.