Transaction Holds

A transaction hold refers to a kind of transaction authorization in which the balance is unavailable to the account holder until it is either settled or cancelled.

Transaction holds are a flexible tool that can be useful or necessary for several common processes and flows, such as:

• Single Euro Payments Area (SEPA) instant payment flows
• check settlements in the US or other countries
• multicurrency settlements
• other scenarios where a hold must be posted prior to an actual transaction

For any type of deposit account, you can create, settle, reverse, and retrieve authorization holds directly on the account. Once you create a hold, the hold balance on the deposit account increases by the specified amount, and the available balance decreases by the specified amount.

Transaction holds are available via requests to the Mambu v2 API. For more information, see GET /deposits/{depositAccountId}/authorizationholds.

Required permissions

To perform any action relating to holds on deposit accounts, you must have the following permissions in the Holds (via account ID) category assigned to your user account:

• Create Holds (CREATE_HOLDS)
• View Holds (VIEW_HOLDS)
• Update Holds (UPDATE_HOLDS)
• Delete Holds (DELETE_HOLDS)

Posting transaction holds

You can post a debit or credit transaction hold to any type of deposit account by making a POST request to the /deposits/{depositAccountId}/authorizationholds endpoint.

Here are some important things to consider when posting transaction holds:

• Transaction holds can be done against all types of deposit accounts, regardless of the overdraft settings.
• The externalReferenceId field is mandatory and must be a unique 32 characters.
• The specified amount cannot be greater than the available balance of the deposit account, or the transaction hold will fail.
• The creditDebitIndicator field is mandatory. Enter either DBIT or CRDT.
• The source field specifies the source of the hold: CARD or ACCOUNT.
• For credit-type holds, the amount is validated against maximum deposit value.
• The hold will be registered in Pending state.
• Holds never expire.

Settling transaction holds

Transaction holds are settled with withdrawal or deposit transactions.

A debit-type transaction hold in the Pending state can be settled by making a POST request to the /deposits/{depositAccountId}/withdrawal-transactions endpoint.

A credit-type transaction hold in the Pending state can be settled by making a POST request to the /deposits/{depositAccountId}/deposit-transactions endpoint.

Here are some important things to consider when making a withdrawal to settle a transaction hold:

• The amount cannot differ from the amount of the authorization hold, or the action will fail.
• The valueDate field is not supported in cases where the holdExternalReferenceId is specified in the action. If the valueDate is specified, the request will fail.
• Once the withdrawal to settle the hold is made:
  • For debit-type holds, the hold balance on the deposit account will decrease by the specified amount, the available balance will remain the same, and the total balance will decrease.
  • For credit-type holds, the forwardBalance on the deposit account will increase by the specified amount. Available balance will not be increased.
• Once the settlement is made, the hold identified by holdExternalReferenceId is updated to Settled.

Reversing transaction holds

You can reverse any transaction hold that is in the Pending state by making a DELETE request to the /deposits/{depositAccountId}/authorizationholds/{authorizationHoldExternalReferenceId} endpoint.

Once the request is successfully made, the hold balance on the deposit account decreases by the amount of the reversed hold, the available balance increases by the same amount, and the hold transaction goes into the Reversed state.