Pular para o conteúdo principal
Bre-B é a plataforma nacional de pagamentos em tempo real da Colômbia, operada pelo Banco de la República. Aceite pagamentos instantâneos A2A 24 horas por dia, 7 dias por semana, por meio de chaves de Virtual Account (payin) e envie fundos diretamente para qualquer chave Bre-B (payout), tudo por meio de uma única integração. A Bre-B é a primeira plataforma de pagamentos em tempo real da Colômbia, lançada em 6 de outubro de 2025 pelo Banco de la República. Pela primeira vez, todos os bancos, carteiras digitais e provedores de serviços de pagamento (PSPs) licenciados no país compartilham uma única infraestrutura instantânea e interoperável, semelhante à transformação que o Pix causou no Brasil. A Bre-B introduz transferências instantâneas de conta para conta (A2A) em menos de 20 segundos, disponibilidade 24 horas por dia, 7 dias por semana, 365 dias por ano, e pagamentos baseados em aliases (chamados llaves) que eliminam a necessidade de compartilhar os números completos das contas. A participação é obrigatória para todas as instituições financeiras regulamentadas, tornando a Bre-B a plataforma de pagamentos de crescimento mais rápido que a Colômbia já viu. O Localpayment é compatível com Bre-B tanto para envio quanto para recebimento de pagamentos:

Visão geral

Bre-B vs. PSE: Quando usar cada um

A Colômbia já conta com o PSE como uma opção consolidada de pagamento A2A. O Bre-B não o substitui, apenas adiciona uma alternativa mais rápida e sempre disponível. Use esta tabela para escolher o método mais adequado para o seu caso:

Chave Bre-B (Llave)

A llave (chave) é um atalho alfanumérico curto que substitui o número completo da conta bancária para transferências Bre-B. Os pagadores simplesmente inserem a chave no aplicativo do banco, sem precisar informar os dados completos da conta. Como a Localpayment gera sua chave Ao criar uma Virtual Account para a Colômbia, a Localpayment gera automaticamente uma chave alfanumérica: você não precisa escolher nem configurar um tipo de chave. A chave é criada deterministicamente a partir do nome do beneficiário que você fornece: Comprimento total da chave: entre 10 e 16 caracteres alfanuméricos (o símbolo de prefixo @ não é contado). Exemplo — nome do beneficiário "TechColombia SAS":
  1. Remover espaços e caracteres especiais → TechColombiaSAS
  2. Selecionar os primeiros 10 caracteres alfanuméricos → TechColomb
  3. Combinar → @ + LP + TechColomb + 0001 = @LPTechColomb0001 (16 caracteres)
A chave gerada é retornada em beneficiary.bank.account.number assim que a Virtual Account é ativada (status.code: "200").

Limites e disponibilidade

Demonstração

Veja como um pagador interage com uma Bre-B Virtual Account na prática:

Recebimento de pagamentos Bre-B (Payin)

O Payin via Bre-B utiliza a infraestrutura Virtual Account. A Localpayment gera uma chave alfanumérica Bre-B exclusiva para cada conta criada. Os pagadores enviam fundos para essa chave a partir de qualquer aplicativo bancário compatível com Bre-B. A liquidação é instantânea e totalmente automatizada.

Como funciona

  1. Criar uma Virtual Account: seu sistema chama o endpoint Create Virtual Account com os detalhes do beneficiário.
  2. Recupere a chave Bre-B: assim que a conta for ativada (~6 segundos), consulte o status para obter a chave gerada pelo sistema a partir de beneficiary.bank.account.number.
  3. Compartilhe a chave com o pagador: o pagador insere a chave no aplicativo bancário para iniciar a transferência.
  4. Recebimento de fundos e webhook: O Localpayment recebe a transferência e envia um webhook em tempo real para o endpoint configurado.

Antes de começar

Certifique-se de ter:

Etapa 1. Crie uma Virtual Account

Envie uma solicitação POST para o endpoint Create Virtual Account.

Parâmetros-chave da solicitação

Consulte todos os parâmetros disponíveis na referência da API.

Exemplo de solicitação

curl

Resposta bem-sucedida

Resposta de erro

