Bloqueio Cautelar
O bloqueio cautelar é um mecanismo exclusivo do Pix para aumentar a segurança dos seus usuários. Acontece quando existe uma suspeita de fraude. No momento do recebimento do Pix, os recursos são imediatamente bloqueados por até 72 horas pela instituição do recebedor para fazer uma avaliação mais detalhada.
Nesses casos, o recebedor deve ser imediatamente notificado no ato do bloqueio.
Além disso, importante informar que:
- se houver fraude: os recursos serão devolvidos ao pagador;
- se não houver fraude: o bloqueio é encerrado e o recurso é devolvido ao recebedor, que deve ser notificado sobre o crédito na conta.
Contexto
Esta API foi desenvolvida com o objetivo de viabilizar o cadastro, a consulta, exclusão e a atualização de uma URL destinada ao recebimento de callbacks durante o processo de bloqueio cautelar.
Será enviado notificações em dois momentos distintos:
- No momento da suspeita de fraude e bloqueio do saldo;
- No momento da devolução do valor ao pagador.
Pré-requisitos
- Estar autenticado com um token válido da nossa API;
- Possuir uma URL disponível para cadastro;
- Possuir client_id e client_secret ativos.
Rotas
As rotas permitem cadastrar, atualizar, buscar e remover um webhook. A URL segue o mesmo procedimento de autenticação das outras rotas, utilizando o padrão OAuth2 do token gerado pelo Keycloak. O mediador só pode realizar as operações para o seu ID.
1. Cadastro
▶️ Endpoint
POST: {{url}}/v1/prevention-service/webhook
Para o cadastro de webhook, deverá ser passado os seguintes campos:
- Id do mediador;
- URL de callback;
- Headers que será enviado para callback (opcional);
Request:
Headers:
- Content-Type: application/json
- Authorization: Bearer token
{
"mediatorId": "mock_example",
"url": "http://localhost:3000/webhook",
"headers": {
"Authorizaion": "Bearer teste"
}
}
2. Consulta
▶️ Endpoint
GET: {{url}}/v1/prevention-service/webhook/{{mediatorId}}
Retorna informações do cadastro da webhook.
Request:
Headers:
- Content-Type: application/json
- Authorization: Bearer token
Parâmetro:
- mediatorId
✅ Resposta
{
"createdAt": "2025-08-18T20:01:54.330Z",
"url": "https://webhook.site/fa76f5d7-8e33-4156-b2af-51d827b1a8cc",
"mediatorId": "235E013A-25C0-4335-BEF2-310DFD3D577C",
"headers": null,
"updatedAt": "2025-08-20T20:56:27.398Z"
}
3. Exclusão
▶️ Endpoint
DELETE: {{url}}/v1/prevention-service/webhook/{{mediatorId}}
Request:
Headers:
- Content-Type: application/json
- Authorization: Bearer token
Parâmetro:
- mediatorId
✅ Resposta
{
"status": 200,
"message": "Successfully deleted item!"
}
4. Atualização
▶️ Endpoint
PUT: {{url}}/v1/prevention-service/webhook/{{mediatorId}}
Para atualização do webhook deverá ser passado os seguintes campos:
- url de callback;
- headers que será enviado para callback (opcional);
Request:
Headers:
- Content-Type: application/json
- Authorization: Bearer token
Parâmetro:
- mediatorId
{
"url": "http://localhost:3000/webhook-atualizado"
}
✅ Resposta
{
"status": 200,
"message": "Successfully updated item"
}
5. Callback
Abaixo um payload de exemplo do callback:
{
"message": "valor bloqueado por motivos de segurança",
"transaction": {
"identification": {
"originalSystem": "MP",
"transactionIdentification": "mock_id"
},
"correlationId": "mock_id",
"type": "PIX_RECEIVED",
"amount": 10,
"timestampUtc": "2025-09-01T19:42:17.571",
"debtor": {
"name": "Nome da pessoa fisica",
"taxId": "12345678901",
"account": {
"participantISPB": "23114447",
"branch": "1",
"accountNumber": "111111",
"pixAccountType": "CACC"
}
},
"credtor": {
"name": "Nome da pessoa fisica",
"taxId": "12345678901",
"account": {
"participantISPB": "23114447",
"branch": "1",
"accountNumber": "111111",
"pixAccountType": "TRAN"
}
},
"pixData": {
"initiationType": "DICT",
"addressingKey": "mock_addressing_key",
"transactionPurpose": "IPAY"
}
}
}
Suporte
Para dúvidas ou acompanhamento de chamados, acesse: Portal de Suporte