> 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/desenvolvedores/api-formalizacao-de-credito/api-reference/webhooks/webhooks-de-liquidacao-da-operacao.md).

# Webhooks de liquidação da operação

### Liquidação da Operação

Os eventos de webhook relacionados à liquidação da operação (repasse do valor financiado) de uma CCB informam o resultado de uma transação financeira.\
O resultado da liquidação pode resultar em três possíveis cenários:

* Sucesso
* Falhas ativas
* Falhas passivas

#### Sucesso na Liquidação

Envio de informações da confirmação de liquidação realizada para CCBs enviadas e processadas na Giro.Tech.\
São informados os dados do pagamento e as CCBs associadas ao pagamento. Para mais informações, avalie o payload do webhook abaixo.

Para cadastrar o envio desses eventos, efetue o [cadastro](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/webhooks/cadastro-de-webhook.md) selecionando o tipo de evento `SUCESSO_DESEMBOLSO`.

## Webhook de sucesso na liquidação

> Envia informações de liquidações realizadas e as CCBs associadas.\
> \
> ⚠️ Esse endpoint \`webhook/disbursements/success\` é um exemplo, e pode ser customizado conforme necessidade, pelo cadastro do webhook.<br>

```json
{"openapi":"3.0.0","info":{"title":"API de Webhooks de Formalização de Crédito","version":"3.0.0"},"servers":[{"url":"https://webhook-endpoint-cliente.exemplo.com","description":"Endpoint configurado pelo cliente para receber webhooks"}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhook/disbursements/success":{"post":{"summary":"Webhook de sucesso na liquidação","description":"Envia informações de liquidações realizadas e as CCBs associadas.\n\n⚠️ Esse endpoint `webhook/disbursements/success` é um exemplo, e pode ser customizado conforme necessidade, pelo cadastro do webhook.\n","tags":["Webhooks de Liquidação"],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Token de autenticação."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versao":{"type":"string","maxLength":10,"description":"versão do payload do evento. A versão 3 inclui o campo opcional `link_comprovante`."},"evento":{"type":"string","enum":["SUCESSO_DESEMBOLSO"],"description":"Tipo do evento"},"id_evento":{"type":"string","description":"Identificador único do evento"},"data_evento":{"type":"string","format":"date-time","description":"Data e horário do evento, conforme o horário universal (UTC)."},"dados":{"type":"object","description":"Dados dos pagamentos e das CCBs associadas.","properties":{"valor_desembolso":{"type":"number","format":"double","description":"Valor liquidado.","maximum":999999999.99,"minimum":0},"id_transacao":{"type":"integer","format":"int64","description":"Id único da transferência"},"data_pagamento":{"type":"string","format":"date","description":"Data em que o pagamento foi realizado."},"status":{"type":"string","enum":["CONFIRMADO"],"description":"Situação do pagamento."},"link_comprovante":{"type":"string","maxLength":510,"description":"URL externa do comprovante de pagamento, fornecida pela instituição de pagamento. O formato varia conforme o provedor.\n\n**Atenção:** o tempo de expiração depende da instituição de pagamento responsável e pode ser indefinido. Ao receber o webhook, armazene o link imediatamente para fins de consultas futuras ou prolongadas.\n"},"favorecido":{"type":"object","description":"Informações sobre o favorecido da liquidação da operação.","required":["documento"],"properties":{"documento":{"type":"string","pattern":"^(\\d{11}|\\d{14})$","maxLength":14,"description":"CPF ou CNPJ do favorecido."}}},"conta_bancaria":{"type":"object","description":"Dados da conta bancária utilizada na liquidação da operação.","required":["codigo_banco","numero_conta","numero_agencia","tipo"],"properties":{"codigo_banco":{"type":"string","maxLength":14,"description":"Código do banco."},"numero_conta":{"type":"string","maxLength":20,"description":"Número da conta bancária."},"digito_conta":{"type":"string","maxLength":2,"description":"Dígito da conta bancária."},"numero_agencia":{"type":"string","maxLength":4,"description":"Número da Agência."},"tipo":{"type":"string","enum":["CORRENTE","POUPANCA"],"description":"Tipo de conta, Corrente ou Poupança."}}},"pix":{"type":"object","description":"Dados da chave pix utilizada na liquidação da operação.","required":["chave_pix","tipo_chave_pix"],"properties":{"chave_pix":{"type":"string","maxLength":255,"description":"Chave PIX."},"tipo_chave_pix":{"type":"string","enum":["EMAIL","CPF","CNPJ","PHONE","EVP"],"description":"Tipo da chave PIX."}}},"ccbs":{"type":"array","description":"CCBs associadas ao pagamento","items":{"type":"object","description":"CCB associada à liquidação da operação","properties":{"origem":{"type":"string","maxLength":255,"description":"Originador da operação."},"numero_ccb":{"type":"string","maxLength":20,"description":"Número da CCB."},"documento_tomador":{"type":"string","pattern":"^(\\d{11}|\\d{14})$","maxLength":14,"description":"CPF ou CNPJ do tomador."},"valor_desembolso":{"type":"number","format":"double","description":"Valor liquidado.","maximum":999999999.99,"minimum":0}}}}}}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso, webhook entregue"},"400":{"description":"Requisição não processada, webhook não será entregue novamente"},"500":{"description":"Requisição não processada, webhook será entregue novamente após um período"}}}}}}
```

Na versão `3` do payload, o objeto `dados` pode incluir o campo opcional **`link_comprovante`**: URL externa do comprovante de pagamento fornecida pela instituição de pagamento. O formato varia conforme o provedor. Integrações na versão `2` continuam recebendo o evento sem esse campo.

{% hint style="warning" %}
**Armazene `link_comprovante` ao receber o webhook.** O tempo de expiração depende da instituição de pagamento e pode ser indefinido — não há garantia de disponibilidade prolongada se você depender só do link remoto. Trate a URL como dado sensível: não a publique nem a envie por canal aberto. Ausência do campo **não** significa que o pagamento falhou.
{% endhint %}

⚠️ O evento de sucesso de liquidação foi revisado e sua estrutura foi atualizada. Caso queira avaliar os dados do evento legado, avalie o [payload do webhook v1](https://docs.giro.tech/desenvolvedores/api-formalizacao-de-credito/api-reference/webhooks/webhook-legado-sucesso-liquidacao.md). Fique tranquilo, será mantida a compatibilidade do fluxo antigo até segundo aviso. Mesmo assim, recomendamos que avalie uma oportunidade para atualizar para a nova versão do evento.

#### Falhas na Liquidação

Para os cenários de falhas, temos duas categorias:

* Os cenários que vão aguardar uma ação ativa por parte do contratante da CCB, denominados "falhas ativas", onde a CCB originadora do pagamento precisa ser revisada para que o pagamento possa ser efetivado.
* Os cenários em que as informações da liquidação foram identificadas como consistentes, mas o pagamento não pôde ser concluído, denominados "falhas passivas".

⚠️ Os eventos de falha são processados de forma isolada. Um evento de falha ativa não será notificado como falha passiva, mesmo que ocorra uma falha na entrega ou se apenas um tipo de falha estiver cadastrado. Em caso de falha no envio de um tipo de evento, não será tentado reenviar como outro tipo de evento. Para garantir que você receba todas as notificações de falha, certifique-se de cadastrar todos os tipos de eventos relacionados a falhas.

**Falhas Ativas**

Para o cenário de falhas que requerem atuação por parte do contratante, temos a falha no pagamento devido a alguma inconsistência na conta de liquidação informada na formalização de uma CCB. Um exemplo seria a conta informada não pertencer ao favorecido da CCB.

Nesses cenários de falha no pagamento devido à conta de liquidação, é esperado que seja informada uma nova conta para efetuar a liquidação dessa CCB. Para efetuar esse processo, deve ser utilizado o fluxo de [revisão de liquidação](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/revisao-de-liquidacao.md).

Para mais informações, avalie o [webhook de revisão de liquidação](https://docs.giro.tech/desenvolvedores/api-formalizacao-de-credito/api-reference/webhooks/webhook-de-revisao-de-liquidacao.md).

Para cadastrar o envio desses eventos, efetue o [cadastro](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/webhooks/cadastro-de-webhook.md) selecionando o tipo de evento `REVISAO_DESEMBOLSO`.

**Falhas Passivas**

Essas falhas não requerem uma atuação direta por parte do contratante; elas serão avaliadas pela equipe da Giro.Tech para identificar a melhor resolução para o problema. Poderá ser aplicada uma nova tentativa de pagamento para casos de instabilidades, por exemplo, ou a equipe entrará em contato para identificar alternativas para a liquidação dessa operação.

Para mais informações, avalie o [payload do webhook](https://docs.giro.tech/desenvolvedores/api-formalizacao-de-credito/api-reference/webhooks/webhook-de-falha-na-liquidacao.md).

Para cadastrar o envio desses eventos, efetue o [cadastro](https://docs.giro.tech/introducao/produtos-da-giro.tech/formalizacao-de-credito/webhooks/cadastro-de-webhook.md) selecionando o tipo de evento `FALHA_DESEMBOLSO`.

#### Revisão de liquidação (falha ativa)

## Webhook de revisão da conta de liquidação

> Envia informações sobre a falha na liquidação de uma CCB devido a inconsistência da conta de liquidação.\
> Inclui informações necessárias para revisão de uma conta de liquidação.\
> \
> ⚠️ Esse endpoint \`webhook/disbursements/amendment\` é um exemplo, e pode ser customizado conforme necessidade, pelo cadastro do webhook.<br>

```json
{"openapi":"3.0.0","info":{"title":"API de Webhooks de Formalização de Crédito","version":"3.0.0"},"servers":[{"url":"https://webhook-endpoint-cliente.exemplo.com","description":"Endpoint configurado pelo cliente para receber webhooks"}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/webhook/disbursements/amendment":{"post":{"summary":"Webhook de revisão da conta de liquidação","description":"Envia informações sobre a falha na liquidação de uma CCB devido a inconsistência da conta de liquidação.\nInclui informações necessárias para revisão de uma conta de liquidação.\n\n⚠️ Esse endpoint `webhook/disbursements/amendment` é um exemplo, e pode ser customizado conforme necessidade, pelo cadastro do webhook.\n","tags":["Webhooks de Liquidação"],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Token de autenticação."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versao":{"type":"string","maxLength":10,"description":"versão do payload do evento"},"evento":{"type":"string","enum":["REVISAO_DESEMBOLSO"],"description":"Tipo do evento"},"id_evento":{"type":"string","description":"Identificador único do evento"},"data_evento":{"type":"string","format":"date-time","description":"Data e horário do evento, conforme o horário universal (UTC)."},"dados":{"type":"object","description":"Dados dos pagamentos e das CCBs associadas.","properties":{"valor_desembolso":{"type":"number","format":"double","description":"Valor liquidado.","maximum":999999999.99,"minimum":0},"id_transacao":{"type":"integer","format":"int64","description":"Id único da transferência"},"data_pagamento":{"type":"string","format":"date","description":"Data em que o pagamento foi realizado."},"status":{"type":"string","enum":["AGUARDANDO_REVISAO"],"description":"Situação do pagamento."},"favorecido":{"type":"object","description":"Informações sobre o favorecido da liquidação da operação.","required":["documento"],"properties":{"documento":{"type":"string","pattern":"^(\\d{11}|\\d{14})$","maxLength":14,"description":"CPF ou CNPJ do favorecido."}}},"conta_bancaria":{"type":"object","description":"Dados da conta bancária utilizada na liquidação da operação.","required":["codigo_banco","numero_conta","numero_agencia","tipo"],"properties":{"codigo_banco":{"type":"string","maxLength":14,"description":"Código do banco."},"numero_conta":{"type":"string","maxLength":20,"description":"Número da conta bancária."},"digito_conta":{"type":"string","maxLength":2,"description":"Dígito da conta bancária."},"numero_agencia":{"type":"string","maxLength":4,"description":"Número da Agência."},"tipo":{"type":"string","enum":["CORRENTE","POUPANCA"],"description":"Tipo de conta, Corrente ou Poupança."}}},"pix":{"type":"object","description":"Dados da chave pix utilizada na liquidação da operação.","required":["chave_pix","tipo_chave_pix"],"properties":{"chave_pix":{"type":"string","maxLength":255,"description":"Chave PIX."},"tipo_chave_pix":{"type":"string","enum":["EMAIL","CPF","CNPJ","PHONE","EVP"],"description":"Tipo da chave PIX."}}},"erro":{"type":"object","description":"Informações referentes ao erro que ocasionou falha no pagamento","properties":{"codigo":{"type":"string","maxLength":255,"description":"Código de erro interno para referência."},"mensagem":{"type":"string","maxLength":255,"description":"Mensagem de erro que ocasionou a falha no pagamento."}}},"revisao_conta_desembolso":{"type":"object","description":"Informações referentes ao ticket que deve ser enviado junto aos dados de liquidação revisados.","properties":{"ticket":{"type":"string","maxLength":256,"description":"Ticket utilizado para validação dos novos dados bancarios a serem enviados."},"data_criacao":{"type":"string","format":"date-time","description":"Data e horário em que o ticket foi emitido, conforme o horário universal (UTC)."},"data_vencimento":{"type":"string","format":"date-time","description":"Data e horário em que o ticket irá expirar, conforme o horário universal (UTC)."},"acoes_disponiveis":{"type":"array","description":"Ações disponíveis para revisão dos dados de liquidação.","uniqueItems":true,"items":{"type":"string","enum":["NOVA_CONTA","RETENTATIVA"]}}}},"ccbs":{"type":"array","description":"CCBs associadas ao pagamento","items":{"type":"object","description":"CCB associada à liquidação da operação","properties":{"origem":{"type":"string","maxLength":255,"description":"Originador da operação."},"numero_ccb":{"type":"string","maxLength":20,"description":"Número da CCB."},"documento_tomador":{"type":"string","pattern":"^(\\d{11}|\\d{14})$","maxLength":14,"description":"CPF ou CNPJ do tomador."},"valor_desembolso":{"type":"number","format":"double","description":"Valor liquidado.","maximum":999999999.99,"minimum":0}}}}}}}}}}},"responses":{"200":{"description":"Requisição processada com sucesso, webhook entregue"},"400":{"description":"Requisição não processada, webhook não será entregue novamente"},"500":{"description":"Requisição não processada, webhook será entregue novamente após um período"}}}}}}
```