Tempo de ativação: As Virtual Accounts da Colômbia geralmente são ativadas em até 6 segundos. Consulte o endpoint de status ou aguarde alguns instantes antes de obter a chave Bre-B.
Beneficiários não locaisSe o seu beneficiário for residente no exterior (não for domiciliado na Colômbia), a Virtual Account deve ser registrada no Localpayment como titular da conta. Isso garante a conformidade com as regulamentações bancárias locais, permitindo que você receba pagamentos em nome de entidades estrangeiras.

Etapa 2. Recupere sua chave Bre-B

Assim que a Virtual Account estiver ativa (status.code: "200"), envie uma solicitação GET para o endpoint Get Virtual Account Status.

Exemplo de solicitação

curl

Resposta bem-sucedida

Campos de resposta principais

Compartilhe o valor de beneficiary.bank.account.number com o pagador. Nenhum dado bancário adicional é necessário.

Etapa 3. O pagador inicia a transferência.

O pagador utiliza a chave Bre-B em qualquer aplicativo bancário ou carteira digital colombiana participante:
  1. Abra o aplicativo do banco e selecione a opção Bre-B ou Transferência por chave.
  2. Insira a chave Bre-B (por exemplo, @LPTechColomb0001) como destino.
  3. Insira o valor e confirme a transferência.
  4. O pagamento é concluído em menos de 20 segundos.
O Localpayment associa automaticamente o pagamento recebido à sua Virtual Account e envia um webhook.

Etapa 4. Gerenciar Webhooks

A Localpayment envia uma solicitação POST para o endpoint configurado assim que o pagamento é creditado. Seu servidor deve responder com HTTP 200 OK para confirmar o recebimento. Consulte o guia de Webhooks para obter instruções de configuração.

Exemplo de payload de webhook

Campos-chave do webhook


Etapa 5. Acompanhe o status do Payin

Webhooks (Recomendado)

Receba notificações em tempo real quando um pagamento for creditado. Ideal para ambientes de produção.

Endpoint da API de Status

Consultar o status da transação programaticamente. Útil para conciliar notificações de webhook perdidas.

Visualização do Business Portal

Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada.
Bre-B é uma plataforma de pagamentos diretos em tempo real: as transações são liquidadas instantaneamente. O webhook é acionado somente após o pagamento ser totalmente creditado.
Referência completaConsulte todos os códigos de status em nossa Documentação de Status da Transação.

Envio de pagamentos Bre-B (Payout)

Para enviar fundos para a chave Bre-B de um destinatário, use o fluxo de Payout por transferência bancária com o código de método de pagamento 0062. O destinatário deve ter uma chave Bre-B registrada em seu banco. Você informa essa chave por meio de beneficiary.bank.account.alias.

Como funciona

  1. Colete a chave Bre-B do destinatário: obtenha a llave registrada do destinatário (qualquer tipo de chave compatível: alfanumérica, telefone, e-mail, documento ou código de comerciante).
  2. Envie o payout: chame o endpoint Create Payout com o código 0062 e a chave em beneficiary.bank.account.alias.
  3. Acompanhe a transferência: monitore o status via webhooks ou pela API de Status até 200 Completed.

Etapa 1. Inicie o Payout

Envie uma solicitação POST para o endpoint Create a Payout. Observe que o corpo da solicitação é um array.

Parâmetros-chave da solicitação

Importante: Ao enviar para uma chave Bre-B, os campos beneficiary.bank.account.type e beneficiary.bank.account.number devem ser excluídos da solicitação. Use apenas beneficiary.bank.account.alias.

Exemplo de solicitação

curl

Resposta bem-sucedida

Resposta de erro


Etapa 2. Acompanhe o status do Payout

Webhooks (Recomendado)

Receba notificações em tempo real quando a transferência for debitada. Ideal para ambientes de produção.

Endpoint da API de Status

Consulte o status do payout programaticamente. Útil para conciliação e tratamento de exceções.

Visualização do Business Portal

Interface visual para monitorar e aprovar payouts manualmente.
Referência completaConsulte todos os códigos de status em nossa Documentação de Status da Transação.

Bancos compatíveis

Os pagamentos Bre-B podem ser enviados e recebidos em todas as instituições financeiras colombianas participantes: mais de 200 bancos, carteiras digitais e cooperativas conectadas à rede do Banco de la República.
  • A&C COLANTA
  • ACCIONES Y VALORES
  • AFROAMERICANA
  • ALCALICOOP
  • AMAR
  • AVANCOP

