Record a decision on a maker-checker action

Records the authenticated identity's approval, rejection, or send-back for a pending maker-checker action, identified by its reference_id and type within the caller's entity. The entity_id and identity_id are derived from the authenticated session, not the request body. The service enforces strict approval-order sequencing: a decision is only accepted from the identity whose approval_order matches the next unrecorded step in the action's approver list, and only while the action's overall status is still pending. Rejecting or sending back an action immediately moves its status to rejected or sent_back respectively and requires a status_reason. Approving records the identity's approval and, once every configured approver has approved, automatically advances the action's status to approved. Once the action leaves pending, a background job is queued to carry out any downstream side effects associated with that outcome.

This endpoint is gated by the verify-money-action-confirmation middleware: every request must also carry a money_action_confirmation_id obtained from POST /money-action-confirmations (minted with action_type approval_decision) after the caller has proven their PIN, and authenticator code where required. The confirmation must be unused, unexpired, issued to the same identity and entity, and if it carries a reference_id, that value must match this request's reference_id. It is consumed as part of processing this request. This requirement only applies to JWT-authenticated (human) callers.

Responses

🟢201

application/json

The decision was recorded successfully. The response reflects the maker-checker action's state after applying this decision, including whether the action has now reached a final approved, rejected, or sent_back status.

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

curl --location '/maker-checker-action-decisions' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "reference_id": "01J9XA3F7QW4K3C8L5M9T6P1NX", "type": "payout", "decision": "approved", "money_action_confirmation_id": "01JMAC1234567890ABCDEFGHI" }'

{ "message": "Maker-checker action decision recorded successfully", "status": "success", "data": { "id": "01J9XB1M4K6NQ7T2V6S9D1R3YZ", "entity_id": "01J9X0G3K8V7MZPY2Q1R5T6N4A", "reference_id": "01J9XA3F7QW4K3C8L5M9T6P1NX", "type": "payout", "maker_checker_group_id": "01J9X0W8M4K6NQ7T2V6S9D1R3Y", "requester_identity_id": "01J9X0M7ZYXW9876543210ABC", "requester": { "id": "01J9X0M7ZYXW9876543210ABC", "name": "Ngozi Eze", "email": "ngozi.eze@acme.ng" }, "approvers": [ { "approval_order": 1, "identity_id": "01J9X0M7G3SRNQ8Y2P4K6T1A5C", "identity": { "id": "01J9X0M7G3SRNQ8Y2P4K6T1A5C", "name": "Ada Okafor", "email": "ada.okafor@acme.ng" } }, { "approval_order": 2, "identity_id": "01J9X0R2F7QW4K3C8L5M9T6P1N", "identity": { "id": "01J9X0R2F7QW4K3C8L5M9T6P1N", "name": "Kehinde Adebayo", "email": "kehinde.adebayo@acme.ng" } } ], "approvals": [ { "identity_id": "01J9X0M7G3SRNQ8Y2P4K6T1A5C", "name": "Ada Okafor", "email": "ada.okafor@acme.ng", "status": "approved", "status_reason": null } ], "status": "pending", "status_reason": null, "amount": 25000, "currency": "NGN", "counterparty": "01J9XCPTY1234567890ABCDEF", "is_requester": false, "created": 1757702400000, "updated": 1757788800000 } }

Record a decision on a maker-checker action

Request

Responses