> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bre-B (Colômbia)

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](https://docs.localpayment.com/pt-br/docs/pix-brazil.md) 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:

| Fluxo | Método | Código de pagamento | Moeda | Valor máximo |
| - | - | - | - | - |
| **Payin** (recebimento) | Virtual Account | `2006` | COP | COP 12.110.000 |
| **Payout** (envio) | Transferência bancária | `0062` | COP | COP 11.552.000 |

***

## Visão geral

### Bre-B vs. PSE: Quando usar cada um

A Colômbia já conta com o [PSE](https://docs.localpayment.com/pt-br/docs/pse-colombia.md) 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:

| Recurso | PSE | Bre-B |
| - | - | - |
| **Liquidação** | Ciclos de lotes: dependem dos horários de corte bancários | Instantâneo, a qualquer hora, sem atrasos na compensação. |
| **Disponibilidade** | Somente em horário bancário (normalmente das 8h às 17h, de segunda a sexta-feira). | 24 horas por dia, 7 dias por semana, 365 dias por ano, incluindo noites, fins de semana e feriados. |
| **Experiência de finalização da compra** | São necessários todos os dados da conta + redirecionamento bancário. | Sem redirecionamento, o pagador usa um alias (*llave*) ou QR Code |
| **Interoperabilidade** | Apenas bancos participantes, fluxo variável | Obrigatório para todos os bancos, carteiras digitais e provedores de serviços de pagamento licenciados. |
| **Velocidade de confirmação** | De horas a dias, dependendo do horário. | Menos de 20 segundos, garantido. |
| **Ideal para** | Fluxos estabelecidos com integração PSE existente | Novas integrações, casos de uso em tempo real, cobertura 24 horas por dia, 7 dias por semana. |

### 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:

| Parte | Conteúdo | Descrição |
| - | - | - |
| **1** | `LP` | Prefixo fixo que identifica a Localpayment como emissora da chave. |
| **2** | Até 10 caracteres alfanuméricos | Primeiros caracteres do nome do beneficiário após remover espaços e caracteres especiais (ex.: `-`, `.`, acentos). |
| **3** | Contador sequencial de 4 dígitos | Contador preenchido com zeros que incrementa para cada chave emitida (ex.: `0001`, `0002`, `0003`). |

**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

| Propriedade | Payin (código `2006`) | Payout (código `0062`) |
| - | - | - |
| Moeda | `COP` | `COP` |
| Valor mínimo | COP 1,00 | COP 1,00 |
| Valor máximo | COP 12.110.000,00 | COP 11.552.000,00 |
| Velocidade de liquidação | Em tempo real (\< 20 s) | Em tempo real (\< 20 s) |
| Disponibilidade | 24/7/365 | 24/7/365 |
| Confirmação de pagamento | Assíncrono (webhook) | Assíncrono (webhook) |

### Demonstração

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

[Embedded content](https://embed.figma.com/proto/4RwikYTlBaLleedifW2WcO/Virtual-Accounts-Examples?node-id=7395-59\&scaling=scale-down-width\&content-scaling=fixed\&page-id=7395%3A185\&embed-host=share\&kind=proto)

***

## Recebimento de pagamentos Bre-B (Payin)

O Payin via Bre-B utiliza a infraestrutura **[Virtual Account](https://docs.localpayment.com/pt-br/docs/virtual-accounts-overview.md)**. 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:

* [Credenciais de API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso).
* Uma conta Localpayment configurada para a [Colômbia](https://docs.localpayment.com/pt-br/docs/colombia.md) (`COP`).

***

### Etapa 1. Crie uma Virtual Account

Envie uma solicitação `POST` para o endpoint [Create Virtual Account](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md).

#### Parâmetros-chave da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
| - | - | - | - | - |
| `country` | string | ✅ | Deve ser `COL` para a Colômbia. | `"COL"` |
| `accountNumber` | string | ✅ | Seu número de conta comercial Localpayment. | `"{{accountNumber}}"` |
| `externalId` | string | ✅ | Seu identificador exclusivo para esta Virtual Account. Use um UUID. | `"a1b2c3d4-..."` |
| `beneficiary.type` | string | ✅ | `INDIVIDUAL` (pessoa física) ou `COMPANY` (pessoa jurídica). | `"COMPANY"` |
| `beneficiary.name` | string | ✅ | Nome completo ou nome da entidade jurídica. Os primeiros caracteres são usados para gerar a chave Bre-B. | `"TechColombia SAS"` |
| `beneficiary.document.type` | string | ✅ | `NIT` para empresas; `CC`, `CE`, `TI` ou `PASS` para pessoas físicas. | `"NIT"` |
| `beneficiary.document.id` | string | ✅ | Número do documento que corresponde ao formato do tipo selecionado. | `"901275418-3"` |

Consulte todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md) na referência da API.

#### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "country": "COL",
  "accountNumber": "{{accountNumber}}",
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    }
  }
}'
```

#### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "8f3e1c20-4b72-4d5a-9a1b-2c3d4e5f6078",
  "accountNumber": "{{accountNumber}}",
  "country": "COL",
  "currency": "COP",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "fullName": "TechColombia SAS",
    "lastName": "",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    }
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}
```

#### Resposta de erro

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "f2d9d9b0-093d-469b-c8d6-728b0cc67e80",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}
```

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **Beneficiários não locais**
>
> Se 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](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md).

#### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
     --url 'https://api.stage.localpayment.com/api/virtual-account/a1b2c3d4-5e6f-7890-abcd-ef1234567890' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'
```

#### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "8f3e1c20-4b72-4d5a-9a1b-2c3d4e5f6078",
  "accountNumber": "{{accountNumber}}",
  "country": "COL",
  "currency": "COP",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "fullName": "TechColombia SAS",
    "lastName": "",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    },
    "bank": {
      "account": {
        "type": "KEY",
        "number": "@LPTechColomb0001"
      }
    }
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "Virtual account active and ready for payments"
  },
  "errors": []
}
```

#### Campos de resposta principais

| Campo | Descrição |
| - | - |
| `beneficiary.bank.account.number` | A chave Bre-B para compartilhar com o pagador (por exemplo, `@LPTechColomb0001`). |
| `beneficiary.bank.account.type` | Sempre `KEY` para Virtual Accounts Bre-B. |
| `status.code` | `200` = ativa e pronta para receber. `100` = ainda em ativação. |

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](https://docs.localpayment.com/pt-br/docs/webhooks.md) para obter instruções de configuração.

#### Exemplo de payload de webhook

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "transactionType": "PayIn",
    "externalId": "cf194632-7ec4-4a44-9b92-9bbacad5349a",
    "internalId": "b97ac13c-1acb-4bc0-8b2a-067945e26161",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "2006",
        "flow": "DIRECT"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "COP",
        "fxQuote": 1.0,
        "amount": 1000.0
    },
    "payment": {
        "currency": "COP",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1000.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "COP",
        "fxSource": 3705.82,
        "fxQuote": 1.0,
        "amount": 1.0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "LOCALPAYMENT",
        "document": {
            "type": "NIT",
            "id": "1111123456"
        },
        "bank": {
            "name": "BANCO DE BOGOTÁ",
            "code": "1001",
            "account": {
                "type": "KEY",
                "number": "@XXXXXXXOXX0000"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Test company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastName": "Doe",
        "document": {
            "type": "CC",
            "id": "11111654321"
        },
        "email": "NA",
        "bank": {
            "name": "BANCO POPULAR",
            "code": "1002",
            "account": {
                "type": "BREB",
                "number": "signer:wTUTnHK5mLAQXLgVuhoANKGaKTdgRFmrx7@breb"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": [],
    "referenceCode": "V0ZO-AIPV-NOD9",
    "tracking": {
        "id": "20260225900504001TFY123451234501234",
        "reference": "20260225900504001TFY123451234501234",
        "concept": "Test payment"
    }
}
```

#### Campos-chave do webhook