Perguntas frequentes

As Virtual Accounts da Colômbia geralmente são ativadas em até 6 segundos. A resposta de criação da VA retorna status.code: "100" INPROGRESS. Consulte o endpoint Get Virtual Account Status até receber status.code: "200" COMPLETED antes de compartilhar a chave com os pagadores.
Sim. Uma Virtual Account e sua respectiva chave Bre-B permanecem ativas até que você as desative ou exclua explicitamente. Você pode receber um número ilimitado de pagamentos para a mesma chave ao longo do tempo.
Transferências que excedam o valor máximo (COP 12.110.000 para payin, COP 11.552.000 para payout) serão rejeitadas pela rede Bre-B. O pagador verá uma mensagem de erro em seu aplicativo bancário. Para transferências de alto valor, divida-as em várias transações.
Sim, a Bre-B opera 24 horas por dia, 7 dias por semana, 365 dias por ano, por mandato do Banco de la República. Não há períodos de inatividade, fins de semana ou restrições de feriados.
Esses campos servem a propósitos diferentes, dependendo do fluxo:
  • beneficiary.bank.account.number: Usado na resposta do Get Virtual Account Status: é onde a Localpayment retorna a chave Bre-B gerada automaticamente para a sua Virtual Account de payin. É um campo de saída somente leitura.
  • beneficiary.bank.account.alias: Usado na solicitação do Create Payout: é onde você informa a chave Bre-B do destinatário ao iniciar um payout. É um campo de entrada.
Para payouts, nunca inclua account.type ou account.number, apenas account.alias.
Esse erro normalmente significa que paymentMethod.code não é "0062" ou que paymentMethod.type não é "BankTransfer". Verifique novamente ambos os campos e certifique-se de que paymentMethod.flow esteja definido como "DIRECT". Confirme também que você está enviando o corpo da solicitação como um array JSON (envolvido em [...]).
A chave é gerada deterministicamente a partir do nome do beneficiário fornecido na criação da Virtual Account (VA):
  1. Remova todos os espaços e caracteres especiais do nome do beneficiário.
  2. Extraia os 10 primeiros caracteres alfanuméricos da string resultante.
  3. Combine: @ + LP + segmento do nome + contador sequencial de 4 dígitos.
Exemplo: "TechColombia SAS" → remover espaços → TechColombiaSAS → primeiros 10 → TechColomb → chave = @LPTechColomb0001.O contador (0001, 0002, etc.) incrementa a cada chave emitida. O comprimento final da chave varia entre 10 e 16 caracteres alfanuméricos, excluindo o símbolo @.

Testando sua integração

Ambiente de Sandbox

Utilize o ambiente de teste (staging) para todos os testes:

Cenários de teste

Verifique se sua integração lida com esses cenários:
  1. Criação de VA: Crie uma Virtual Account para a Colômbia e confirme a resposta 100 INPROGRESS.
  2. Obtenção da chave: Consulte o endpoint de status até status.code: "200" e, em seguida, verifique se beneficiary.bank.account.number contém uma chave Bre-B válida.
  3. Recebimento de pagamento (Payin): Simule um pagamento Bre-B recebido e valide se o seu handler de webhook retorna HTTP 200. Consulte Receba notificações de pagamento para configurar webhooks.
  4. Envio de payout: Envie um payout com o código 0062 e um beneficiary.bank.account.alias válido.
  5. Tratamento de notificações duplicadas: Verifique se o seu sistema lida com novas tentativas de webhook de forma idempotente usando internalId ou externalId.
  6. Ciclo de vida da conta: Teste a ativação, desativação e exclusão de Virtual Accounts.

Próximos passos

Gerenciar o ciclo de vida da Virtual Account

Ative ou desative as chaves Bre-B para pausar ou retomar temporariamente a cobrança de pagamentos sem excluir a Virtual Account.

Reembolsar um Payin

Emita um reembolso para um pagamento Bre-B recebido através da API Localpayment ou do Business Portal.

Instruções de pagamento

Veja exatamente o que compartilhar com seus pagadores para pagamentos de Virtual Account na Colômbia.

Analisar detalhes da transação

Recupere informações completas da transação usando a API Localpayment para auditoria e conciliação.
Última modificação em 10 de novembro de 2026