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 3 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. - Release 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, there is no supported action to transfer them back to client 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, and transfer to a third-party account. These processing codes must be associated with transaction types that will generate the transactions after the authorization.
At this time, you need to contact a Pismo representative to request creation of processing codes that are specific to balance impact for hold funds functionality.
Events
The platform generates the following two events whenever an authorization is successfully completed.
authorization-event-1
Endpoint | Event | API | Authorization type |
---|---|---|---|
Block amount | authorization-event-1 | hold-funds/block | BLOCK |
Unblock amount | authorization-event-1 | hold-funds/unblock | UNBLOCK |
Transfer held amount | authorization-event-1 | hold-funds/transfer | TRANSFER |
change_available-1
Endpoint | Event | API | Operation type | Impact |
---|---|---|---|---|
Block amount | change_available-1 | hold-funds/block | DEBIT | Debit available credit limit and/or available savings limit |
Unblock amount | change_available-1 | hold-funds/unblock | CREDIT | Credit available credit limit |
Transfer held amount | change_available-1 | hold-funds/transfer | DEBIT | Debit held funds |
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 limit
(and, if applicable, also from available_savings_account_limit
) to the held_funds
limit.
Find below 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",
"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.
Find below 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.
Find below 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"
}
}
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.
Find below 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.
Find below 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 4 days ago