QR Code Guide

Overview

QR Codes provide a streamlined mechanism for initiating Payments between parties. A person may generate a QR Code to share payment details, while a Merchant can display one to help a buyer complete a purchase at a Point of Sale (POS).

The Passport PaaS Platform enables the creation of compliant QR Codes that follow the EMV Co Colombian industry specification - current at time of writing with the latest specification from July 2025. These QR Codes can be used in both digital and offline channels, reducing manual errors and enhancing the buyer experience.

Bre-B QR Codes simplify the sale process by embedding essential information (e.g., Bre-B Key, transaction amount, purpose) into a scannable format, reducing friction and improving security - saving the Customer time.

QR Code requirements are defined by institutions including: ACH Colombia, Banco de la República, Credibanco, EMV Co, Mastercard, Redeban, Servibanca, Visa, and Visionamos. Passport provides support to these groups to help further the clarity of the specification for Bre-B payments.

Passport, in partnership with Visionamos, operates a national Bre-B access point to process Bre-B payments and issue QR Codes for use across the ecosystem.

Payment Lifecycle

Bre-B QR Codes can be used across physical and digital channels: including posters, POS terminals, ATMs, websites, and mobile apps.

Example: Coffee Shop Purchase

Sample Payment Lifecycle

The image above depicts a simple transaction for a Buyer to purchase a coffee at a Point of Sale where the simple steps are:

Merchant creates a Sale in their POS system.
The POS system generate a Dynamic QR Code that captures the information of the Sale using the Passport PaaS API and displays it to the Buyer.
The Buyer scans the QR code using their mobile banking app's within the Bre-B Zone.
The mobile banking app pre-fills the recipient (Bre-B Key), amount, and transaction purposes.
The Buyer reviews and confirms the transfer to the nominated Bre-B Key.
The payment is sent via the Bre-B network from the Buyer's Bank to Passport's Sponsor Bank.
Passport PaaS receives confirmation from the Bre-B node and identifies the corresponding Merchant.
A Webhook notification is sent to the Merchant's POS system to confirm payment.

Prerequisites

To create QR Codes on the PaaS Platform, there are a number of prerequisities that need to be satisfied. The information for generating the QR Code is pulled from a variety of sources:

Customer: The created Customer contains information such as the Merchant Name and Address which provides data such as the name, city, zip code, and country which are mandatory data fields for the QR Code.
Bre-B Key: A created Key for an Account must be stored in a Static or Dynamic QR Code to route Payments to the Merchant over the Bre-B network.
Configuration: Setting other information such as the Merchant Category Code on the Configuration for the Merchant is required as this is another mandatory data field for a QR Code.
API Request: The majority of the information is provided via the Create QR Codes API request and can include mandatory and optional information depending on the intended use case.

Required Tasks

To satisfy the prerequisites, you must complete the following tasks:

Step	Description
1	Link a Merchant a with legal name, address, city, country, and zip code.
2	Link Account linked to the active customer.
3	Create Key at least one Bre-B Key associated with that account.

Once you finish the steps, you can gather the necessary information for the QR Code from the relevant sources to meet the profile requirements. Use the Create QR Codes API request to get the remaining fields for creating the Static or Dynamic QR Code.

QR Code Creation

To create a QR Code, the Developer needs to consider the main fields and available information for each use case where a QR Code can be presented.

The table below captures the considerations that are needed for the QR Code to have the most impact. Note, the below is not the mandatory fields for each API call, but rather the main fields that can be used to set the contents of the QR Code for the various use cases.

Field	Dynamic	Static
type	A QR Code generated for one time use that is linked to a specific payment amount and activity within the developer ecosystem	A QR Code that can be reused as it doesn't contain any transaction specific information.
channel	Details where and how the QR Code is presented - for example at a Point of Sale, or a Mobile Point of Sale (attached to a phone). The PoS has auto generated the information for the transaction ready for awaiting Payment.	Most likely within a poster or printed mechanism. The Static QR Code is used for sharing information that doesn't change per transaction - such as the Bre-B Key.
qr_code__reference	A unique reference to tie the QR Code to the action the Developer wishes to track	Not required
transaction_purpose	Describes what the QR Code is representing - such as a Purchase	Similar to the Dynamic QR Code, it can also be set for the Static QR Code

