> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/revisao-de-liquidacao.md).

# Revisão de liquidação

Este guia descreve como homologar a funcionalidade de **revisão de conta de liquidação** em cenários de instabilidade bancária e dados bancários inválidos.

## O que é revisão de liquidação?

Quando a liquidação da operação falha por um motivo recuperável (dados bancários inválidos ou instabilidade temporária), a plataforma pode gerar um **ticket** e notificar o cliente via webhook. O cliente usa esse ticket para informar uma nova conta ou solicitar retentativa com a mesma conta.

### Pré-requisitos

* Solicite à nossa equipe a configuração do programa para utilizar essa funcionalidade, pelo e-mail: <atendimento@girotech.com.br>
* Solicite o cadastro do webhook do tipo `REVISAO_DESEMBOLSO` para a sua carteira. Novos cadastros podem ser realizados em: [formulário de cadastro de webhooks](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/webhooks/cadastro-de-webhook.md)
* Integração via API

> ℹ️ Utilize os programas e carteiras configurados pela nossa equipe para a revisão de liquidação automática.

```mermaid
flowchart TB
    subgraph cliente ["Cliente"]
        formaliza(["1. Formaliza CCB<br/>Dados bancários ou PIX"])
        revisao(["5. Solicita revisão de liquidação<br/>nova conta ou retentativa"])
    end

    subgraph plataforma ["Plataforma de Formalização"]
        liquidacao["2. Solicita liquidação"]
        avalia["3. Avalia o erro"]
        ticket["4a. Gera ticket"]
        webhook["4b. Webhook REVISAO_DESEMBOLSO"]
        retenta["6. Retenta transferência"]
        interno["Tratamento interno<br/>sem ticket"]
    end

    subgraph ip ["Instituição de Pagamento"]
        processa{"Pagamento<br/>processado?"}
    end

    sucesso(["Liquidação concluída"])

    formaliza --> liquidacao
    liquidacao --> processa
    processa -->|Sucesso| sucesso
    processa -->|Falha| avalia
    avalia --> podeAtuar{"Cliente<br/>pode atuar?"}
    podeAtuar -->|Não| interno
    podeAtuar -->|Sim| ticket
    ticket --> webhook
    webhook --> revisao
    revisao --> retenta
    retenta --> processa
```

## Cenários cobertos

| Tipo de erro              | Ação esperada do cliente                    | `acoes_disponiveis` no webhook  |
| ------------------------- | ------------------------------------------- | ------------------------------- |
| Dados bancários inválidos | Enviar **nova** conta ou PIX                | `["NOVA_CONTA"]`                |
| Instabilidade bancária    | Enviar a **mesma ou uma nova** conta ou PIX | `["NOVA_CONTA", "RETENTATIVA"]` |

**Modo automático:** após o cliente resolver o ticket via API, a plataforma **dispara a nova transferência automaticamente**. O resultado na nova retentativa chegará via webhook e, caso ocorra uma nova falha, você poderá atuar com um **novo** ticket.

## Como simular um erro de liquidação

1. Formalize uma operação CCB (API V3) usando uma das [chaves PIX de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md) que provoca o cenário desejado no ambiente de homologação.
2. Aguarde o processamento do pagamento (em homologação, pode levar alguns minutos).
3. A plataforma categoriza a falha e, com o programa habilitado, **gera um ticket** e **envia o webhook** `REVISAO_DESEMBOLSO` para o endpoint cadastrado.