| Campo | Descrição |
| - | - |
| `paymentMethod.code` | Sempre `2006` para payins de Virtual Account Bre-B. |
| `status.code` | `200` = `COMPLETED`: os fundos foram creditados. |
| `beneficiary.bank.account.number` | A chave Bre-B da sua Virtual Account que recebeu o pagamento. |
| `payer.bank.account.type` | `BREB`: confirma que o pagador enviou via rede Bre-B. |
| `tracking.id` / `tracking.reference` | Referência de transação da rede Bre-B. Utilizada para [reconciliação](https://docs.localpayment.com/pt-br/docs/reporting-and-reconciliation.md). |
| `tracking.concept` | Descrição da transferência fornecida pelo pagador. |
| `referenceCode` | Referência exclusiva da Localpayment para esta transação. |

***

### Etapa 5. Acompanhe o status do Payin

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando um pagamento for creditado. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para conciliar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> 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.

| Código | Status | Descrição |
| :- | :- | :- |
| `200` | `COMPLETED` | O pagamento foi creditado em sua conta. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## 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](https://docs.localpayment.com/pt-br/docs/send-funds-via-bank-transfer.md)** 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](https://docs.localpayment.com/pt-br/reference/create-a-payout.md). Observe que o corpo da solicitação é um **array**.

#### Parâmetros-chave da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição | Exemplo |
| - | - | - | - | - |
| `country` | string | ✅ | Deve ser `COL`. | `"COL"` |
| `currency` | string | ✅ | Deve ser `COP`. | `"COP"` |
| `amount` | number | ✅ | Valor da transação. Mínimo COP 1,00, máximo COP 11.552.000,00. | `50000` |
| `paymentMethod.type` | string | ✅ | Deve ser `BankTransfer`. | `"BankTransfer"` |
| `paymentMethod.code` | string | ✅ | Deve ser `0062` para Bre-B. | `"0062"` |
| `paymentMethod.flow` | string | ✅ | Deve ser `DIRECT`. | `"DIRECT"` |
| `beneficiary.type` | string | ✅ | `INDIVIDUAL` ou `COMPANY`. | `"INDIVIDUAL"` |
| `beneficiary.name` | string | ✅ | Nome do destinatário ou nome da empresa. | `"John"` |
| `beneficiary.lastName` | string | ✅ | Sobrenome do destinatário (somente para pessoas físicas). | `"Doe"` |
| `beneficiary.document.type` | string | ✅ | `CC`, `NIT`, `CE`, `TI` ou `PASS`. | `"CC"` |
| `beneficiary.document.id` | string | ✅ | Número do documento que corresponde ao formato do tipo selecionado. | `"1088338888"` |
| `beneficiary.bank.account.alias` | string | ✅ | Chave Bre-B (llave) registrada do destinatário. **Não** inclua `account.type` nem `account.number`. | `"@juanPerez0001"` |
| `accountNumber` | string | ✅ | Seu número de conta comercial Localpayment. | `"{{accountNumber}}"` |
| `externalId` | string | ✅ | Seu identificador único para este payout. Use um UUID. | `"b2c3d4e5-..."` |
| `conceptCode` | string | ✅ | Código do conceito de pagamento fornecido pela Localpayment. | `"0001"` |

> [!WARNING]
>
> **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

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '[
  {
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "country": "COL",
    "currency": "COP",
    "amount": 50000,
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "0062",
      "flow": "DIRECT"
    },
    "beneficiary": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "CC",
        "id": "1088338888"
      },
      "email": "john.doe@example.com",
      "bank": {
        "account": {
          "alias": "@juanPerez0001"
        }
      }
    },
    "sender": {
      "type": "COMPANY",
      "name": "TechColombia SAS",
      "document": {
        "type": "NIT",
        "id": "901275418-3"
      },
      "email": "pagos@techcolombia.com"
    },
    "merchant": {
      "type": "COMPANY",
      "name": "TechColombia SAS",
      "document": {
        "type": "NIT",
        "id": "901275418-3"
      }
    },
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "Pago Bre-B Colombia"
  }
]'
```

#### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "internalId": "3a4b5c6d-7e8f-9012-cdef-a12345678902",
    "paymentMethod": {
        "code": "0062",
        "name": "Bre-B Key",
        "paymentMethodType": "BankTransfer"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 50000,
    "accountNumber": "{{accountNumber}}",
    "status": {
        "code": "100",
        "description": "Received",
        "detail": "The payout was received"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "CC",
            "id": "1088338888"
        },
        "email": "john.doe@example.com",
        "bank": {
            "account": {
                "alias": "@juanPerez0001"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": null
}
```

