Guia de Contas escrow

Confira o guia de contas escrow para mais informações.

Este endpoint permite encerrar manualmente a garantia associada a uma cobrança que utiliza Conta Escrow.

Ao executar essa operação, os recursos financeiros deixam de permanecer protegidos pelas regras da garantia e seguem o fluxo financeiro normal da cobrança.

Normalmente, essa ação é realizada pela plataforma responsável pela intermediação da operação após confirmar que todas as condições acordadas entre as partes foram atendidas.

Quando utilizar

O encerramento manual da garantia é indicado em cenários como:

• confirmação da entrega de um produto;
• conclusão da prestação de um serviço;
• validação manual da operação pela plataforma;
• confirmação do recebimento pelo comprador;
• liberação antecipada dos recursos antes do encerramento automático da garantia.

Em uma integração com Conta Escrow, este endpoint geralmente representa a etapa final do fluxo de proteção financeira.

Dependências para utilização

Antes de encerrar a garantia, é necessário que:

• a cobrança tenha sido criada utilizando Conta Escrow;
• a garantia ainda esteja ativa;
• o identificador da garantia esteja disponível;
• a garantia não tenha sido encerrada anteriormente.

Sem essas condições, a operação não poderá ser concluída.

📘

Importante

O parâmetro id corresponde ao identificador da garantia da Conta Escrow e não ao identificador da cobrança.

Parâmetro utilizado

📘

Importante

O parâmetro id corresponde ao identificador da garantia da Conta Escrow e não ao identificador da cobrança.

Esse identificador é retornado durante a criação da cobrança com garantia e deve ser armazenado pela integração para utilização posterior.

Exemplo de utilização

Uma chamada típica para encerrar a garantia utiliza o identificador da garantia retornado anteriormente pela API.

POST /v3/escrow/esc_123456/finish

Fluxo esperado:

Criar cobrança com garantia

↓

Receber pagamento

↓

Validar entrega ou serviço

↓

Executar o encerramento da garantia

↓

Liberar o fluxo financeiro da cobrança

📘

Exemplo

Uma plataforma de marketplace pode manter os recursos protegidos até a confirmação da entrega do produto pelo comprador.

Após a confirmação, a plataforma executa este endpoint para finalizar a garantia e permitir que a operação siga seu fluxo financeiro normal.

Papel deste endpoint no fluxo da integração

Uma implementação típica utilizando Conta Escrow segue a seguinte sequência:

Criar cobrança com garantia
↓
Receber pagamento
↓
Manter valor protegido
↓
Validar entrega ou serviço
↓
Encerrar garantia
↓
Fluxo financeiro normal da cobrança

O encerramento da garantia representa a conclusão do processo de proteção dos recursos envolvidos na operação.

Comportamento da operação

Após a execução do endpoint, a garantia deixa de permanecer ativa para aquela cobrança.

Garantia ativa
↓
Solicitação de encerramento
↓
Garantia encerrada
↓
Liberação do fluxo financeiro da operação

Uma vez concluída, a operação não possui mecanismo para reativar a garantia da cobrança.

🚧

Atenção

O encerramento da garantia possui impacto financeiro direto, pois os valores deixam de permanecer protegidos pelas regras da Conta Escrow.

Certifique-se de que todas as validações operacionais da sua plataforma tenham sido concluídas antes de executar essa ação.

Regras de negócio importantes

• O encerramento é definitivo para aquela garantia.
• O identificador utilizado deve ser o da garantia da Conta Escrow.
• Uma garantia já encerrada não pode ser encerrada novamente.
• O endpoint não cria uma nova garantia nem altera as condições da cobrança, apenas finaliza a proteção existente.

Boas práticas

📘

Recomendado

• Armazene o identificador da garantia retornado durante a criação da cobrança.
• Execute o encerramento apenas após confirmar que a operação foi concluída.
• Evite liberar recursos automaticamente sem validações adicionais.
• Registre auditorias internas para rastreabilidade das liberações realizadas.
• Mantenha o evento que autoriza a liberação dos recursos desacoplado da chamada da API sempre que possível.

Erros comuns

Garantia não encontrada

Ocorre quando o identificador informado não existe ou não pertence à conta autenticada.

Garantia já encerrada

Ocorre quando a operação é executada sobre uma garantia que já foi finalizada anteriormente.

Identificador inválido

Ocorre quando o identificador informado não corresponde a uma garantia válida de Conta Escrow.

Garantia indisponível para encerramento

Ocorre quando a operação não atende às condições necessárias para a finalização da garantia.

Próximos passos

Após o encerramento da garantia, normalmente o fluxo da integração continua com:

• consulta da cobrança;
• acompanhamento dos eventos da operação através de Webhooks;
• conciliação financeira da transação;
• processamento interno da conclusão da negociação.