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

# Crear llave Bre-B de un cliente

> Asigna a un cliente su propia llave Bre-B para recibir transferencias en su billetera, y devuelve su QR.

Crea una llave Bre-B a nombre de uno de tus clientes. Lo que le transfieran a esa llave entra directo al saldo de su billetera, que consultas con [Saldo](https://docs.onepay.la/client/wallets/balance.md) y [Movimientos](https://docs.onepay.la/client/wallets/transactions.md).

La respuesta trae también el QR de la llave, listo para mostrárselo al cliente.

> [!NOTE]
>
> Disponible para empresas con billeteras (Fintech as a service) activas. Si tu empresa no las tiene, el endpoint responde `403`.

### Path

**customer\_id** `string` *required*

ID del cliente que va a recibir la llave. [Crear cliente](https://docs.onepay.la/client/customers/create.md).

### Body

**account\_number** `string` *required*

Llave que quieres asignar, sin el `@`. Mínimo 5 caracteres, y no puede estar registrada ya en Bre-B. Usa solo letras y números: Bre-B registra la llave solo con esos caracteres, y quien te transfiere la escribe con `@` adelante (`@juanperez`). Siempre es una llave alfanumérica: si mandas solo números, queda como `@3001234567` y no como una llave de celular o de cédula.

### QR de la llave

* **Es estático:** no lleva monto. Quien escanea escribe cuánto transfiere desde su app bancaria.
* **Muestra el nombre de tu empresa**, cortado a 19 caracteres. Es el mismo nombre que ve quien transfiere a la llave.
* **`qr.image`** es la imagen en base64 con su prefijo `data:image/png;base64,`, así que va directo en un `<img>`:

```html theme={null}
<img src="data:image/png;base64,iVBORw0KGgoAAAANS..." />
```

* **El QR solo llega en esta respuesta.** Guárdalo: hoy no hay un endpoint para volver a pedirlo.
* **`qr` puede venir en `null`** si el QR no se pudo generar. La llave queda creada igual y recibe transferencias.

```bash cURL theme={null}
curl https://api.onepay.la/v1/customers/9dd4158b-0e45-42bc-b56f-a4c1f856814d/accounts/bre-b \
  -X POST \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "account_number": "juanperez"
  }'
```

```javascript JavaScript theme={null}
const customerId = '9dd4158b-0e45-42bc-b56f-a4c1f856814d';

const response = await fetch(`https://api.onepay.la/v1/customers/${customerId}/accounts/bre-b`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    account_number: 'juanperez'
  })
});
const account = await response.json();

// La llave que el cliente comparte y la imagen del QR para mostrarle
console.log(account.external_id);
console.log(account.qr?.image);
```

```python Python theme={null}
import requests

customer_id = "9dd4158b-0e45-42bc-b56f-a4c1f856814d"
url = f"https://api.onepay.la/v1/customers/{customer_id}/accounts/bre-b"
headers = {
    "Authorization": "Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
data = {
    "account_number": "juanperez"
}

response = requests.post(url, headers=headers, json=data)
account = response.json()

# La llave que el cliente comparte y la imagen del QR para mostrarle
print(account["external_id"])
print((account.get("qr") or {}).get("image"))
```

```php PHP theme={null}
<?php
$customerId = "9dd4158b-0e45-42bc-b56f-a4c1f856814d";

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.onepay.la/v1/customers/{$customerId}/accounts/bre-b",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi",
        "Content-Type: application/json",
        "Accept: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "account_number" => "juanperez"
    ])
]);

$response = curl_exec($ch);
$account = json_decode($response, true);
curl_close($ch);

// La llave que el cliente comparte y la imagen del QR para mostrarle
echo $account["external_id"];
echo $account["qr"]["image"] ?? "";
```

```json 201 theme={null}
{
  "id": "9e184fda-62bb-477b-9020-fa59f44f2b99",
  "title": "juanperez",
  "subtype": "KEY_STATIC",
  "status": "VALIDATED",
  "authorization": false,
  "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
  "re_enroll": false,
  "external_id": "@juanperez",
  "bank_id": "9e01d019-b731-48bc-b111-2baa3ea56ef6",
  "bank": {
    "id": "9e01d019-b731-48bc-b111-2baa3ea56ef6",
    "name": "ONE BANK",
    "logo": "https://cdn.onepay.la/banks/co/one-bank.svg"
  },
  "customer": {
    "id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "document_type": "CC",
    "document_number": "1234567890",
    "created_at": "2026-01-15T10:00:00.000000Z",
    "is_test": false
  },
  "qr": {
    "image": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "string": "00020101021126ABC123...",
    "id": "ABC123DEF456789GHx"
  }
}
```

```json 422 Llave ocupada theme={null}
{
  "message": "Esta llave BreB ya existe, por favor usa otra.",
  "code": 10001,
  "code_name": "validation_error",
  "errors": {
    "account_number": [
      "Esta llave BreB ya existe, por favor usa otra."
    ]
  }
}
```

```json 403 theme={null}
{
  "message": "Company does not have this feature."
}
```

```json 404 theme={null}
{
  "message": "Registro no encontrado, Cliente no existe",
  "code": 10002,
  "code_name": "record_not_found"
}
```

### Campos de respuesta

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | ID de la llave en OnePay |
| `subtype` | string | Siempre `KEY_STATIC`: llave fija que no vence |
| `status` | string | `VALIDATED` cuando la llave quedó registrada en Bre-B |
| `external_id` | string | La llave tal como se comparte, con `@` |
| `customer_id` | string | Cliente dueño de la llave |
| `qr.image` | string | Imagen del QR en base64, con prefijo `data:image/png;base64,` |
| `qr.string` | string | Contenido del QR como texto, por si prefieres dibujarlo tú |
| `qr.id` | string | ID del QR en Bre-B |

`qr` viene en `null` cuando el QR no se pudo generar. La llave sirve igual.

### Errores de la llave

Además de `Esta llave BreB ya existe`, el `422` puede traer estos mensajes en `errors.account_number`. En los dos casos, pide otra llave:

* `Esta llave ya existe en Kamin. Por favor usa otra.`
* `Esta llave ya está registrada en otra entidad financiera.`

### Flujo

1. Crea el cliente con [Crear cliente](https://docs.onepay.la/client/customers/create.md), si todavía no existe.
2. Llama a este endpoint con la llave que el cliente eligió.
3. Muéstrale al cliente su llave (`external_id`) y su QR (`qr.image`).
4. Lo que le transfieran entra a su billetera: consúltalo con [Saldo](https://docs.onepay.la/client/wallets/balance.md) y [Movimientos](https://docs.onepay.la/client/wallets/transactions.md).
5. Para ver las llaves de un cliente, usa [Cuentas del cliente](https://docs.onepay.la/client/customers/accounts.md).


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