Create QR Codes

Note

This specification is subject to change, it is Work in Progress. The Colombian EASPBV standard is evolving to support the capabilities of the Bre-B network.

Passport is actively collaborating with industry stakeholders to shape a flexible and robust QR Code integration model for real-time payments.

Overview

This endpoint allows you to create a Bre-B compliant QR Code using the Passport PaaS API. It encodes payment and contextual metadata as defined by the Colombian EASPBV standard, returning a unique QR Code ID and associated resource details.

QR Codes Types

The supported types are: Dynamic and Static QR codes.

Endpoint Details

Definition	Description
Endpoint	https://api.paas-sandbox.co.passportfintech.com/v1/qrcodes
Method	POST
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Request Body

Parameter	Type	Required	Description
key_id	String	Yes	The unique identifier of the previously created Bre-B key associated with the merchant account.
customer_id	String	Yes	The unique identifier of the customer (merchant) initiating the transaction.
type	ENUM	Yes	Type of QR Code: `STATIC` or `DYNAMIC`.
channel	ENUM	Yes	Where the QR Code will be used: `IM` - Manual `POS` - Point of Sale `APP` - Mobile App `ECOMM` - E-commerce `MPOS` - Mobile POS `CB` - Corresponsal Bancario `OFC` - Oficina `ATM` - ATM
additional_info	Object	Yes	Additional meta data for the transaction.
additional_info.transaction_purpose	ENUM	Yes	Purpose of the transaction: 00: Compras 02: Anulaciones 03: Transferencias 04: Retiro 05: Recaudo 06: Recargas 07: Depósito Use 2 digits instead of the string value.
qr_code_reference	String	Optional	A unique reference that can be set so it is passed through the network with the associated Payment. Maximum of 17 alphanumeric characters. The letter P is not permitted. In the Bre-B logic, the PaaS platform will add “CO.COM.VISI.TRXID” to the message and the letter P is part of the internal identification for this reference field. For example, if the reference below is sent to the PaaS platform: `qr_code_reference:"11213344556677889"` When the payment and its notifications are received, the following reference will be added and shown: `qr_code_reference:"CO.COM.VISI.TRXIDP11213344556677889"`
additional_info.invoice_number	String	Optional	Invoice number (max 25 characters).
additional_info.mobile_phone number	String	Optional	Mobile phone number linked to the transaction (max 25 characters).
additional_info.store_label	String	Optional	Store identifier (max 25 characters).
additional_info.loyalty_label	String	Optional	Loyalty program reference for the Buyer (max 25 characters).
additional_info.reference_label	String	Optional	Unique transaction reference (max 25 characters).
additional_info.customer_label	String	Optional	Store the Buyer unique identifier (max 25 characters).
additional_info.terminal_label	String	Yes	POS terminal ID (max 25 characters).
additional_info.customer_info	ENUM	Optional	An indicator whether the device scanning the QR Code needs to capture information from the Customer. Use one of the DIGIT codes below: `A` - ADDRESS `E` - EMAIL `P` - PHONE
additional_info.channel_presentation	String	Optional	A 3 digit field used to compliment the `channel` field to indicate how the QR Code is presented to the Buyer. First Character: The medium used: 0 - Printed - Adhesive 1 - Printed - Invoice 2 - Printed - Magazine / Poster 3 - Printed - Other 4 - Screen - Merchant POS 5 - Screen - Website 6 - Screen - App 7 - Screen - Other Second Character: The location presented: 0 - the registered address of the business 1 - different from the registered address of the business 2 - remote commerce 3 - other Third Character: How it was presented: 0 - if a cashier was present 1 - if a cashier was not present 2 - self attended box / checkout 3 - other
vat	Object	Required	An object to track the VAT applied to the transaction being represented by the QR Code.
vat.vat_type	ENUM	Required	Indicates how the VAT will be calculated for the transaction: `WALLET` `FIXED` `PERCENTAGE`
vat.vat_value	String	Required	VAT value: If `FIXED`: Amount in COP with two decimals (e.g., `100.10`) If `PERCENTAGE`: Rate with five decimals (e.g., `0.00500`)
vat.vat_base value	String	Required	Indicates the VAT Base Value
inc	Object	Conditional	An object to track the INC applied to the transaction being represented by the QR Code. Required for Dynamic QR Codes if an Amount is provided.
inc.inc_type	ENUM	Conditional	Indicates how the INC will be calculated for the transaction: `WALLET` `FIXED` `PERCENTAGE`
inc.inc_value	String	Conditional	INC value: If `FIXED`: Amount in COP with two decimals (e.g., `100.10`) If `PERCENTAGE`: Rate with five decimals (e.g., `0.00500`)
amount	Object	Optional	Represents the value and currency of the transaction to be encoded in in the QR Code.
amount.value	String	Optional	Amount of the transaction in COP (e.g., `10000.10`).
amount.currency	ENUM	Optional	Currency for the transaction. Must be `COP`.
tip	Object	Optional	An object to track if a tip is to be added to the value of the transaction such as for paying a restaurant bill.
tip.tip_type	ENUM	Optional	Tip calculation method: `REQUEST` `FIXED` `PERCENTAGE`
tip.tip_value	String	Optional	Required if `tip_type` is `FIXED`.
tip.tip_percentage	String	Optional	Required if `tip_type` is `PERCENTAGE`

