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":
- Remover espaços e caracteres especiais →
TechColombiaSAS - Selecionar os primeiros 10 caracteres alfanuméricos →
TechColomb - Combinar →
@+LP+TechColomb+0001=@LPTechColomb0001(16 caracteres)
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
- Criar uma Virtual Account: seu sistema chama o endpoint Create Virtual Account com os detalhes do beneficiário.
- 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. - Compartilhe a chave com o pagador: o pagador insere a chave no aplicativo bancário para iniciar a transferência.
- 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:- Credenciais de API válidas (token de acesso).
- Uma conta Localpayment configurada para a Colômbia (
COP).
Etapa 1. Crie uma Virtual Account
Envie uma solicitaçãoPOST 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:- Abra o aplicativo do banco e selecione a opção Bre-B ou Transferência por chave.
- Insira a chave Bre-B (por exemplo,
@LPTechColomb0001) como destino. - Insira o valor e confirme a transferência.
- O pagamento é concluído em menos de 20 segundos.
Etapa 4. Gerenciar Webhooks
A Localpayment envia uma solicitaçãoPOST 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.
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 pagamento0062. 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
- 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).
- Envie o payout: chame o endpoint Create Payout com o código
0062e a chave embeneficiary.bank.account.alias. - 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çãoPOST para o endpoint Create a Payout. Observe que o corpo da solicitação é um array.
Parâmetros-chave da solicitação
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.Lista completa de bancos
Lista completa de bancos
- A
- B
- C
- D
- F
- G
- J
- K
- L
- M
- N
- P
- R
- S
- T
- U
- V
- A&C COLANTA
- ACCIONES Y VALORES
- AFROAMERICANA
- ALCALICOOP
- AMAR
- AVANCOP
Perguntas frequentes
Quanto tempo leva para minha Virtual Account Bre-B ser ativada?
Quanto tempo leva para minha Virtual Account Bre-B ser ativada?
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.Posso usar a mesma chave Bre-B para vários pagamentos?
Posso usar a mesma chave Bre-B para vários pagamentos?
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.
O que acontece se um pagador enviar um valor superior ao máximo permitido?
O que acontece se um pagador enviar um valor superior ao máximo permitido?
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.
Posso receber pagamentos da Bre-B fora do horário comercial?
Posso receber pagamentos da Bre-B fora do horário comercial?
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.
Qual a diferença entre account.number e account.alias?
Qual a diferença entre account.number e account.alias?
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.
account.type ou account.number, apenas account.alias.Por que meu payout foi rejeitado com a mensagem 'Parâmetro inválido + [paymentMethod.code]'?
Por que meu payout foi rejeitado com a mensagem 'Parâmetro inválido + [paymentMethod.code]'?
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 [...]).Como a Localpayment gera a chave Bre-B para minha Virtual Account?
Como a Localpayment gera a chave Bre-B para minha Virtual Account?
A chave é gerada deterministicamente a partir do nome do beneficiário fornecido na criação da Virtual Account (VA):
- Remova todos os espaços e caracteres especiais do nome do beneficiário.
- Extraia os 10 primeiros caracteres alfanuméricos da string resultante.
- Combine:
@+LP+ segmento do nome + contador sequencial de 4 dígitos.
"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:- Criação de VA: Crie uma Virtual Account para a Colômbia e confirme a resposta
100 INPROGRESS. - Obtenção da chave: Consulte o endpoint de status até
status.code: "200"e, em seguida, verifique sebeneficiary.bank.account.numbercontém uma chave Bre-B válida. - 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. - Envio de payout: Envie um payout com o código
0062e umbeneficiary.bank.account.aliasválido. - Tratamento de notificações duplicadas: Verifique se o seu sistema lida com novas tentativas de webhook de forma idempotente usando
internalIdouexternalId. - 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.

