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 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 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
andavailable_savings_account_limit
), otherwise the operation is denied. The account must be active with the account status NORMAL or BLOCKED and the program type can be any type except CREDIT. - Release held funds (Unblock amount 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 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 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:
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 for each hold funds service, ensure that the operation_type
is set to HOLD_FUNDS
.
For more information, see Processing codes and transaction types and 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-event-1
The following endpoints generate the authorization-event-1 event.
Endpoint | Authorization type |
---|---|
Block amount | BLOCK |
Unblock amount | UNBLOCK |
Transfer held amount | TRANSFER |
Cancel transfer of held funds | HELD_FUNDS_CREDIT |
change_available-1
The following endpoints generate the change_available-1 event.
Endpoint | Operation type | Impact |
---|---|---|
Block amount | DEBIT | Debit available credit limit and/or available savings limit |
Unblock amount | CREDIT | Credit available credit limit |
Transfer held amount | DEBIT | Debit held funds |
Cancel transfer of held funds | CREDIT | Credit available credit limit |
creation-1
The 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 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
{
"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 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
{
"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 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
{
"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 endpoint.
Below is a sample of a request to cancel transfer of held funds.
POST v1/payments/hold-funds/transfer/cancel
{
"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 endpoint.
Below is a sample of response with the current account balances.
GET v1/accounts/:accountId/limits
{
"available_savings_account_limit": 9596.85,
"available_credit_limit": 7845.98,
"held_funds": 2285.72
}
For more information, see the Account limits 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 endpoint.
Below is a sample of response with the current account balances.
GET ledger/v1/accounts/{accountId}/daily-balances
{
"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 guide.
Updated 5 months ago