Example Request

curl --location 'https://api.paas-sandbox.co.passportfintech.com/v1/qrcodes' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --data '{ "key_id": "e7f75ffc-22b8-4cfe-884b-8ebcb008b680", "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c", "type": "DYNAMIC", "channel": "MPOS", "vat": { "vat_type": "FIXED", "vat_value": "100.00", "vat_base_value": "100.00" }, "inc": { "inc_type": "FIXED", "inc_value": "10.00" }, "amount": { "value": "100000.00", "currency": "COP" }, "additional_info":{ "transaction_purpose": "00", "invoice_number": "123", "terminal_label": "01", "store_label": "sasc0193", "mobile_phone_number": "3503503456", "loyalty_label": "1234", "reference_label": "pago impuesto", "customer_label": "0001", "customer_info": "EMAIL", "channel_presentation": "400" }, "qr_code_reference": "uniquereferencefortracking" }'

Response Body

HTTP Status Code: 200 OK.
Returns the newly created QR Code and its associated metadata.

Example of Response

{ "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c", "status": "ACTIVE", "key": { "key_type": "ID", "key_value": "36606864" }, "vat": { "vat_value": "100.00", "vat_base_value": "100.00", "vat_type": "FIXED" }, "type": "DYNAMIC", "qr_code_data": "00020101021226310015CO.COM.VISI.LLA01083660686449270015CO.COM.VISI.RED0104VISI52045782530317054130000100000.005802CO5914Merchant CWSPZ6006Bogota610598273621020810COLLECTION0103123021035035034560308sasc0193040412340513pago impuesto060400010702010905EMAIL110340080290017CO.COM.VISI.CANAL0104MPOS81260016CO.COM.VISI.CIVA01020282290015CO.COM.VISI.IVA0106100.0083300016CO.COM.VISI.BASE0106100.0084260016CO.COM.VISI.CINC01020285280015CO.COM.VISI.INC010510.0090610017CO.COM.VISI.TRXID01363D8CB42B-9222-46DD-9AB3-67A5DAF3CF4B63042BFB", "acquirer_network_identifier": "VISI", "created_at": "2025-10-10T11:45:24.099819Z", "key_id": "e7f75ffc-22b8-4cfe-884b-8ebcb008b680", "merchant": { "merchant_category_code": "0412", "merchant_country": "CO", "merchant_name": "Merchant CWSPZ", "merchant_city": "Medellin", "merchant_post_code": "101010" }, "additional_info": { "transaction_purpose": "00", "invoice_number": "123", "terminal_label": "01", "store_label": "sasc0193", "channel_presentation": "400", "customer_info": "EMAIL", "mobile_phone_number": "3503503456", "customer_label": "0001", "loyalty_label": "1234", "reference_label": "pago impuesto" }, "inc": { "inc_value": "10.00", "inc_type": "FIXED" }, "amount": { "value": "100000", "currency": "COP" }, "channel": "MPOS", "id": "7cc278ab-c8fd-40e9-ad4e-a53db7dcbcf3" }

{ "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c", "status": "ACTIVE", "key": { "key_type": "ID", "key_value": "36606864" }, "type": "STATIC", "qr_code_data": "00020101021126310015CO.COM.VISI.LLA01083660686449270015CO.COM.VISI.RED0104VISI5204578253031705802CO5914Merchant CWSPZ6006Bogota61059827362120808PURCHASE80280017CO.COM.VISI.CANAL0103POS90310017CO.COM.VISI.TRXID010600000063045CB4", "acquirer_network_identifier": "VISI", "created_at": "2025-10-10T11:47:52.365840Z", "additional_info": { "transaction_purpose": "PURCHASE" }, "key_id": "e7f75ffc-22b8-4cfe-884b-8ebcb008b680", "merchant": { "merchant_category_code": "0412", "merchant_country": "CO", "merchant_name": "Merchant CWSPZ", "merchant_city": "Medellin", "merchant_post_code": "101010" }, "channel": "POS", "id": "ffd0d013-1fe9-4b36-bf3f-9d9850b5b638" }

Important

The QR Codes response includes the image in Base64 format. You can use any front-end library to convert it to a readable image for your audience.
The QR codes are visible in the dashboard for validation purposes.
The id you get back is the qr_code_id, which you will use in other endpoints.

Common Errors and Handling

HTTP Status Code	Meaning	Description
400 Bad Request	Invalid Data	Required fields are missing or contain incorrect values.
401 Unauthorized	Expired Token	The access token is invalid or has expired.
403 Forbidden	Access Denied	The request is not authorized to validate the entity.
500 Internal Server Error	Server Error	An unexpected error occurred while validating the entity.

Best Practices

Verify that the key_id and customer_id are valid and correctly associated.
Use thechannel_presentation field to specify how and where the QR is displayed.
Use the qr_code_reference to track the QR Code against incoming Payments
If an amount is included, make sure to include the vat and inc objects with the appropriate structure and types.

Last updated on