Skip to main content

Bre-B

Cash and Codes Bundle

Bre-B is a real-time payment solution in Colombia that enables instant transfers 24/7 through QR codes. This guide provides step-by-step instructions on how to integrate Bre-B payments with the EBANX Direct API.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See the Direct API Guide for more info.

How it works​

  1. Set up a payment request through the EBANX API and choose Bre-B as the payment method.
  2. Generate a QR code for the customer. The EBANX API will return a Base64-encoded image.
  3. Display the QR code image, amount, and expiration date clearly for the customer.
  4. Monitor payment status until confirmed.

Instructions​

Follow the steps below.

  1. Select your environment
    ​

    Select the appropriate environment for your integration. Use the sandbox environment for testing or the production environment for live transactions.

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct

  2. Define your parameters
    ​

    Bre-B is an instant payment system that allows customers to make payments directly from their bank account using QR codes. To create a Bre-B QR Code, call the /ws/direct endpoint with the required parameters.


    Defining API parameters

    You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.

    Essential parameters

    • payment.payment_type_code - Specifies the payment method to be used for the transaction.
    • payment.currency_code - Three-letter code of the payment currency
    • payment.amount_total - Total amount to be charged.

    Additional parameters

    • EBANX Integration Key - Used to authenticate and authorize API requests.
    • Customer Information
      • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
      • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
    • Additional Context - Extra data for specific methods or countries.

    To learn more about API parameters, please refer to the
    API Reference Guide chevron_right

    At the API Reference Guide, select Colombia and Bre-B from the dropdown menus.

  3. Sample request
    ​

    Here’s an example using cURL to initiate a Bre-B payment:

    Sample request

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "payment": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "document": "1020304050",
          "country": "co",
          "payment_type_code": "breb",
          "merchant_payment_code": "b53123fde19djbs7",
          "currency_code": "COP",
          "amount_total": 50000
        }
      }'

  4. Sample response
    ​

    A successful request returns a response containing the Base64-encoded QR Code in the payment.ewallet.qr_code_value parameter.

    Sample response

    {
        "payment": {
            "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
            "country": "co",
            "merchant_payment_code": "your_unique_merchant_code",
            "order_number": null,
            "status": "PE",
            "status_date": null,
            "open_date": "2026-01-16 21:21:15",
            "confirm_date": null,
            "transfer_date": null,
            "amount_br": "1001.00",
            "amount_ext": "1001.00",
            "amount_iof": "0.00",
            "currency_rate": "1.0000",
            "currency_ext": "COP",
            "due_date": "2026-01-19",
            "instalments": "1",
            "payment_type_code": "breb",
            "redirect_url": "https://api.ebanx.com/ws/redirect?hash=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
            "pre_approved": false,
            "capture_available": null,
            "ewallet": {
                "qr_code_value": "iVBORw0KGgoAAAANSUhEUgAAAYEAAAGBCAIAAAAPO5pzAAA... (Base64 string)"
            },
            "currency_ext_base": "COP"
        },
        "status": "SUCCESS",
        "redirect_url": "https://api.ebanx.com/ws/redirect?hash=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4"
    }
    At this stage, the payment will appear as pending (PE) in your
    EBANX Dashboardchevron_right

  5. Show voucher on your site
    ​

    Use a modal, iframe, or webview to display the voucher within your site (or app). Unlike other methods, Bre-B does not use a redirect URL. You must render the QR code from the Base64 data provided in the API response.

    Instructions

    • Retrieve the Base64 string from the payment.ewallet.qr_code_value parameter in the response.

    • Decode the Base64 data and render it as an image on your checkout page. Most programming languages and frameworks have libraries to handle this conversion (e.g., creating an image from a data URI: data:image/png;base64,...).

    Guidelines for Desktop & Mobile

    • Clearly indicate that this is a Bre-B payment.
    • Display the payment amount prominently.

    • Display the expiration time. Bre-B is instant, but the customer may take time to complete the payment.

    • Render the QR code with high contrast using the Base64 data provided by the API.

    • Provide clear instructions for the user to scan the QR code with their banking or wallet app to complete the payment.

    • Note: There is no "copy code" functionality. The user must scan the QR image with their mobile device.


    Example on desktop:

  6. Monitor payment for status changes
    ​

    Notifications

    • EBANX will send a notification whenever a payment status changes.

    • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

    Status

    • After receiving a notification, retrieve the payment status.
    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).
    • Bre-B payments expire based on the expiration time defined in the payment request (a default is used if not specified).
    • If the customer does not complete the payment within this timeframe, the status will automatically update to canceled (CA).

  7. Congratulations!
    ​

    You have successfully integrated Bre-B.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Warning Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: