Llaves Cobre con Bre-B

La API de Cobre Key proporciona servicios para crear, gestionar y obtener llaves de Bre-B asignadas por Cobre.

Una Cobre Key es un identificador único que permite a los usuarios finales enviar fondos a un destinatario sin requerir los detalles tradicionales de cuenta bancaria, habilitando la cobranza de dinero sin interrupciones a través de rieles de pago inmediatos.

Las Cobre Keys actúan como identificadores de destino reutilizables y se utilizan comúnmente para cobrar fondos al instante, simplificando la experiencia de pago tanto para individuos como para empresas que interactúan con la plataforma de Cobre.

Las Cobre Keys no tienen fecha de vencimiento, por lo que pueden usarse tantas veces como sea necesario para recibir payins.

Límites de Transferencia Bre-B para Payins

Las Cobre Keys, como todas las llaves Bre-B en Colombia, pueden recibir transferencias hasta el monto máximo permitido por la red Bre-B. Sin embargo, el monto que un pagador puede enviar a una Cobre Key puede estar sujeto a límites más bajos impuestos por su banco.

Combinaciones Permitidas

Al crear una Cobre Key, se deben tener en cuenta los tipos de cuenta soportados y las geografías, como se detalla a continuación:

Tipo de Cuenta	Geo	Tipo de Llave	Ejemplo de Valor de Llave
Cobre Balance	COL	Alfanumérico	@CBARG452PEXTOCOLOMBI

Estructura y personalización de llaves

Tipos de Cobre Key

Cobre soporta diferentes tipos de Cobre Keys, cada uno diseñado para necesidades específicas de identificación y experiencia de usuario.

Name: Genera una Cobre Key basada en los primeros 12 caracteres (sin espacios) del alias del cliente.

ID: Genera una Cobre Key basada en los primeros 9–10 dígitos del número de identificación del cliente.

Random: Genera una Cobre Key usando caracteres alfanuméricos aleatorios.

Open Input: Genera una Cobre Key usando cualquier valor alfanumérico que desees ingresar.

El alias utilizado para llaves basadas en nombre puede configurarse desde el Portal de Cobre o mediante una solicitud a través de nuestros canales de soporte.

Tipo de Llave	Longitud	Ejemplo
`name`	21	@CBARG452PEXTOCOLOMBI
`ID`	17-18	@CBAQ1ER9001234567
`random`	10	@CBAQ1EXD8
`open_input`	21	@MYPERSONALIZEDKEY123

open_input: Únicamente letras y números son permitidos, sin espacios, mínimo 5 caracteres y máximo 20 para la parte personalizable.

name: Puedes crear llaves tipo name con un alias al inicio para mejorar tu visibilidad de marca en las llaves generadas. Por ejemplo: @PEXTOCOLOMBICBARG452
Contacta a tu KAM para habilitar este feature

Ahora puede personalizar el nombre del titular de sus llaves Bre-B para que sus contrapartes vean el nombre de su cliente como destino de la transacción, en lugar del nombre predeterminado de Pexto o el nombre de su empresa. Esta función es compatible con todos los tipos de llaves Cobre.

Guía Rápida: Cobre Key soportados por Flujo

Método de Pago	open_input	name	id	random
Direct link Key		x	x	x
Direct link Qr				x
Checkout Key				x
Checkout Qr				x
Static Key	x	x	x	x

Ciclo de vida de Cobre Key y acciones previas

El objeto Cobre Key incluye información sobre la previous_action realizada por el cliente. Esto te permite:

Identificar si el cliente intentó crear, bloquear, reactivar o eliminar una llave

Comparar la acción solicitada con el estado actual de la Cobre Key para determinar si la operación fue procesada exitosamente

Las acciones de administración de Cobre Key están integradas en el ciclo de vida de la llave, como sigue:

estado	descripción
`processing`	Un estado intermedio que indica que la creación de Cobre Key enviada aún está siendo procesada
`registered`	La Cobre Key fue creada y registrada exitosamente, y ahora está disponible para uso
`unregistered`	La Cobre Key fue cancelada por solicitud del usuario a través de nuestra API de cancelación de llaves. Una vez cancelada, una llave no puede ser reactivada
`disabled`	La Cobre Key fue deshabilitada por el usuario o por Cobre. Una llave en estado deshabilitado puede ser reactivada
`failed`	La acción intentada sobre la llave no fue exitosa y es necesario enviar la solicitud de creación nuevamente

Ten en cuenta que la creación de Cobre Key es asíncrona, por lo que las solicitudes de creación siempre retornarán en estado processing. El estado final de la llave debe verificarse posteriormente a través del endpoint de obtener todas las llaves o el endpoint de obtener una específica, y por lo tanto los campos key_value y source_id solo serán devueltos una vez que la llave transite al estado registered.

Idempotencia de Cobre Key

La creación de Cobre Key actualmente no soporta idempotencia.

En este momento, solo se puede crear una Cobre Key por cuenta de Cobre Balance.

Acciones realizadas en una Cobre Key

🔑 Crear

🔍 Obtención

❌ Bloquear o Reactivar

❌ Cancelar

Descripción: Creación de Cobre Key.
Qué esperar después de la acción: La Cobre Key es creada en Cobre.
📘 Aprende más:

🔗 Crear una Cobre Key

Cómo Comenzar

Antes de empezar, recomendamos revisar las siguientes consideraciones.

Antes de usar esta API

Necesitas un Cobre Balance en Colombia

Para poder crear una Cobre Key, debes tener una cuenta de Cobre Balance en Colombia.

Define el tipo de Cobre Key

Antes de crear una Cobre Key, considera cuidadosamente qué tipo de llave se adapta mejor a tu caso de uso. El tipo seleccionado determina cómo se genera, gestiona y reutiliza el valor de la llave a través de tus flujos de pago.

Implementa Webhooks para rastrear el estado de Cobre Key

Para mantenerte informado sobre cambios en el ciclo de vida de una Cobre Key, recomendamos encarecidamente implementar Webhooks. Los Webhooks notifican a tu sistema en tiempo real cuando una Cobre Key es creada, habilitada, deshabilitada o eliminada, permitiéndote reaccionar prontamente a cada cambio de estado. También suscríbete a los eventos requeridos para recibir notificaciones sobre créditos de transacciones.

Ver Notificaciones para más detalles.

Qué esperar después de usar esta API

Comenzar a recibir transferencias

Una vez que la Cobre Key es creada y está disponible, puedes exponerla a tus usuarios finales para comenzar a recibir transferencias a través de la llave y tener los fondos acreditados directamente a tu Cobre Balance. Verás una transacción de crédito tipo breb_credit en la cuenta de Cobre Balance vinculada a la llave.

Bloquear o Reactivar una Cobre Key

Una vez que la Cobre Key es creada y está disponible, puedes habilitarla o deshabilitarla en cualquier momento, dependiendo de tus necesidades operacionales o de negocio.

Eliminar una Cobre Key

Una vez que la Cobre Key es creada y está disponible, puedes eliminarla si ya no tienes la intención de usarla para operaciones. Una vez que una Cobre Key es eliminada, no puede ser usada nuevamente.

Llaves Cobre con Bre-B

Combinaciones Permitidas#

Estructura y personalización de llaves#

Tipos de Cobre Key#

Ciclo de vida de Cobre Key y acciones previas#

Idempotencia de Cobre Key#

Acciones realizadas en una Cobre Key#

Cómo Comenzar#

Antes de usar esta API#

Qué esperar después de usar esta API#