These are the main fields that can be changed to suit the Dynamic or Static QR Code implementation - in addition to the Bre-B Key and Amount of course.

The intended use case for the Dynamic QR Code is one that is uniquely tied to a single expected Payment - such as a buyer at the Point of Sale. The QR Code is generated on demand for that particular purchase and is "dynamically" set for that sale.

The Static QR Code can be printed out en masse and left for anyone to find - there is no sale specific information that needs to be generated for each person that scans the QR Code. For example, a charity taking donations could print Static QR Codes in a national newspaper, while the person scanning the code sets the amount of the donation that they wish to send within the mobile banking app.

The examples below show how this can be implemented.

Static - Print

Dynamic - PoS

Dynamic - ATM

Dynamic - Online

Static QR Code

A Static QR Code contains fixed payment information and does not change once created. It’s typically printed and displayed on a physical medium, such as a sticker, poster, or checkout stand in a merchant's location.

This QR Code type is ideal for environments where the merchant has a direct, in-person interaction with the buyer, such as small vendors or informal retail setups.

The buyer scans the QR Code using their mobile banking app.
The buyer manually enters the amount and submits the payment.
The merchant confirms the payment manually, for example by checking their banking app.

No integration with a Point of Sale system is required, making this a lightweight solution for Bre-B acceptance.

Passport’s PaaS Platform supports multiple implementation paths: either through dedicated merchant accounts or platform-managed flows where you remain in control of the end-to-end payment lifecycle.

Static QR Code Request Example

The example below could be used for a small street vendor wishing to take Bre-B Payments via a Static QR Code that has been printed out on a sticker that is attached to the side of their cart to help Buyers scan to make a Payment.

Parameter	Description
key_id	The unique identifier for the Bre-B key that was created in a previous step for the pre-requisite.
customer_id	The unique identifier of the merchant (Customer).
type	Set to `STATIC` to indicate this is a static QR Code. (`DYNAMIC` is an option but in this use case `STATIC` is correct).
channel	Set to `MPOS` to indicate this is used via a Mobile Point of Sale.
additional_info.transaction_purpose	Submitted within the `additional_info` object, but specifies what the transaction purpose is, in this example it will be set to SHOPPING
additional_info.transaction.channel_presentation	Submitted within the `additional_info` object as an optional three digit code that represents the medium used to provide more detail to the channel. In this example, it was a Printed Sticker (0), that was not used at the registered location of the business (1) and the cashier was present (0) therefore `010` is submitted.

Static QR Code Request Body

Static QR Code
    
xxxxxxxxxx
 
curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/qrcodes' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer 17d5cc1adb6f6c90d5aa73f74b38f9fa3336d04aee6cf8121a3cf19f190e6213' \--data '{    "key_id": "1f2046b7-428d-4682-b6f2-3fe438ae5a3e",    "customer_id": "291b10c1-b86a-4741-a49f-ff55c46190d8",    "type": "STATIC",    "channel": "POS",    "additional_info":{        "transaction_purpose": "SHOPPING"    }}'
Copy

There are additional optional fields that can be added to the additional_info object to augment the information in the QR Code, explore the endpoint Create QR Codes to learn more about them and what they can be used for.

Static QR Code Response Example

Once the request is submitted, the PaaS Platform combines information from the various sources in order to create the compliant QR Code according to the Colombian EASPBV Industry Specification for QR Codes. The response is provided back to the Developer in a similar format as other Resources.

