# Hold funds Hold funds feature allows you to prevent or limit financial movement of a specified amount of money out of the account. Usually, but not always, this occurs due to a legal action. While the funds are held, you can call the [List account limits](https://developers.pismo.io/pismo-docs/reference/get-v1-account-limit) endpoint to view the held funds amount. Held funds can't be withdrawn or moved until they are released back into the account or transferred to another account. There are four different actions available in the hold funds feature: * **Hold funds** ([Block amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-block) endpoint) transfers a specified amount of money out of the available account balance and holds it in reserve, so that the account holder no longer has access to it. The amount to be moved to held funds must be available in the client account (that means the sum of `available_credit_limit` and `available_savings_account_limit`), otherwise the operation is denied. The account must be active with the [account status](https://developers.pismo.io/pismo-docs/docs/accounts-overview#account-status) NORMAL or BLOCKED and the program type can be any type except CREDIT. * **Release held funds** ([Unblock amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-unblock) endpoint) releases the total or partial amount blocked from held funds balance to available balance. The amount released is fully moved to the `available_credit_limit` balance. The amount to be released must be less than or equal to the held funds, otherwise the operation is denied. * **Transfer held funds** ([Transfer held funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer) endpoint) transfers the total or partial retained balance from held funds out of the Pismo platform to an external third-party account. The amount to be transferred must be less than or equal to the held funds, otherwise the operation is denied. Once the held funds are transferred to a third-party account, you can cancel the transfer to place the held funds back into the client account. * **Cancel transfer of held funds** ([Cancel transfer of held funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer-cancel) endpoint) cancels transfer of a previously held amount from a Pismo account to an external third-party account. # Workflow The following diagram represents the hold funds transaction flow: Image showing the hold funds transaction flow. Note that you need to move the amount from the available balance to held funds and only then it is possible to transfer the amount to a third-party account. If you block an amount, the way to reverse it is using the unblock endpoint. If you transfer the blocked amount to a third-party account, the way to reverse it is to make a cash-in for the account and then block the amount once again. # Processing codes and transaction types Processing codes are used in each endpoint of this service: hold funds, release funds, transfer to a third-party account, and cancel transfer of held funds. These processing codes must be associated with specific operation types and transaction types that will generate the transactions after the authorization. When [creating a processing code](https://developers.pismo.io/pismo-docs/reference/post-processing-code-by-tenant) for each hold funds service, ensure that the `operation_type` is set to `HOLD_FUNDS`. For more information, see [Processing codes and transaction types](https://developers.pismo.io/pismo-docs/docs/processing-codes-and-transaction-types) and [Payments configurations](https://developers.pismo.io/pismo-docs/docs/payments-configurations). | Processing code | Balance impact | Processing code description | Transaction type | Transaction type description | Operation type | | :-------------- | :----------------------- | :---------------------------- | :--------------- | :---------------------------- | :------------- | | 999999 | **-1** (debit, cash-out) | Hold funds | 9999 | Hold funds | HOLD\_FUNDS | | 999999 | **1** (credit, cash-in) | Release funds | 9999 | Release funds | HOLD\_FUNDS | | 999999 | **-1** (debit, cash-out) | Transfer court account | 9999 | Transfer court account | HOLD\_FUNDS | | 999999 | **1** (credit, cash-in) | Cancel transfer court account | 9999 | Cancel transfer court account | HOLD\_FUNDS | # Events The platform generates the following two events whenever an authorization is successfully completed. ## Authorization created The following endpoints generate the [Authorization created](https://developers.pismo.io/events/docs/authorization-authorization-event-1) event. | Endpoint | Authorization type | | :------------------------------------------------------------------------------- | :------------------ | | [Block amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-block) | BLOCK | | [Unblock amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-unblock) | UNBLOCK | | [Transfer held amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer) | TRANSFER | | [Cancel transfer of held funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer-cancel) | HELD\_FUNDS\_CREDIT | ## Account balance changed The following endpoints generate the [Account balance changed](https://developers.pismo.io/events/docs/availables-change-available-1) event. | Endpoint | Operation type | Impact | | :------------------------------------------------------------------------------- | :------------- | :---------------------------------------------------------- | | [Block amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-block) | DEBIT | Debit available credit limit and/or available savings limit | | [Unblock amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-unblock) | CREDIT | Credit available credit limit | | [Transfer held amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer) | DEBIT | Debit held funds | | [Cancel transfer of held funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer-cancel) | CREDIT | Credit available credit limit | ## Transaction created The [Transaction created](https://developers.pismo.io/events/docs/transaction-creation-1) event occurs asynchronously when the platform creates a transaction after the successful authorization. # Example of hold funds actions ## Hold funds You can block a specific amount using the [Block amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-block) endpoint. Once blocked, the corresponding amount is moved from the `available_credit_limit` to the `held_funds` limit. By default, the Pismo platform performs account balance validation to ensure the account has sufficient funds to block an amount. You also have the option to force this operation without performing account balance validation. When you set `skip_balance_validation` to `true`, the platform skips account balance validation and blocks the amount regardless whether the account has a sufficient available balance. In this case, if the account doesn’t have a sufficient balance, its available balance will be in a negative state and any future usual debit operations will not be possible until the account receives enough credit. Below is a sample of a request to hold funds. `POST v1/payments/hold-funds/block` ```json { "account_id": 111507785, "tracking_id":"b970c8a9-5ec9-4e46-8c0d-f411e0bd6ce7", "amount":500.45, "processing_code":283503, "description":"Legal block", "skip_balance_validation": false, "metadata":{ "message": "Block requested" } } ``` ## Release funds You can release a specific amount using the [Unblock amount](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-unblock) endpoint. Once unblocked, the amount is moved back to the `available_credit_limit` limit. Below is a sample of a request to release funds. `POST v1/payments/hold-funds/unblock` ```json { "account_id": 111507785, "tracking_id":"c852a2b1-9ad0-5a57-9d1e-a512f1ae7df8", "amount":30.22, "processing_code":283506, "description":"Legal unblock", "metadata":{ "message":"Unblock requested" } } ``` ## Transfer held funds To perform a transfer of held funds to an external account, use the [Transfer held funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer) endpoint. Once transferred, the amount is removed from the `held_funds` limit. > 📘 > > You can only transfer an amount that was previously blocked. Below is a sample of a request to transfer held funds. `POST v1/payments/hold-funds/transfer` ```json { "account_id": 111507785, "tracking_id":"d853b3c2-1ba2-6b58-0e2a-b513a2bf8ea9", "amount":100.63, "processing_code":283506, "description":"Transfer to judicial court", "metadata":{ "message":"Transfer requested", "transfer_to":"International Bank" } } ``` ## Cancel transfer of held funds To perform a transfer of held funds to an external account, use the [Cancel transfer of held funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-hold-funds-transfer-cancel) endpoint. Below is a sample of a request to cancel transfer of held funds. `POST v1/payments/hold-funds/transfer/cancel` ```json { "tracking_id": "be68db6e-8da0-4761-8632-6a51857bd123", "account_id": 101, "amount": 12.13, "processing_code": "004000", "description": "Blocked value", "metadata": { "my-custom-key": "my-custom-value" } } ``` # Get account balances ## Check current account balance To find out the amount of held funds, you need to get its account limits. You can do this by checking the field `held_funds` in the response of the [List account limits](https://developers.pismo.io/pismo-docs/reference/get-v1-account-limit) endpoint. Below is a sample of response with the current account balances. `GET v1/accounts/:accountId/limits` ```json { "available_savings_account_limit": 9596.85, "available_credit_limit": 7845.98, "held_funds": 2285.72 } ``` For more information, see the [Account limits](https://developers.pismo.io/pismo-docs/docs/working-with-limits-objects) guide. ## Check end-of-day balance To find out the held funds at the end of a specific day, you need to check the field `held_funds` in the response of the [Get daily account balance limits](https://developers.pismo.io/pismo-docs/reference/get-v1-account-balance) endpoint. Below is a sample of response with the current account balances. `GET ledger/v1/accounts/{accountId}/daily-balances` ```json { "account_id": "2412", "org_id": "08102A0B-D4F8-42A2-8B0E-2052D05577D7", "ref_date": "2023-02-01", "available_credit_limit": 2997.41, "available_withdrawal_credit": 411.05, "available_total_installment_credit": 455.45, "available_savings_account_limit": 311.08, "held_funds": 311.08 }, ``` For more information, see the [Daily account balances](https://developers.pismo.io/pismo-docs/docs/accounts-overview#get-daily-account-balance-limits) guide.