Crear Códigos QR

Esta especificación está sujeta a cambios. El estándar colombiano EASPBV está evolucionando para soportar las capacidades de la red Bre-B. Passport colabora activamente con entidades del sector para definir un modelo robusto y flexible de integración de códigos QR para pagos en tiempo real.

Visión General

Este endpoint permite crear un Código QR compatible con Bre-B utilizando la API de la Plataforma PaaS de Passport. El código QR codifica información de pago y metadatos contextuales de acuerdo con el estándar colombiano EASPBV, devolviendo un identificador único del QR y los detalles asociados.

Detalles del Endpoint

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

Cuerpo de la Solicitud

Parámetro	Tipo	Cardinalidad	Descripción
key_id	String	Obligatorio	ID único de la llave Bre-B asociada a la cuenta del comercio.
customer_id	String	Obligatorio	ID único del cliente (comercio) que inicia la transacción.
`type`	ENUM	Obligatorio	Tipo de código QR: `STATIC` o `DYNAMIC`.
channel	ENUM	Obligatorio	Canal en el cual se presentará el QR: `MAN`, `POS`, `APP`, `ECOMM`, `MPS`, `ATM`.
additional_info	Objeto	Obligatorio	Objeto con metadatos adicionales de la transacción.
additional_info.transaction_purpose	ENUM	Obligatorio	Finalidad de la transacción: `SHOPPING`, `CANCELLATION`, `TRANSFER`, `RETREAT`, `COLLECTION`, `REFILL`, `DEPOSIT`.
additional_info.invoice_number	String	Opcional	Número de factura (máx. 25 caracteres).
additional_info.mobile_phone_number	String	Opcional	Número móvil vinculado a la transacción.
additional_info.store_label	String	Opcional	Identificador de tienda.
additional_info.loyalty_label	String	Opcional	Referencia a programa de lealtad del comprador.
additional_info.reference_label	String	Opcional	Referencia única de la transacción.
additional_info.customer_label	String	Opcional	Identificador único del comprador.
additional_info.terminal_label	String	Opcional	ID del terminal de punto de venta (POS).
additional_info.customer_info	ENUM	Opcional	Información requerida del comprador: `ADDRESS`, `EMAIL`, `PHONE`.
additional_info.channel_presentation	String	Opcional	Código de 3 dígitos que indica cómo fue presentado el QR.
vat	Objeto	Condicional	Información del IVA si se incluye monto. Obligatorio para QR dinámicos.
vat.vat_type	ENUM	Condicional	Tipo de cálculo del IVA: `FIXED`, `PERCENTAGE`, `WALLET`.
vat.vat_value	String	Condicional	Valor fijo en COP o porcentaje (5 decimales).
vat.vat_base	String	Condicional	Base del valor sobre el cual se calcula el IVA.
inc	Objeto	Condicional	Información del INC. Aplicable si se incluye monto.
inc.inc_type	ENUM	Condicional	Tipo de cálculo del INC: `FIXED`, `PERCENTAGE`, `WALLET`.
inc.inc_value	String	Condicional	Valor fijo en COP o porcentaje (5 decimales).
amount	Objeto	Opcional	Valor de la transacción codificada en el QR.
amount.value	String	Opcional	Valor del pago (e.g., "100000.00").
amount.currency	ENUM	Opcional	Debe ser `COP`.
tip	Objeto	Opcional	Información sobre propina (opcional).
tip.tip_type	ENUM	Opcional	Método de cálculo: `REQUEST`, `FIXED`, `PERCENTAGE`.
tip.tip_value	String	Opcional	Requerido si el tipo es `FIXED`.
tip.tip_percentage	String	Opcional	Requerido si el tipo es `PERCENTAGE`.

Ejemplo de Solicitud

JSON
    
 
curl --location 'https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/qrcodes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TU_TOKEN_DE_ACCESO' \
--data '{
    "key_id": "be63d052-488b-4394-826e-941b95458368",
    "customer_id": "be63d052-488b-4394-826e-941b95458368",
    "type": "DYNAMIC",
    "channel": "POS",
    "vat": {
        "vat_type": "FIXED",
        "vat_value": "100.00",
        "vat_base": "100.00"
    },
    "inc": {
        "inc_type": "FIXED",
        "inc_value": "10.00",
    },
    "amount": {
        "value": "100000.00",
        "currency": "COP"
    },
    "additional_info": {
        "transaction_purpose": "SHOPPING"
    }
'
Copy

Cuerpo de la Respuesta

Código HTTP: 201 Created.
Retorna un código QR creado y asociado a los metadatos de la solicitud.

Ejemplo de Respuesta

JSON
    
 
{
    "id": "be63d052-488b-4394-826e-941b95458368",
    "key_id": "be63d052-488b-4394-826e-941b95458368",
    "customer_id": "be63d052-488b-4394-826e-941b95458368",
    "qr_code_data": "123098768sadf9203yiug9020897yu2i3ew89uf7y8guih9089782890iou892987y",
    "key": {
        "key_type": "M",
        "key_value": "3503501234",
    },
    "acquirer_network_identifier": "VISI",
    "merchant": {
        "merchant_category_code": "0123",
        "country": "CO",
        "merchant_name": "Passport Software SaS",
        "merchant_city": "Bogota",
        "merchant_zip_code": "49312",
    },
    "status": "ACTIVE",
    "created_at": "2025-03-04T10:10:10.00000Z",
    "type": "DYNAMIC",
    "channel": "POS",
    "vat": {
        "vat_type": "FIXED",
        "vat_value": "100.00",
        "vat_base": "100.00"
    },
    "inc": {
        "inc_type": "FIXED",
        "inc_value": "10.00",
    },
    "amount": {
        "value": "100000.00",
        "currency": "COP"
    },
    "additional_info": {
        "transaction_purpose": "SHOPPING"
    }
}
Copy

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 validar la entidad.
500 Server Error	Error del servidor	Se produjo un error inesperado al procesar la validación.

Buenas Prácticas

Verifica que el key_id y customer_id sean válidos y estén asociados correctamente.
Usa el campo channel_presentation para detallar cómo y dónde se muestra el QR.
Si se incluye un monto, asegúrate de incluir los objetos vat e inc con la estructura y tipos adecuados.

Última actualización el