Bloqueio de saldo

Visão Geral

A API de Bloqueio de Saldo permite realizar o bloqueio de um valor específico no saldo disponível da conta do cliente, reduzindo o saldo disponível e transferindo o valor para o saldo bloqueado de forma controlada e rastreável.

A funcionalidade está disponível para clientes dos modelos BaaS e Core Banking, permitindo a execução de bloqueios operacionais, regulatórios, judiciais ou comerciais de forma única e padronizada.

Após a confirmação do bloqueio, o valor bloqueado torna-se indisponível para transações que consumam saldo disponível, mantendo integridade contábil e transparência via extrato e eventos (webhooks).

Esta API foi projetada para suportar múltiplos cenários de bloqueio de forma genérica e flexível, incluindo:

• Bloqueios judiciais
• Ações antifraude
• Decisões comerciais ou operacionais
• Reserva de valores para garantia de operações
• Controles internos de risco e compliance

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Realizar um bloqueio de saldo - [API Reference] *

📘

Informações importantes:

1. Regras gerais do bloqueio:

• O bloqueio deve obrigatoriamente informar um valor específico, sendo o valor mínimo permitido de R$ 0,01;
• O bloqueio somente será processado caso haja saldo disponível suficiente na conta;
• O valor solicitado para bloqueio deve ser menor ou igual ao saldo disponível no momento da requisição;
• Ao realizar um bloqueio com sucesso:
  • O saldo disponível da conta é reduzido;
  • O valor é transferido para o saldo bloqueado;
  • A operação é registrada de forma rastreável;
  • Um webhook de confirmação do bloqueio é enviado ao cliente.
• O valor bloqueado permanecerá indisponível para movimentação até que seja efetuado o desbloqueio;
• O bloqueio não altera o status cadastral da conta, impactando exclusivamente a disponibilidade do saldo;
• O bloqueio não impede o recebimento de novos créditos nem a realização de débitos, desde que haja saldo disponível (não bloqueado).

2. Rastreabilidade e Auditoria

• O campo clientRequestId garante a idempotência da operação e permite o rastreamento adequado das requisições;
  • Requisições com o mesmo clientRequestId já processado não serão executadas novamente;
  • Recomenda-se a utilização de UUID único para cada nova operação;
• O campo correlationBlockedId é obrigatório no momento do bloqueio, pois assegura a correlação operacional entre eventos de bloqueio e desbloqueio;
  • É permitido realizar múltiplos bloqueios utilizando o mesmo correlationBlockedId;
  • Não há limite técnico de bloqueios por correlação, porém recomenda-se, por boas práticas operacionais, limitar até 100 ocorrências por correlationBlockedId;

3. Uso de Tags (Metadados Operacionais e/ou Regulatórios)

• O campo tags permite a inclusão de informações complementares sem alteração do contrato da API;
• Pode ser utilizado para metadados como, por exemplo: número de processo judicial, vara/tribunal, protocolo interno, identificadores regulatórios, entre outros;
• Limite máximo de 10 tags por operação;
• Tamanho máximo por valor de tag: 255 caracteres.

Path Parameters

Campos do Request

Exemplo de request

{
  "amount": 0.01,
  "clientRequestId": "ed6a61e7-6ba4-4ccf-864a-18a1a7a96530",
  "correlationBlockedId": "b07bc9ff-393d-4557-ba7a-97fab25f7120",
  "reason": "BLOQUEIO JUDICIAL",
  "description": "Bloqueio de saldo",
  "tags": [
    { "key": "protocolo", "value": "123456" },
    { "key": "processo", "value": "54321" },
    { "key": "tipo do processo", "value": "civil" }
  ]
}

cURL da chamada

curl --location 'https://kubernetes-prod.celcoin.dev/sandbox-baas-wallet-transactions-webservice/wallet/30023646094074/balance/block' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --data '{
    "amount": 0.01,
    "clientRequestId": "ed6a61e7-6ba4-4ccf-864a-18a1a7a96530",
    "correlationBlockedId": "b07bc9ff-393d-4557-ba7a-97fab25f7120",
    "reason": "BLOQUEIO JUDICIAL",
    "description": "Bloqueio de saldo",
    "tags": [
      { "key": "protocolo", "value": "123456" },
      { "key": "processo", "value": "54321" },
      { "key": "tipo do processo", "value": "civil" }
    ]
  }'

Exemplo de retorno

👍

Sucesso 200

{
  "status": "CONFIRMED",
  "version": "1.0.0",
  "body": {
    "id": "c18c4967-2071-405d-9e88-c2f13994fc88",
    "blockedAmount": 0.01,
    "clientRequestId": "a4bbc5b0-dd62-4d87-ab29-19564b8e7955",
    "clientRequestId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
    "debitParty": {
      "account": "30023646094074",
      "ispb": null,
      "name": "Frank Mante",
      "branch": "0001",
      "bank": "13935893"
    },
    "description": "Bloqueio de saldo",
    "reason": "BLOQUEIO JUDICIAL",
    "tags": [
      {
        "key": "protocolo",
        "value": "123456"
      },
      {
        "key": "processo",
        "value": "54321"
      },
      {
        "key": "tipo de processo",
        "value": "civil"
      }
    ]
  }
}

Campos do Response

Webhook

Campos importantes do webhook:

Exemplo de webhook - "entity": "balance-amount-even" e "type": "blocked-amount"

{
  "webhookId": "c18c4967-2071-405d-9e88-c2f13994fc88",
  "body": {
    "reason": "BLOQUEIO CLIENTE",
    "amount": 0.01,
    "correlationBlockedId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
    "taxId": "66877376781",
    "clientCode": "a4bbc5b0-dd62-4d87-ab29-19564b8e7955",
    "name": "Frank Mante",
    "description": "Criação de bloqueio de saldo MKD",
    "id": "c18c4967-2071-405d-9e88-c2f13994fc88",
    "type": "blocked-amount",
    "branch": "0001",
    "account": "30023646094074"
  },
  "entity": "balance-amount-event",
  "createTimestamp": "2026-02-20T12:22:15.0803751",
  "status": "CONFIRMED"
}

Erros

❗

Error 400

{
  "status": "ERROR",
  "version": "1.0.0",
  "error": {
    "errorCode": "CBE316",
    "message": "Lançamento não permitido. Não existe saldo em moeda eletrônica para o lançamento"
  }
}

Tabela de errorCode