#### Resposta de erro

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "internalId": "cd052d8c-8406-45f8-98aa-aff9876c3285",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [paymentMethod.code] + doesn't exist for PAYMENT_METHOD_TYPE BankTransfer"
      }
    ]
  }
]
```

***

### Etapa 2. Acompanhe o status do Payout

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando a transferência for debitada. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consulte o status do payout programaticamente. Útil para conciliação e tratamento de exceções.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitorar e aprovar payouts manualmente.

| Código | Status | Descrição |
| :- | :- | :- |
| `100` | `Received` | O payout foi recebido pela Localpayment. |
| `101` | `Locked` | Validações AML confirmadas e aprovadas. |
| `102` | `In Progress` | Enviado para a rede Bre-B. |
| `200` | `Completed` | Fundos creditados ao beneficiário. |
| `300` | `Rejected` | Parâmetro inválido: verifique o array `errors` para obter detalhes. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## 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.

> [accordion] Lista completa de bancos
>
> > [tab] A
> >
> > * A\&C COLANTA
> > * ACCIONES Y VALORES
> > * AFROAMERICANA
> > * ALCALICOOP
> > * AMAR
> > * AVANCOP
>
> > [tab] B
> >
> > * BADIVENCOOP
> > * BAN100
> > * BANCAMIA S A
> > * BANCO AGRARIO
> > * BANCO AV VILLAS
> > * BANCO BTG PACTUAL
> > * BANCO CAJA SOCIAL
> > * BANCO CONTACTAR
> > * BANCO DAVIVIENDA
> > * BANCO DE BOGOTA
> > * BANCO DE OCCIDENTE
> > * BANCO FALABELLA
> > * BANCO FINANDINA
> > * BANCO ITAÚ
> > * BANCO MUNDO MUJER
> > * BANCO POPULAR
> > * BANCO SERFINANZA
> > * BANCO SUDAMERIS
> > * BANCO UNION
> > * BANCO W
> > * BANCOLOMBIA
> > * BANCOOMEVA
> > * BBVA COLOMBIA
> > * BENEFICIAR
> > * BIENESTAR
> > * BOLD
>
> > [tab] C
> >
> > * CARDIOCOOP
> > * CAVIPETROL
> > * CESCA
> > * CFA
> > * CIDESA
> > * COAPAZ
> > * COASMEDAS
> > * COBELÉN
> > * CODEMA
> > * COEDUCADORES BOYACA
> > * COESCOOP
> > * COFACENEIVA
> > * COFINAL
> > * COINPROGUA
> > * COLTEFINANCIERA
> > * COMEDAL
> > * COMERCIACOOP
> > * COMULSEB
> > * COMULTRASAN
> > * COMUNA
> > * CONEXRED
> > * CONFIAMOS
> > * CONFIAR
> > * CONGENTE
> > * COOABEJORRAL
> > * COOACUEDUCTO
> > * COOBAGRE
> > * COOCREAFAM
> > * COODIN
> > * COOEDUCAR
> > * COOFINANCIAR
> > * COOFIPOPULAR
> > * COOFISAM
> > * COOFRASA
> > * COOGOMEZPLATA
> > * COOGRANADA
> > * COOINDEGABO
> > * COOINPE
> > * COOMBEL
> > * COOMEC
> > * COOMPARTIR
> > * COOMSERVI
> > * COOMULDESA
> > * COOMULTAGRO
> > * COOMULTRAISS
> > * COONECTA
> > * COONFIE
> > * COOPACREDITO SANTA ROSA
> > * COOPANTEX
> > * COOPARAMO
> > * COOPCANAPRO
> > * COOPCARVAJAL
> > * COOPCENTRAL
> > * COOPEAIPE
> > * COOPEBIS
> > * COOPECREDITO ENTRERRIOS
> > * COOPEMSURA
> > * COOPEMTOL
> > * COOPERATIVA ALIANZA
> > * COOPERATIVA AVANZA
> > * COOPERATIVA AVP
> > * COOPERATIVA CUB
> > * COOPEREN
> > * COOPERENKA
> > * COOPETEXAS
> > * COOPETROL
> > * COOPICREDITO
> > * COOPIGON
> > * COOPINTEGRATE
> > * COOPIO XII
> > * COOPJUDICIAL
> > * COOPLAROSA
> > * COOPMACEO
> > * COOPRIACHON
> > * COOPROCAL
> > * COOPROFESIONALES
> > * COOPROFESORES
> > * COOPROFESORESUN
> > * COOPRUDEA
> > * COOPSANFRANCISCO
> > * COOPSANSIMON
> > * COOPSERVIVÉLEZ
> > * COOPSOCIAL
> > * COOPSUYA
> > * COOPTENJO
> > * COOPTRAISS
> > * COOPVALLE
> > * COOPYARUMAL
> > * COOSANANDRESITO
> > * COOSANLUIS
> > * COOSANROQUE
> > * COOSERVUNAL
> > * COOSVICENTE
> > * COOTEP
> > * COOTRACERREJON
> > * COOTRACHEC
> > * COOTRADECUN
> > * COOTRAIPI
> > * COOTRAMED
> > * COOTRAPELDAR
> > * COOTRASENA
> > * COOTRAUNION
> > * COOTREGUA
> > * COOVITEL
> > * COPACREDITO
> > * COPROCENVA
> > * COPVILLANUEVA
> > * CORPECOL
> > * COTRAFA
> > * COTRASENA
> > * COVICSS
> > * COY-AMOR
> > * CREARCOOP
> > * CRECIAT
> > * CREDIFLORES
> > * CREDIFUTURO
> > * CREDISERVIR
> > * CREZCAMOS
>
> > [tab] D
> >
> > * DALE
> > * DAVIBANK
> > * DAVIPLATA
>
> > [tab] F
> >
> > * FAVI UTP
> > * FEBOR
> > * FECEL
> > * FECSA
> > * FEDANE
> > * FEDEJOHNSON
> > * FEDIAN
> > * FEG
> > * FELAFRANCOL
> > * FEMPHA
> > * FEPIMSA
> > * FESICOL
> > * FETRABUV
> > * FEU QUINDIO
> > * FINANCIERA COAGROSUR
> > * FINANCIERA COFINCAFE
> > * FINCOMERCIO
> > * FINECOOP
> > * FODELSA
> > * FODUN
> > * FONALIANZA
> > * FONCALDAS
> > * FONDECOM
> > * FONDECOR
> > * FONDUCAR
> > * FONEDH
> > * FONFABRICAFE
> > * FONRECAR
> > * FONVALLE
> > * FORJAR
> > * FOTRANORTE
>
> > [tab] G
> >
> > * GRANCOOP
>
> > [tab] J
> >
> > * JFK
> > * JURISCOOP
>
> > [tab] K
> >
> > * KAMIN
>
> > [tab] L
> >
> > * LULO BANK
>
> > [tab] M
> >
> > * MANUELITACOOP
> > * MICROEMPRESAS DE COLOMBIA
> > * MONO COLOMBIA
> > * MOVII
> > * MULTIACOOP
> > * MULTICOOP
> > * MUTUAL CANAPRO
> > * MUTUAL INTEGRAL
> > * MUTUAL SAN JERONIMO
>
> > [tab] N
> >
> > * NEQUI
> > * NU COLOMBIA
>
> > [tab] P
> >
> > * PAYU
> > * PEXTO
> > * POWWI
> > * PRESENTE
> > * PREVENSERVICIOS
> > * PROMEDICO
> > * PROSPERANDO
>
> > [tab] R
> >
> > * RAPPIPAY
>
> > [tab] S
> >
> > * SERVICONAL
> > * SERVIMCOOP
> > * SERVITRUST
> > * SUCREDITO
>
> > [tab] T
> >
> > * TAX LA FERIA
> > * TECNIPAGOS
> > * TELEPOSTAL
>
> > [tab] U
> >
> > * UALÁ
> > * UTRAHUILCA
>
> > [tab] V
> >
> > * VIDASOL

***

## Perguntas frequentes

> [accordion] 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.

> [accordion] 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](https://docs.localpayment.com/pt-br/docs/activate-deactivate-virtual-account.md) explicitamente. Você pode receber um número ilimitado de pagamentos para a mesma chave ao longo do tempo.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.
>
> Para payouts, nunca inclua `account.type` ou `account.number`, apenas `account.alias`.

> [accordion] 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 `[...]`).

> [accordion] 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):
>
> 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:

```
# Virtual Account (payin)
POST https://api.stage.localpayment.com/api/virtual-account

# Bank Transfer payout
POST https://api.stage.localpayment.com/api/payout/
```

### 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](https://docs.localpayment.com/pt-br/docs/receive-payment-notifications.md) 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](https://docs.localpayment.com/pt-br/docs/activate-deactivate-virtual-account.md) e [exclusão](https://docs.localpayment.com/pt-br/docs/delete-virtual-account.md) de Virtual Accounts.

***

## Próximos passos

> [card] [Gerenciar o ciclo de vida da Virtual Account](https://docs.localpayment.com/pt-br/docs/activate-deactivate-virtual-account.md)
>
> Ative ou desative as chaves Bre-B para pausar ou retomar temporariamente a cobrança de pagamentos sem excluir a Virtual Account.

> [card] [Reembolsar um Payin](https://docs.localpayment.com/pt-br/docs/refund-virtual-account-payment.md)
>
> Emita um reembolso para um pagamento Bre-B recebido através da API Localpayment ou do Business Portal.

> [card] [Instruções de pagamento](https://docs.localpayment.com/pt-br/docs/payment-instructions.md)
>
> Veja exatamente o que compartilhar com seus pagadores para pagamentos de Virtual Account na Colômbia.

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Recupere informações completas da transação usando a API Localpayment para auditoria e conciliação.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.