> ## 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 (Colombia)

Bre-B es la plataforma nacional de pagos en tiempo real de Colombia, operada por Banco de la República. Acepta pagos instantáneos entre particulares las 24 horas del día, los 7 días de la semana, mediante claves de cuentas virtuales (pagos entrantes) y envía fondos directamente a cualquier clave Bre-B (pagos salientes), todo a través de una única integración.

**Bre-B** es la primera plataforma de pagos en tiempo real de Colombia, impulsada por el gobierno y lanzada el 6 de octubre de 2025 por el Banco de la República. Por primera vez, todos los bancos, monederos electrónicos y proveedores de servicios de pago autorizados en el país comparten una única infraestructura instantánea e interoperable, de forma similar a como [Pix](https://docs.localpayment.com/es/docs/pix-brazil.md) transformó Brasil.

Bre-B introduce transferencias instantáneas entre cuentas (A2A) en menos de 20 segundos, disponibilidad las 24 horas, los 7 días de la semana, los 365 días del año, y pagos basados en alias (llamados *llaves*) que eliminan la necesidad de compartir números de cuenta completos. La participación es obligatoria para todas las instituciones financieras reguladas, lo que convierte a Bre-B en la plataforma de pagos de mayor crecimiento en la historia de Colombia.

Localpayment admite Bre-B tanto para **recibir** como para **enviar** pagos:

| Flujo | Método | Código de pago | Divisa | Cantidad máxima |
| - | - | - | - | - |
| **Payin** (recepción) | Cuenta virtual | `2006` | COP | COP 12.110.000 |
| **Payout** (envío) | Transferencia bancaria | `0062` | COP | COP 11.552.000 |

***

## Descripción general

### Bre-B vs. PSE: ¿Cuándo usar cada uno?

Colombia ya cuenta con el [PSE](https://docs.localpayment.com/es/docs/pse-colombia.md) como opción de pago A2A establecida. Bre-B no lo reemplaza, sino que añade una alternativa más rápida y siempre disponible. Utiliza esta tabla para elegir el método adecuado para tu caso de uso:

| Característica | PSE | Bre-B |
| - | - | - |
| **Liquidación** | Ciclos de procesamiento por lotes: dependen de los plazos de cierre bancario. | Instantáneo, en cualquier momento: sin demoras en la compensación. |
| **Disponibilidad** | Solo en horario bancario (normalmente de 8:00 a 17:00, de lunes a viernes). | 24 horas al día, 7 días a la semana, 365 días al año, incluyendo noches, fines de semana y festivos. |
| **Experiencia de pago** | Se requieren todos los datos de la cuenta + redireccionamiento bancario | Sin redirección: el pagador utiliza un alias (*llave*) o un código QR. |
| **Interoperabilidad** | Solo bancos participantes, el flujo varía | Obligatorio para todos los bancos, monederos electrónicos y proveedores de servicios de pago autorizados. |
| **Velocidad de confirmación** | De horas a días, dependiendo del momento. | Menos de 20 segundos, garantizado |
| **Ideal para** | Flujos establecidos con integración PSE existente | Nuevas integraciones, casos de uso en tiempo real, cobertura 24/7. |

### Llave Bre-B

La *llave* es un alias alfanumérico corto que reemplaza el número completo de cuenta bancaria para las transferencias Bre-B. Los pagadores solo tienen que ingresar la llave en su aplicación bancaria; no se requieren los datos completos de la cuenta.

**Cómo genera Localpayment tu clave**

Al crear una cuenta virtual para Colombia, Localpayment genera automáticamente una **clave alfanumérica**; no es necesario elegir ni configurar un tipo de clave. La clave se genera de forma determinista a partir del nombre del beneficiario que tú proporcionas.

| Parte | Contenido | Descripción |
| - | - | - |
| **1** | `LP` | Prefijo fijo que identifica a Localpayment como el emisor principal. |
| **2** | Hasta 10 caracteres alfanuméricos | Primeros caracteres del nombre del beneficiario después de eliminar espacios y caracteres especiales (p. ej., `-`, `.`, acentos). |
| **3** | Contador secuencial de 4 dígitos | Contador con ceros a la izquierda que se incrementa por cada clave emitida (p. ej., `0001`, `0002`, `0003`). |

**Longitud total de la clave**: entre 10 y 16 caracteres alfanuméricos (el símbolo de prefijo `@` no se cuenta).

**Ejemplo**: nombre del beneficiario `"TechColombia SAS"`:

1. Elimina los espacios y caracteres especiales → `TechColombiaSAS`
2. Toma los primeros 10 caracteres alfanuméricos → `TechColomb`
3. Combina → `@` + `LP` + `TechColomb` + `0001` = **`@LPTechColomb0001`** (16 caracteres)

La clave generada se devuelve en `beneficiary.bank.account.number` una vez que la cuenta virtual se activa (`status.code: "200"`).

### Límites y disponibilidad

| Propiedad | Payin (código `2006`) | Payout (código `0062`) |
| - | - | - |
| Divisa | `COP` | `COP` |
| Cantidad mínima | COP 1.00 | COP 1.00 |
| Cantidad máxima | COP 12.110.000,00 | COP 11.552.000,00 |
| Velocidad de liquidación | Tiempo real (\< 20 s) | Tiempo real (\< 20 s) |
| Availability | 24/7/365 | 24/7/365 |
| Confirmación de pago | Asíncrono (webhook) | Asíncrono (webhook) |

### Demo

Mira cómo interactúa un pagador con una cuenta virtual de Bre-B en la práctica:

[Contenido incrustado](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)

***

## Recepción de pagos de Bre-B (Pago entrante)

Payin a través de Bre-B utiliza la infraestructura de **[Cuenta Virtual](https://docs.localpayment.com/es/docs/virtual-accounts-overview.md)**. Localpayment genera una clave alfanumérica única de Bre-B para cada cuenta que crees. Los pagadores envían fondos a esa clave desde cualquier aplicación bancaria compatible con Bre-B. La liquidación es instantánea y totalmente automatizada.

### Cómo funciona

1. Crear una cuenta virtual: tu sistema llama al endpoint Crear cuenta virtual con los detalles del beneficiario.
2. Recuperar la clave Bre-B: una vez que la cuenta se active (\~6 segundos), consulta tu estado para obtener la clave generada por el sistema desde `beneficiary.bank.account.number`.
3. Comparte la clave con el pagador: el pagador introduce la clave en su aplicación bancaria para iniciar la transferencia.
4. Recepción de fondos y webhook: Localpayment recibe la transferencia y envía un webhook en tiempo real al endpoint configurado.

### Antes de comenzar

Asegúrate de tener:

* [Credenciales API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md) válidas (token de acceso).
* Una cuenta de Localpayment configurada para [Colombia](https://docs.localpayment.com/es/docs/colombia.md) (`COP`).

***

### Paso 1. Crea una cuenta virtual

Envía una solicitud `POST` al endpoint [Crear cuenta virtual](https://docs.localpayment.com/es/reference/create-virtual-account.md).

#### Parámetros clave de la solicitud

| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
| - | - | - | - | - |
| `country` | string | ✅ | Debe ser `COL` para Colombia. | `"COL"` |
| `accountNumber` | string | ✅ | Tu número de cuenta comercial de Localpayment. | `"{{accountNumber}}"` |
| `externalId` | string | ✅ | Tu identificador único para esta cuenta virtual. Utiliza un UUID. | `"a1b2c3d4-..."` |
| `beneficiary.type` | string | ✅ | `INDIVIDUAL` (persona física) o `COMPANY` (persona jurídica). | `"COMPANY"` |
| `beneficiary.name` | string | ✅ | Nombre completo o razón social. Los primeros caracteres se utilizan para generar la clave Bre-B. | `"TechColombia SAS"` |
| `beneficiary.document.type` | string | ✅ | `NIT` para empresas; `CC`, `CE`, `TI` o `PASS` para personas físicas. | `"NIT"` |
| `beneficiary.document.id` | string | ✅ | Número de documento que coincida con el formato del tipo seleccionado. | `"901275418-3"` |

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/create-virtual-account.md) en la referencia de la API.

#### Ejemplo de solicitud

```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"
    }
  }
}'
```

#### Respuesta exitosa

```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": []
}
```

#### Respuesta de error

```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]
>
> **Tiempo de activación**: Las cuentas virtuales de Colombia suelen activarse en **6 segundos**. Consulta el estado en el endpoint o espera brevemente antes de recuperar la clave Bre-B.

> [!NOTE]
>
> **Beneficiarios no locales**
>
> Si tu beneficiario es residente extranjero (no reside en Colombia), la cuenta virtual debe estar registrada en Localpayment a nombre del titular. Esto garantiza el cumplimiento de la normativa bancaria local y, al mismo tiempo, te permite recibir pagos en nombre de entidades extranjeras.

***

### Paso 2. Recupera tu llave Bre-B

Una vez que la cuenta virtual esté activa (`status.code: "200"`), envía una solicitud `GET` al endpoint [Obtener estado de la cuenta virtual](https://docs.localpayment.com/es/reference/get-virtual-account-status.md).

#### Ejemplo de solicitud

```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'
```

#### Respuesta exitosa

```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 respuesta clave

| Campo | Descripción |
| - | - |
| `beneficiary.bank.account.number` | La clave Bre-B para compartir con el pagador (p. ej., `@LPTechColomb0001`). |
| `beneficiary.bank.account.type` | Siempre `KEY` para las cuentas virtuales Bre-B. |
| `status.code` | `200` = activa y lista para recibir. `100` = aún en proceso de activación. |

Comparte el valor de `beneficiary.bank.account.number` con el pagador. No se requieren datos adicionales de la cuenta bancaria.

***

### Paso 3. El pagador inicia la transferencia

El pagador utiliza la clave Bre-B en cualquier aplicación bancaria o billetera digital colombiana participante:

1. Abre tu aplicación bancaria y selecciona la opción Bre-B o **Transferencia por clave**.
2. Introduce la clave Bre-B (p. ej., `@LPTechColomb0001`) como destino.
3. Introduce el importe y confirma la transferencia.
4. El pago se completa en menos de 20 segundos.

Localpayment asocia automáticamente el pago entrante con tu cuenta virtual y envía un webhook.

***

### Paso 4. Gestionar los webhooks

Localpayment envía una solicitud `POST` al endpoint configurado una vez que el pago se acredita. Tu servidor debe responder con `HTTP 200 OK` para confirmar la recepción. Consulta la [guía de Webhooks](https://docs.localpayment.com/es/docs/webhooks.md) para ver las instrucciones de configuración.

#### Ejemplo de payload del 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 clave del webhook

| Campo | Descripción |
| - | - |
| `paymentMethod.code` | Siempre `2006` para los payins de cuentas virtuales Bre-B. |
| `status.code` | `200` = `COMPLETED`: los fondos han sido acreditados. |
| `beneficiary.bank.account.number` | La clave Bre-B de tu cuenta virtual que recibió el pago. |
| `payer.bank.account.type` | `BREB`: confirma que el pagador envió a través de la red Bre-B. |
| `tracking.id` / `tracking.reference` | Referencia de transacción de la red Bre-B. Utilizar para la [conciliación](https://docs.localpayment.com/es/docs/reporting-and-reconciliation.md). |
| `tracking.concept` | Descripción de la transferencia proporcionada por el pagador. |
| `referenceCode` | Referencia única de Localpayment para esta transacción. |

***

### Paso 5. Seguimiento del estado de los pagos

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando se abone un pago. Ideal para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para conciliar las notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado.

Bre-B es una plataforma de pagos directos en tiempo real: las transacciones se liquidan al instante. El webhook se activa solo cuando el pago se ha acreditado por completo.

| Código | Estado | Descripción |
| :- | :- | :- |
| `200` | `COMPLETED` | Pago abonado a tu cuenta. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Envío de pagos de Bre-B (desembolso)

Para enviar fondos a la clave Bre-B de un destinatario, utiliza el flujo de **[Payout por transferencia bancaria](https://docs.localpayment.com/es/docs/send-funds-via-bank-transfer.md)** con el código de método de pago `0062`. El destinatario debe tener una clave Bre-B registrada en su banco. Tú proporcionas esa clave mediante `beneficiary.bank.account.alias`.

### Cómo funciona

1. Recopila la clave Bre-B del destinatario: obtén la llave registrada del destinatario (cualquier tipo de clave compatible: alfanumérica, teléfono, correo electrónico, documento o código de comerciante).
2. Envía el payout: llama al endpoint Crear Payout con el código `0062` y la clave en `beneficiary.bank.account.alias`.
3. Realiza el seguimiento de la transferencia: supervisa el estado a través de webhooks o la API de estado hasta `200 Completed`.

***

### Paso 1. Iniciar el pago

Envía una solicitud `POST` al endpoint [Crear un Payout](https://docs.localpayment.com/es/reference/create-a-payout.md). Ten en cuenta que el cuerpo de la solicitud es un **array**.

#### Parámetros clave de la solicitud

| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
| - | - | - | - | - |
| `country` | string | ✅ | Debe ser `COL`. | `"COL"` |
| `currency` | string | ✅ | Debe ser `COP`. | `"COP"` |
| `amount` | number | ✅ | Importe de la transacción. Mínimo COP 1,00, máximo COP 11.552.000,00. | `50000` |
| `paymentMethod.type` | string | ✅ | Debe ser `BankTransfer`. | `"BankTransfer"` |
| `paymentMethod.code` | string | ✅ | Debe ser `0062` para Bre-B. | `"0062"` |
| `paymentMethod.flow` | string | ✅ | Debe ser `DIRECT`. | `"DIRECT"` |
| `beneficiary.type` | string | ✅ | `INDIVIDUAL` o `COMPANY`. | `"INDIVIDUAL"` |
| `beneficiary.name` | string | ✅ | Nombre del destinatario o nombre de la empresa. | `"John"` |
| `beneficiary.lastName` | string | ✅ | Apellido del destinatario (solo para personas físicas). | `"Doe"` |
| `beneficiary.document.type` | string | ✅ | `CC`, `NIT`, `CE`, `TI` o `PASS`. | `"CC"` |
| `beneficiary.document.id` | string | ✅ | Número de documento que coincida con el formato del tipo seleccionado. | `"1088338888"` |
| `beneficiary.bank.account.alias` | string | ✅ | Clave Bre-B registrada del destinatario (llave). **No** incluyas `account.type` ni `account.number`. | `"@juanPerez0001"` |
| `accountNumber` | string | ✅ | Tu número de cuenta comercial de Localpayment. | `"{{accountNumber}}"` |
| `externalId` | string | ✅ | Tu identificador único para este pago. Utiliza un UUID. | `"b2c3d4e5-..."` |
| `conceptCode` | string | ✅ | Código del concepto de pago proporcionado por Localpayment. | `"0001"` |

> [!WARNING]
>
> **Importante**: Al enviar a una clave Bre-B, los campos `beneficiary.bank.account.type` y `beneficiary.bank.account.number` deben **excluirse** de la solicitud. Utiliza solo `beneficiary.bank.account.alias`.

#### Ejemplo de solicitud

```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"
  }
]'
```

#### Respuesta exitosa

```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
}
```

#### Respuesta de error

```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"
      }
    ]
  }
]
```

***

### Paso 2. Seguimiento del estado del pago

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando se realice el cargo a la transferencia. Ideal para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta programáticamente el estado de los pagos. Útil para la conciliación y el manejo de excepciones.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para supervisar y aprobar manualmente los pagos.

| Código | Estado | Descripción |
| :- | :- | :- |
| `100` | `Received` | El pago fue recibido por Localpayment. |
| `101` | `Locked` | Validaciones AML confirmadas y superadas. |
| `102` | `In Progress` | Enviado a la red Bre-B. |
| `200` | `Completed` | Fondos abonados al beneficiario. |
| `300` | `Rejected` | Parámetro no válido: revisa el array `errors` para ver los detalles. |

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Bancos admitidos

Los pagos con Bre-B se pueden enviar y recibir a través de todas las instituciones financieras colombianas participantes: más de 200 bancos, monederos digitales y cooperativas conectadas a la red del 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

***

## Preguntas frecuentes

> [accordion] ¿Cuánto tiempo tarda en activarse mi cuenta virtual de Bre-B?
>
> Las cuentas virtuales de Colombia suelen activarse en **6 segundos**. La respuesta de creación de la VA devuelve `status.code: "100" INPROGRESS`. Consulta el endpoint Obtener estado de la cuenta virtual hasta recibir `status.code: "200" COMPLETED` antes de compartir la clave con los pagadores.

> [accordion] ¿Puedo usar la misma clave Bre-B para varios pagos?
>
> Sí. Una cuenta virtual y su clave Bre-B asociada permanecen activas hasta que las [desactives o elimines](https://docs.localpayment.com/es/docs/activate-deactivate-virtual-account.md) explícitamente. Puedes recibir un número ilimitado de pagos a la misma clave a lo largo del tiempo.

> [accordion] ¿Qué sucede si un pagador envía una cantidad superior al máximo permitido?
>
> Las transferencias que superen el límite máximo (COP 12.110.000 para depósitos y COP 11.552.000 para pagos) serán rechazadas por la red Bre-B. El pagador verá un error en su aplicación bancaria. Para transferencias de alto valor, divídelas en varias transacciones.

> [accordion] ¿Puedo recibir pagos de Bre-B fuera del horario comercial?
>
> Sí, Bre-B opera las 24 horas del día, los 7 días de la semana, los 365 días del año, por mandato del Banco de la República. No hay horarios restringidos, ni fines de semana, ni días festivos.

> [accordion] ¿Cuál es la diferencia entre account.number y account.alias?
>
> Estos campos cumplen diferentes funciones según el flujo:
>
> * **`beneficiary.bank.account.number`**: Se usa en la **respuesta** de Obtener estado de la cuenta virtual — aquí es donde Localpayment devuelve la clave Bre-B generada automáticamente para tu cuenta virtual de payin. Es un campo de salida de solo lectura.
> * **`beneficiary.bank.account.alias`**: Se usa en la **solicitud** de Crear Payout — aquí es donde tú proporcionas la clave Bre-B del destinatario al iniciar un payout. Es un campo de entrada.
>
> Para los payouts, nunca incluyas `account.type` ni `account.number`, solo `account.alias`.

> [accordion] ¿Por qué se rechaza mi solicitud de Payout con el mensaje 'Invalid param + \[paymentMethod.code]'?
>
> Este error normalmente significa que `paymentMethod.code` no es `"0062"` o que `paymentMethod.type` no es `"BankTransfer"`. Verifica ambos campos y asegúrate de que `paymentMethod.flow` esté configurado como `"DIRECT"`. Confirma también que estás enviando el cuerpo de la solicitud como un **array** JSON (envuelto en `[...]`).

> [accordion] ¿Cómo genera Localpayment la clave Bre-B para mi cuenta virtual?
>
> La clave se genera de forma determinista a partir del nombre del beneficiario que tú proporcionas al crear el VA:
>
> 1. Elimina todos los espacios y caracteres especiales del nombre del beneficiario.
> 2. Toma los primeros 10 caracteres alfanuméricos de la cadena resultante.
> 3. Combina: `@` + `LP` + segmento del nombre + contador secuencial de 4 dígitos.
>
> Ejemplo: `"TechColombia SAS"` → elimina los espacios → `TechColombiaSAS` → primeros 10 → `TechColomb` → clave = `@LPTechColomb0001`.
>
> El contador (`0001`, `0002`, etc.) se incrementa con cada clave emitida. La longitud final de la clave está entre 10 y 16 caracteres alfanuméricos, excluyendo el símbolo `@`.

***

## Probando tu integración

### Entorno de pruebas

Utiliza el entorno de prueba para todas las pruebas:

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

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

### Escenarios de prueba

Verifica que tu integración gestione estos escenarios:

1. **Creación de la VA**: crea una cuenta virtual para Colombia y confirma la respuesta `100 INPROGRESS`.
2. **Recuperación de la clave**: consulta el endpoint de estado hasta que `status.code: "200"` y luego verifica que `beneficiary.bank.account.number` contenga una clave Bre-B válida.
3. **Recepción de pago (Payin)**: simula un pago Bre-B entrante y valida que tu controlador de webhook devuelva `HTTP 200`. Consulta [Recibir notificaciones de pago](https://docs.localpayment.com/es/docs/receive-payment-notifications.md) para la configuración de webhooks.
4. **Envío de payout**: envía un payout con el código `0062` y un `beneficiary.bank.account.alias` válido.
5. **Manejo de notificaciones duplicadas**: verifica que tu sistema gestione los reintentos de webhook de forma idempotente usando `internalId` o `externalId`.
6. **Ciclo de vida de la cuenta**: Prueba a [habilitar, deshabilitar](https://docs.localpayment.com/es/docs/activate-deactivate-virtual-account.md) y [eliminar](https://docs.localpayment.com/es/docs/delete-virtual-account.md) cuentas virtuales.

***

## Próximos pasos

> [card] [Gestionar el ciclo de vida de las cuentas virtuales](https://docs.localpayment.com/es/docs/activate-deactivate-virtual-account.md)
>
> Habilita o deshabilita las claves Bre-B para pausar o reanudar temporalmente el cobro de pagos sin eliminar la cuenta virtual.

> [card] [Reembolsar un Payin](https://docs.localpayment.com/es/docs/refund-virtual-account-payment.md)
>
> Emitir un reembolso por un pago Bre-B recibido a través de la API de Localpayment o el Business Portal.

> [card] [Instrucciones de pago](https://docs.localpayment.com/es/docs/payment-instructions.md)
>
> Consulta exactamente qué información debes compartir con tus pagadores para los pagos a cuentas virtuales en Colombia.

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Recupera la información completa de la transacción utilizando la API de Localpayment para fines de auditoría y conciliación.


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