Confirm a money-moving action with PIN (and, where required, an authenticator code)

Mint a single-use, short-lived confirmation that authorizes the authenticated identity to perform a specific money-moving action (e.g. approving a payout, deciding a maker-checker action, issuing a card). The identity_id and entity_id are always taken from the authenticated JWT session — they can never be supplied in the request body, even if included. The confirmation's required factor tier (pin_only or pin_and_authenticator) is resolved server-side per action_type, starting from a platform default and optionally overridden to something stricter (never weaker) at the entity level. A valid, active secure-pin MFA method is always required; when the resolved tier is pin_and_authenticator, an active authenticator MFA method and a valid authenticator_code are also required. Each PIN/authenticator verification is rate-limited independently — repeated failed attempts against the same MFA method within a rolling window return a 429 and block further attempts until the window clears. On success, the returned confirmation is valid for a fixed TTL (5 minutes by default, configurable via MONEY_ACTION_CONFIRMATION_TTL_MS) and can be consumed exactly once by including its id as money_action_confirmation_id on the action it was created for (e.g. POST /payout-intents, PATCH /maker-checker-action-decisions/:id). Passing reference_id binds the confirmation to a specific existing resource (e.g. a payout_intent_id) so it can only be consumed against that resource; omit it for actions that don't yet have a resource id at confirmation time (e.g. payout, card_issuance).

Responses

🟢201

application/json

The PIN (and, where required, authenticator code) were verified successfully. A single-use confirmation was minted for the given action_type, valid until expires_at; pass its id as money_action_confirmation_id on the action it was created for before it expires.

Bodyapplication/json

🟠400

🟠401

🟠403

🟠429

{ "message": "Money action confirmation created successfully", "status": "success", "data": { "id": "01HN8S1M4X2Q7V9K3D6B5F8CDE", "entity_id": "01H9ZK3M8T5Y2V7Q1N4B6C0DEF", "action_type": "payout", "reference_id": null, "tier": "pin_only", "status": "active", "expires_at": 1722869820000, "created": 1722869520000 } }

Confirm a money-moving action with PIN (and, where required, an authenticator code)

Request

Responses