Create QR Codes

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://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/qrcodes
Method	POST
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Request Body

Parameter	Type	Cardinality	Description
key_id	String	Mandatory	The unique identifier of the previously created Bre-B key associated with the merchant account.
customer_id	String	Mandatory	The unique identifier of the customer (merchant) initiating the transaction.
type	ENUM	Mandatory	Type of QR Code: `STATIC` or `DYNAMIC`.
channel	ENUM	Mandatory	Where the QR Code will be used: `MAN` - Manual `POS` - Point of Sale `APP` - Mobile App `ECOMM` - E-commerce `MPS` - Mobile POS `ATM` - ATM
additional_info	Object	Mandatory	Additional meta data for the transaction.
additional_info.transaction_purpose	ENUM	Mandatory	Purpose of the transaction: `SHOPPING` `CANCELLATION` `TRANSFER` `RETREAT` `COLLECTION` `REFILL` `DEPOSIT`
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	Optional	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. Will be one of: `ADDRESS` `EMAIL` `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	Conditional	An object to track the VAT applied to the transaction being represented by the QR Code. Required for Dynamic QR Codes if an Amount is provided.
vat.vat_type	ENUM	Conditional	Indicates how the VAT will be calculated for the transaction: `WALLET` `FIXED` `PERCENTAGE`
vat.vat_value	String	Conditional	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	Conditional	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

Dynamic QR Codes
Static QR Codes
    
 
curl --location 'https://bre-b-sandbox.api.visionamos.passportfintech.com/v1/paas/entities/customers/qrcodes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--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": "PURCHASING"
    }
'
Copy

Response Body

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

Example of Response

Dynamic QR Codes
Static QR Codes
    
    
 
{
    "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",
    "inc": {
        "inc_value": "10.00",
        "inc_type": "FIXED"
    },
    "account_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": "DYNAMIC",
    "key": {
        "key_type": "E",
        "key_value": "jimmyjohns1111402545255@test.com"
    },
    "channel": "MPOS",
    "amount": {
        "currency": "COP",
        "value": "100000"
    },
    "additional_info": {
        "transaction_purpose": "PURCHASE"
    },
    "vat": {
        "vat_type": "FIXED",
        "vat_value": "100.00",
        "vat_base_value": "100.00"
    }
}
Copy

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.

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.
If an amount is included, make sure to include thevat and inc objects with the appropriate structure and types.

Last updated on