Consulte a [tabela de cenários](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md#tabela-de-cenarios) no guia de chaves PIX de teste para identificar qual chave utilizar em cada cenário (nova conta ou retentativa).

## Webhook gerado pelo erro

Quando a falha é categorizada como revisão de liquidação e a política do programa permite, a plataforma envia um webhook com evento `REVISAO_DESEMBOLSO`, contendo o ticket em `dados.revisao_conta_desembolso`.

### Campos principais

| Campo                                              | Descrição                                             |
| -------------------------------------------------- | ----------------------------------------------------- |
| `evento`                                           | Sempre `REVISAO_DESEMBOLSO`                           |
| `dados.status`                                     | `AGUARDANDO_REVISAO`                                  |
| `dados.revisao_conta_desembolso.ticket`            | UUID do ticket — usar na API de revisão de liquidação |
| `dados.revisao_conta_desembolso.data_criacao`      | Data de criação do ticket                             |
| `dados.revisao_conta_desembolso.data_vencimento`   | Prazo de validade do ticket                           |
| `dados.revisao_conta_desembolso.acoes_disponiveis` | Ações permitidas (ver seção abaixo)                   |
| `dados.ccbs`                                       | Lista de CCBs afetadas (`numero_ccb`, `origem`, etc.) |
| `dados.erro`                                       | Código e mensagem da falha original                   |
| `dados.pix` ou `dados.conta_bancaria`              | Dados da conta usada na tentativa que falhou          |

## Campo `acoes_disponiveis`

O campo `acoes_disponiveis` indica **o que o cliente pode fazer** com aquele ticket.

| Valor         | Significado                                                  |
| ------------- | ------------------------------------------------------------ |
| `NOVA_CONTA`  | Informar dados bancários ou PIX **diferentes** dos originais |
| `RETENTATIVA` | Reenviar a **mesma** conta ou PIX da operação original       |

### Regras de validação

* Se o webhook trouxer apenas `["NOVA_CONTA"]`, enviar a mesma chave ou conta da formalização será **rejeitado**
* Se trouxer `["NOVA_CONTA", "RETENTATIVA"]`, o cliente escolhe a ação adequada — retentativa com a conta da instabilidade ou envio de conta nova
* Cada ticket é de **uso único** — após uma revisão de liquidação aceita, o ticket deixa de estar disponível

⚠️ **Aviso:** Internamente, o sistema acompanha as retentativas em andamento e existe um **limite** de tentativas por pagamento. Em cenários de instabilidade bancária, é responsabilidade do **cliente** gerenciar **quando** realizar as retentativas — tentativas seguidas podem esgotar o limite e impedir nova atuação.

## Payloads de exemplo

### Retentativa — instabilidade bancária

```json
{
  "versao": "2",
  "evento": "REVISAO_DESEMBOLSO",
  "id_evento": "bcf94684-56ef-46e5-bd83-56ffe0719bdb",
  "data_evento": "2026-06-25T15:17:07.774333666Z",
  "dados": {
    "valor_desembolso": 1.00,
    "id_transacao": 21593,
    "data_pagamento": "2026-06-25",
    "status": "AGUARDANDO_REVISAO",
    "favorecido": {
      "documento": "21057874019"
    },
    "erro": {
      "codigo": "paymentError.general",
      "mensagem": "Houve uma instabilidade na comunicação com o banco"
    },
    "pix": {
      "chave_pix": "b2c4d6e8-f0a1-4b3c-9d5e-7f8a9b0c1d2e",
      "tipo_chave_pix": "EVP"
    },
    "revisao_conta_desembolso": {
      "ticket": "0988b094-e702-43e4-be26-104d329b6fdd",
      "data_criacao": "2026-06-25T15:16:47.017936Z",
      "data_vencimento": "2026-06-30T03:00:00Z",
      "acoes_disponiveis": ["NOVA_CONTA", "RETENTATIVA"]
    },
    "ccbs": [
      {
        "origem": "scd_staging",
        "numero_ccb": "733946",
        "documento_tomador": "21057874019",
        "valor_desembolso": 1.00
      }
    ]
  }
}
```

### Nova conta — dados bancários inválidos

```json
{
  "versao": "2",
  "evento": "REVISAO_DESEMBOLSO",
  "id_evento": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data_evento": "2026-06-25T14:10:22.123456789Z",
  "dados": {
    "valor_desembolso": 1.00,
    "id_transacao": 21580,
    "data_pagamento": "2026-06-25",
    "status": "AGUARDANDO_REVISAO",
    "favorecido": {
      "documento": "21057874019"
    },
    "erro": {
      "codigo": "paymentError.general",
      "mensagem": "Dados bancários inválidos para o favorecido"
    },
    "pix": {
      "chave_pix": "b6a1e5cc-96c2-488f-b98a-7c9d968f9a11",
      "tipo_chave_pix": "EVP"
    },
    "revisao_conta_desembolso": {
      "ticket": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "data_criacao": "2026-06-25T14:10:05.456789Z",
      "data_vencimento": "2026-06-30T03:00:00Z",
      "acoes_disponiveis": ["NOVA_CONTA"]
    },
    "ccbs": [
      {
        "origem": "scd_staging",
        "numero_ccb": "733946",
        "documento_tomador": "21057874019",
        "valor_desembolso": 1.00
      }
    ]
  }
}
```

Quando a formalização usou conta bancária em vez de PIX, o bloco `pix` é substituído por `conta_bancaria` com os campos `codigo_banco`, `numero_conta`, `digito_conta`, `numero_agencia`, `digito_agencia` e `tipo`.

## Como realizar a revisão de liquidação

### Fluxo

1. Receber o webhook `REVISAO_DESEMBOLSO`.
2. Ler `acoes_disponiveis` e decidir a ação (`NOVA_CONTA` ou `RETENTATIVA`).
3. Extrair o `ticket` de `dados.revisao_conta_desembolso` e o `numero_ccb` de `dados.ccbs`.
4. Chamar a API de revisão de liquidação **antes** de `data_vencimento`.
5. Em modo automático, aguardar a retentativa de liquidação — nenhuma ação adicional é necessária.

### Endpoint da revisão de liquidação

```
POST {base_url}/integration/v3/operations/{numero_ccb}/disbursement-accounts/amend/{ticket}
```

**Headers obrigatórios:**

| Header          | Valor                     |
| --------------- | ------------------------- |
| `Origem`        | Identificador da carteira |
| `Authorization` | API key de integração     |
| `Content-Type`  | `application/json`        |

Consulte a [referência da API de revisão de liquidação](https://docs.giro.tech/desenvolvedores/api-formalizacao-de-credito/api-reference/revisao-da-conta-de-liquidacao-de-uma-ccb.md) para detalhes do contrato.

### Enviar nova conta (PIX)

```json
{
  "pix": {
    "chave_pix": "<nova_chave>",
    "tipo_chave_pix": "EVP"
  }
}
```

### Enviar nova conta (conta bancária)

```json
{
  "conta_bancaria": {
    "codigo_banco": "001",
    "numero_conta": "56067859",
    "digito_conta": "6",
    "numero_agencia": "1570",
    "digito_agencia": "1",
    "tipo": "CORRENTE"
  }
}
```

### Retentativa com a mesma conta

Use o **mesmo endpoint** e envie a **mesma** chave PIX ou conta bancária da formalização original:

```json
{
  "pix": {
    "chave_pix": "<mesma_chave_da_formalizacao>",
    "tipo_chave_pix": "EVP"
  }
}
```

### Cenário inválido: reutilizar conta antiga

Em tickets de instabilidade (`acoes_disponiveis` com `RETENTATIVA`), **não** é permitido enviar uma conta ou PIX já utilizados em tentativas anteriores da mesma operação, exceto a conta da tentativa que gerou a instabilidade.

| Opção         | Descrição                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `RETENTATIVA` | A **mesma** conta ou PIX da tentativa que falhou por instabilidade (informada no webhook em `dados.pix` ou `dados.conta_bancaria`) |
| `NOVA_CONTA`  | Uma conta ou PIX **nova**, ainda não utilizada naquela operação                                                                    |

**Exemplo:** a operação foi formalizada com a conta A, revisada para a conta B (nova conta), e a tentativa com B falhou por instabilidade. Na retentativa, o cliente **pode** reenviar B (`RETENTATIVA`) ou informar a conta C (`NOVA_CONTA`). Enviar novamente a conta A será **rejeitado**.

## Checklist de homologação

### Nova conta (modo automático)

* [ ] Formalização com chave PIX do cenário **nova conta** (ver [chaves de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md))
* [ ] Webhook recebido com `evento: REVISAO_DESEMBOLSO`
* [ ] `acoes_disponiveis` contém apenas `NOVA_CONTA`
* [ ] Revisão de liquidação com conta ou PIX **nova** aceita com sucesso
* [ ] Retentativa automática de transferência disparada pela plataforma

### Retentativa (modo automático)

* [ ] Formalização com chave PIX do cenário **retentativa** (ver [chaves de teste](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/homologacao/chaves-pix-de-teste.md))
* [ ] Webhook recebido com `evento: REVISAO_DESEMBOLSO`
* [ ] `acoes_disponiveis` contém `NOVA_CONTA` e `RETENTATIVA`
* [ ] Revisão de liquidação com a **mesma** conta ou PIX da instabilidade aceita com sucesso
* [ ] Revisão de liquidação com conta antiga (de tentativa anterior) **rejeitada**
* [ ] Retentativa automática de transferência disparada pela plataforma

<figure><img src="https://978140111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6l1W0qI0y7eF7f0QRDC%2Fuploads%2Fgit-blob-f5d2064d02c970341ca52b2c083eb1f585bc436a%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
