Crear Llave Bre-B

Visión General

Este endpoint permite crear una nueva llave Bre-B. Registra la vinculación entre un Merchant, su Account y una llave de pago específica, que se utilizará para el enrutamiento de pagos y la generación de códigos QR.

La creación de llaves puede procesarse de forma síncrona o asíncrona:

Creación inmediata: Si la llave se crea correctamente de forma inmediata, la API devuelve los datos de la llave con el estado ACTIVE.
Creación en proceso: Si Bre-B (DICE) aún está procesando el registro, la API devuelve una respuesta 202 Accepted con la llave en estado PENDING.
Llave pendiente: Una llave en estado PENDING no debe considerarse disponible para su uso. Los clientes deben esperar hasta que su estado cambie a ACTIVE o FAILED.

El estado definitivo de la llave puede consultarse mediante el endpoint GET /v1/keys/{id} o a través de la suscripción a los eventos de webhook correspondientes a la gestión de llaves.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/keys
Método	POST
Encabezados	Content-Type: application/json, Authorization
Autenticación	Token de Acceso (Bearer Token)

Información

Para poder crear una llave, el Cliente debe haber sido previamente registrado y contar con una cuenta activa (Vincular Cuenta) en el Banco Patrocinador.

Cuerpo de la Solicitud

Parámetro	Tipo	Restricciones	Requerido	Descripción
account_id	String	UUID	Sí	Identificador único de la cuenta con la que se desea asociar la llave.
key_type	String	ENUM: `ID`, `PHONE`, `EMAIL`, `ALPHA`, `BCODE`	Sí	Tipo de llave. `ID`: hasta 18 caracteres alfanuméricos, sin guiones, espacios ni caracteres especiales. `PHONE`: número móvil de 10 dígitos, debe empezar con 3. `EMAIL`: correo electrónico (máx. 92 caracteres; 30 antes del `@`, 61 después). `ALPHA`: alfanumérico de 6–21 caracteres, debe iniciar con `@` e incluir letras y números. `BCODE`: número de entidad comercial de 10 dígitos, comienza con `00`.
key_value	String	Varía según `key_type`.	Sí	Valor de la llave que se desea registrar (ejemplo: correo electrónico o número móvil).
display_name	String		No	Durante el proceso de resolución de llaves, se mostrará el nombre para mostrar al usuario pagador, para mayor claridad y referencia. Sirve como un identificador importante, ayudando a los usuarios a reconocer fácilmente al destinatario involucrado en la transacción.

Relación Llaves Bre-B y Cuentas

La relación entre una cuenta y sus llaves es de tipo 1:M, lo que significa que una cuenta puede tener una o más llaves asociadas.

Ejemplo de Solicitud

curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.com/v1/keys' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \

--data '{

"account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc",

"key":{

"key_type": "BCODE",

"key_value": "0016027228"

"display_name": "Pepito Silva"

Cuerpo de la Respuesta

Código HTTP: 200 OK
Retorna los datos de la llave creada junto con su ID único.

Ejemplo de Respuesta

{

"status": "ACTIVE",

"key": {

"key_type": "BCODE",

"key_value": "0016027228"

"display_name": "Pepito Silva",

"account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc",

"created_at": "2025-10-09T10:42:39.710Z",

"updated_at": "2025-10-09T10:42:39.710Z",

"id": "3184cbfd-73bd-4910-bd03-f8461e724247"

}

Importante

El id que se genera en la respuesta es el key_id.

Errores Comunes y Manejo

Código HTTP	Significado	Descripción
400 Bad Request	Datos inválidos	Faltan campos requeridos o contienen valores incorrectos.
401 Unauthorized	Token inválido	El token de acceso ha expirado o es inválido.
403 Forbidden	Acceso denegado	La solicitud no está autorizada para crear una llave.
500 Server Error	Error del servidor	Se produjo un error inesperado en el momento de crear la llave.

Buenas Prácticas

Utiliza el tipo de llave correcto: Asegúrate de que el key_type coincida con el formato del key_value (por ejemplo, E para correos electrónicos).
Evita llaves duplicadas: Las llaves deben ser únicas en todo el sistema. Una cuenta puede tener múltiples llaves, pero una misma llave no puede estar asociada a más de una cuenta o usuario.

Última actualización el