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

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.

change_available-1

The following endpoints generate the change_available-1 event.

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.