Capture Reason for Hold and Release Actions

What's New?

Capturing a reason for every hold and release action gives your team a clear, consistent record of why a transaction or submerchant was held or released, and who made the decision. Every hold and release action now captures a reason, notes, initiating user, and date and time stamp.

When holding or releasing an item over the API, you pass the reason text directly on each call, manage the tenant's saved reasons through a new set of endpoints, and read back the full history for a transaction or submerchant.

These workflows are available via the API as described below and the Backoffice interface. For those working in the UI, see Capture Reason for Hold and Release Actions.

NOTE: Hold/release history is captured going forward. User and system actions submitted before this feature release do not include reasons or notes.

New Endpoints

A new Hold/Release Reasons resource provides CRUD over your tenant's curated reason list, plus two read-only endpoints for the audit trail.

Resource	Endpoint	Purpose
Hold/Release Reasons	`GET` Review Hold/Release Reasons	List a tenant's saved reasons.
Hold/Release Reasons	`GET` Review a Hold/Release Reason by ID	Read a single reason.
Hold/Release Reasons	`POST` Create a Hold/Release Reason	Create a new reason.
Hold/Release Reasons	`PUT` Update a Hold/Release Reason	Update a reason's text or active flag.
Hold/Release Reasons	`DELETE` Deactivate a Reason	Deactivate a reason.
Transactions	`GET` Review Transaction Hold/Release History	Read a transaction's hold and release history.
Merchants	`GET` Review Submerchant Hold/Release History	Read a submerchant's hold and release history.

Hold/Release Request Changes

All existing hold/release endpoints — single and bulk, across transactions, submerchants, and pending deposits in the Funding Process Center — now accept an optional HoldReleaseRequest body and the X-Initiated-By header.

Field	Type	Description
`reasonText`	`string`	Max 200 characters. Required when the Require Hold/Release Reason option is enabled for the tenant.
`notes`	`string`	Free-text. Optional. Max 2,000 characters.
`initiatedByUserId`	`integer`	Optional Backoffice user id to attribute the action to.

Header	Description
`X-Initiated-By`	Optional display string. Defaults to `"API User"` when absent.

Reading the Audit Trail

Both history endpoints return an array of hold/release events, newest first — the same entries shown in the Hold/Release Activity section on a transaction or submerchant in Backoffice:

Example

[
  {
    "id": 12345,
    "entityType": "Transaction",
    "action": "Hold",
    "reasonId": 7,
    "reasonText": "Chargeback under review",
    "notes": "Awaiting processor confirmation",
    "initiatedBy": "[email protected]",
    "initiatedByUserId": 4291,
    "initiatedAt": "2026-06-10T15:42:11Z"
  }
]