Parameter	Description
id	The unique id for the QR Code that was created from the POST request that can be used for future retrieval and deletion requests.
qr_code data	The formatted string for the QR Code that contains the data which can be presented via a digital channel or converted and printed out.
key	An object to represent the `key_value` and `key_type` that was used for creating the QR Code which is also referenced by the key_id
acquirer_network identifier	QR Codes will always be issued by VISI who are an authorised issuer by Banco de la República for Bre-B keys.
merchant	An object representing the information relating to the Merchant itself - the name, city, zip code, country and category code
status	Indicates successful creation (`ACTIVE`).
created_at	A timestamp capturing when the QR Code was created successfully.
key_id	The unique id for the Bre-B key that was created in a previous step for the pre-requisite.
customer_id	The unique id for the Customer was that was created in a previous step for the pre-requisite.
type	Whether the developer would like to create a STATIC or DYNAMIC QR code - in this example, the Developer would chose STATIC.
channel	States how the QR Code has been presented by the Merchant to the Buyer - in this example, the Developer would chose MPOS for a Mobile Point Of Sale.
transaction_purpose	Returned within the `additional_info` object, but specifies what the transaction purpose is, in this example it will be set to SHOPPING
channel_presentation	Returned within the `additional_info` object as an optional three digit code that represents the medium used to provide more detail to the channel. In this example, it was a Printed Sticker (0), that was not used at the registered location of the business (1) and the cashier was present (0) therefore `010` is submitted.

Static QR Code Response Body

Response - 201 Created
    
xxxxxxxxxx
 
{    "created_at": "2025-05-12T20:30:17.547227Z",    "qr_code_data": "00020101021226550015CO.COM.VISI.LLA0332jimmyjohns1111402545255@test.com49270015CO.COM.VISI.RED0104VISI52045782530317054130000100000.005802CO5919Test Business O9F126006Bogota61059827362120808PURCHASE80290017CO.COM.VISI.CANAL0104MPOS81260016CO.COM.VISI.CIVA01020282290015CO.COM.VISI.IVA0106100.0083300016CO.COM.VISI.BASE0106100.0084260016CO.COM.VISI.CINC01020285280015CO.COM.VISI.INC010510.0090610017CO.COM.VISI.TRXID01364A07229A-7B14-4B63-85D5-79572E130E0763040351",    "qr_code_image": "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",    "acquirer_network_identifier": "VISI",    "key_id": "7756cfcb-0d28-4e89-bbc0-d4ebdc5b6ca1",    "id": "7aa184b7-c549-467b-917f-460b4224b459",    "entity_customer_id": "0d93dea5-00c4-4a9e-b3fa-cbaf5280818b",    "merchant": {        "merchant_category_code": "1234",        "country": "CO",        "merchant_name": "Test Business O9F12",        "merchant_city": "Bogota",        "merchant_zip_code": "98273"    },    "status": "ACTIVE",    "type": "STATIC",    "key": {        "key_type": "EMAIL",        "key_value": "jimmyjohns1111402545255@test.com"    },    "channel": "MPOS",    "additional_info": {        "transaction_purpose": "SHOPPING"    }}
Copy

The QR Code has been created successfully and can then use the returned id as a future reference to retrieve and delete as required. The qr_code_data field contains the encoded string that can be printed out as many times as the Merchant wishes, or use the qr_code_image which is in base64 for ease of use.

The Benefits of the Static QR Code are:

Data is fixed - the same key, channel, transaction_purpose and channel_presentation can be printed out and used multiple times over
The sticker can be included in a variety of places on the cart to make it easy for the Buyer to scan and interact with
There is no complicated integration with a Point of Sale system required to generate and receive Payments

PaaS Platform does not verify that the calculated VAT or INC numbers are correct - we do not contain a list of all appropriate added taxes or charges that should be added to every type of transaction in Colombia.

Nor do our Sponsor Bank partners take any liability for ensuring these details are correct - it is up to the Developer to ensure that the appropriate fees and add-ons are calculated as part of the accounting for processing sales.

Last updated on