Operations

Register users, work payments held for review, cancel when someone asks, and tie Moov’s ids back to the holds on your core.

Participants #

Every user who will send or request must be registered once, typically when they sign up or when you first offer them Moov Money. Registering a participant and minting their token is one flow, covered in sender authentication.

What matters day to day is the status a participant is in:

Status	What it means
`pending`	The signup fraud check is still running. Cannot mint a token.
`active`	Cleared. Can mint a token and use Moov Money.
`denied`	The signup check refused them. Cannot mint a token.
`disabled`	You turned them off. Cannot mint a token.

Creation is asynchronous, so a participant lands in pending first. Poll GET /providers/{providerID}/participants/{participantID} rather than minting a token immediately; a request against a still-pending participant returns 403.

A disabled participant is the off switch without closing the deposit account: token minting stops, and any token already issued expires within the hour on its own. Disabling is done through your Moov contact today; the simplest immediate control you hold yourself is to stop minting tokens for that user.

Reviews #

Not every payment that looks off is declined. Some are placed in a manual review hold. The sender sees that the payment is under review; the other person cannot claim until you resolve it, or until the hold lapses. Field-by-field: list reviews, get review, resolve.

Nothing pushes a new review to you: poll the pending queue on a schedule tight enough that a held payment is worked well before its hold lapses. List the queue (defaults to pending):

curl "https://api.moov.money/providers/$PROVIDER_ID/reviews?status=pending" \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET"

Each item carries a reason, a risk-assessment id, timestamps, and a thin payout summary (amount, recipient name, status). Fetch GET /providers/{providerID}/reviews/{reviewID} for the full payout when a reviewer needs it.

Resolve with approved or rejected:

curl -X POST "https://api.moov.money/providers/$PROVIDER_ID/reviews/$REVIEW_ID/resolutions" \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"resolution":"approved","notes":"Known payee, user confirmed by phone"}'

Approve: the claim may proceed once no pending reviews remain.
Reject: recorded as fraudulent feedback. Rejecting the last pending review on a cancellable payment (authorized or accepted) cancels it. Your release endpoint is called so the hold comes off.

Re-resolving an already-resolved review returns 409. Reviews are scoped to your institution; an id from someone else’s queue looks like a 404.

Cancellations and expiry #

Your user can cancel a payment until it’s claimed, and a request until it’s paid. Unclaimed payments expire after 10 days on their own. Unpaid requests expire after 30 days by default. Cancelling happens in the SDK, from the sender’s own session, the same place the payment was created. You don’t call anything to cancel on their behalf.

Cancel and expiry both end in release on your ledger. You don’t need a back-office job to unstick holds for expired claims; Moov calls you. (Card-funded programs get the funding card refunded instead.)

If a recipient’s claim attempt fails (issuer decline, timeout), they can retry with the same or a different card. That’s retryable on their side (payout_failed). It is not a release. The hold stays until a successful claim captures it, or until cancel/expiry releases it.

Notifications #

Moov messages the other person over RCS and email. You don’t send those. That’s deliberate: a branded, verifiable message is harder to phish than an SMS you composed. Your app can still show the link and let the user share it (Messages, copy, QR). The hosted page is the same either way.

Moov will never ask a user to pay a fee to “unlock” or “release” a payment. If someone claims Moov did, it’s a scam; point them at your trust & safety runbook and the consumer help center.

Reconciliation #

For every payment, persist:

Id	Source	Use
Payout ID	Your authorize callback (`payoutID`)	Moov’s primary key
`holdReference`	Your authorize response	Ties the hold on your core
`captureReference` or `releaseReference`	Your capture or release response	How the hold ended
Idempotency key	On every funding call	Safe retries
Network authorization code	Completed claim	Card-side trace

A hold ends in exactly one of capture or release. If your reports show a hold that is neither, the funding call didn’t land. Check retries and idempotency.

For every paid request, persist the request ID and the creditReference you return on credit account. You will not have the payer’s PAN.

The money-movement side lives in your Moov Dashboard: every wallet transaction (each push out to a recipient, each pull in from a payer, and the daily sweep) is listed there, and Moov generates statements for your institution. Reconcile by tying the references above to those wallet transactions: the payout and its OCT, the request and its AFT, the sweep and your GL entry. Card disputes are also worked in the Dashboard.

Funding sources #

Register each account a user can pay from on the participant before the SDK lists it. See configuration and create funding source.

Launching #

A workable sequence:

Follow the quick start through one payment end to end, including the review-resolution path.
Theme the SDK. Confirm the hosted page and RCS/email carry your name.
Set shortName so descriptors look like you.
Open to a tight group (employees, then a low-limit cohort).
Work every review for the first weeks. Adjust groups based on actual activity, not a planned rollout slide.

Moov provides device intelligence, messaging, and the hosted page as part of the program. What you need in-house is someone who owns the review queue and the limit groups.