Track funds under Escrow Account guarantee

When a charge or installment is received by a subaccount with the Escrow Account enabled, the amount remains under guarantee during the period configured in daysToExpire.

While the guarantee is active, the receipt exists, but the amount is not yet available in the subaccount's balance.

Retrieve the guarantee of a charge

To retrieve the guarantee, authenticate the request with the subaccount's own API Key and provide the charge ID:

GET /v3/payments/{id}/escrow

The {id} parameter corresponds to the charge ID.

See the Retrieve payment escrow in the Escrow Account endpoint.

Expected result

A 200 OK response lets you identify the current guarantee data, including:

• the guarantee status;
• expirationDate, with the expected end date;
• the guarantee identifier;
• information related to the charge.

Store the guarantee identifier if your integration needs to perform a manual release later.

The guarantee information is also available in the escrow object returned by the charge retrieval and listing endpoints.

How to interpret the retention

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["Receive the charge"] --> B["Keep the amount under guarantee"]
B --> C["Check the escrow data"]
C --> D{"How will the guarantee be ended?"}

D --> DAuto(("Expiration"))
D --> DManual(("Manual release"))
D --> DDisable(("Disabling"))

DAuto --> E["Reach expirationDate"]
DManual --> F["End the guarantee via API"]
DDisable --> G["Disable the Escrow Account"]

E --> H["Make the amount available in the balance"]
F --> H
G --> H

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaOpcao fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class D decisao
class B,C,E,F,G validacao
class H sucesso

class DAuto respostaSim
class DManual respostaOpcao
class DDisable respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 2 stroke:#22C55E,stroke-width:4px
linkStyle 3 stroke:#8B5CF6,stroke-width:4px
linkStyle 4 stroke:#EF4444,stroke-width:4px

The guarantee can be ended:

• automatically upon reaching expirationDate;
• manually by the platform;
• when the Escrow Account is disabled for the subaccount.

After it ends, the amount is no longer held and becomes part of the subaccount's available balance.

Take the guarantee into account in reconciliation

Do not consider a receipt as available balance just because the charge was received.

While the guarantee is active:

• the receipt can be retrieved normally;
• the amount remains blocked;
• transfers, withdrawals, or other uses of the balance must consider only the funds that are actually available.

Use the escrow object to differentiate received amounts from amounts that have already been released.

Next steps

• Configure the Escrow Account for subaccounts
• Release guaranteed funds
• See the Retrieve payment escrow in the Escrow Account endpoint
• Disable the Escrow Account