Configuring the Escrow Account for subaccounts

Configure the Escrow Account individually for a subaccount or set a default configuration for the entire subaccount structure.

After enablement, new charges and installments received by the configured subaccounts start following the retention flow for the period defined in daysToExpire.

Choose the configuration type

The default configuration continues to be applied to new subaccounts until it is changed again.

Before you start

Check that:

• the Escrow Account is available for your account;
• the subaccount already exists, if you use the individual configuration;
• you have the id of the subaccount that will be configured individually;
• the retention period and who is responsible for the fee are defined for the scenario.

1. Configure a specific subaccount

Use this flow when a subaccount needs its own configuration.

POST /v3/accounts/{id}/escrow

Example:

{
"enabled": true,
"isFeePayer": true,
"daysToExpire": 10
}

The fields used define:

• enabled: enables or disables the Escrow Account;
• isFeePayer: defines whether the subaccount itself will be responsible for the Escrow Account fee. If not provided or set to false, the fee will be charged to the main account;
• daysToExpire: defines the number of days until the guarantee expires and the amount is automatically released.

See the Save or update Escrow Account configuration for subaccount endpoint.

How to validate

The request must return 200 OK.

If you need to confirm the configuration registered for the subaccount, use:

GET /v3/accounts/{id}/escrow

See the Retrieve Escrow Account configuration for subaccount endpoint.

2. Define a default configuration

Use the default configuration when all subaccounts must follow the same Escrow Account rules.

POST /v3/accounts/escrow

Example:

{
"enabled": true,
"isFeePayer": true,
"daysToExpire": 10
}

The configuration will be applied:

• to existing subaccounts;
• to subaccounts created in the future.

New subaccounts will continue to inherit this configuration until it is changed.

See the Create default Escrow Account configuration for all subaccounts endpoint.

How to validate

The request must return 200 OK.

Applying the configuration to existing subaccounts may take a few moments, depending on the number of subaccounts linked to the main account.

To check the registered default configuration, use:

GET /v3/accounts/escrow

See the Retrieve default Escrow Account configuration endpoint.

Next steps

• Understand fee charging per configured subaccount
• Understand how amounts are kept under guarantee
• Implement the release of guaranteed funds
• Disable the Escrow Account