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 and available_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

change_available-1

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.