Skip to main content

​
Overview

Bre-B PayOut enables businesses to disburse funds instantly to individuals identified by a Bre-B key (phone, email, document, NIT, or alphanumeric identifier) or via interoperable QR codes. Funds settle through the Bank of the Republic’s MOL infrastructure in central bank money within seconds. Use this guide after reviewing the Bre-B overview to build, test, and launch payout flows.

​
Flow Summary

  1. Resolve the Bre-B key to confirm destination account details through the centralized directory (DICE).
  2. Create the payout sending payment_method: "BREB" and the resolved account data.
  3. Handle webhook notifications (PENDING, APPROVED, REJECTED) to reconcile results in your system.

​
Prerequisites

  • Bre-B enabled on your TumiPay account with sufficient liquidity.
  • Sandbox or production credentials (Basic Auth + Token-Top).
  • A valid Bre-B key supplied by the beneficiary.
  • Webhook endpoint ready to receive payout status updates (../webhooks).

​
Resolve a Bre-B Key

Use the key resolution endpoint before triggering a payout. It validates that the key is active and returns the account and holder data. Method: GET Path: /api/v1/breb/{key_value}/resolve

​
Example Request

curl --request GET 'https://api-empresas.staging.tumipay.co/production/api/v1/breb/@tumipaybreb/resolve' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key'

​
Example Response

{
  "success": true,
  "data": {
    "key_status": "ACTIVE",
    "key_type": "PHONE",
    "customer_data": {
      "full_name": "Jhon Doe",
      "legal_doc_type": "CC",
      "legal_doc": "1088432333",
      "bank": "NEQUI",
      "account_type": "AHORRO",
      "account_number": "@tumipaybreb"
    }
  }
}

​
Create a Bre-B Payout

Submit the payout with payment_method: "BREB" and the account information returned by the resolution step. Method: POST Path: /api/v1/payout

​
Example Request

{
  "payment_method": "BREB",
  "reference": "11",
  "amount": 1000,
  "currency": "COP",
  "country": "CO",
  "ipn_url": "http://example.com/tu-webhook",
  "customer_data": {
    "legal_doc": "1002184990",
    "legal_doc_type": "CC",
    "phone_code": "57",
    "phone_number": "3003540831",
    "email": "[email protected]",
    "full_name": "John Doe",
    "bank": "NEQUI",
    "account_type": "AHORRO",
    "account_number": "@tumipaybreb"
  }
}

​
Key Points

  • Payment method: Must be "BREB".
  • Account number: Use the Bre-B key obtained from the resolution response.
  • Customer data: Provide complete KYC details for compliance review.
  • Webhook IPN: Required to receive asynchronous status updates.

​
Test Data

Key TypeValue
Phone300000001
Email[email protected]
Document1003191919
Alphanumeric@tumipaybreb
Use the sandbox environment to validate your integration end-to-end before scheduling production activation.

​
Status Notifications

StatusDescription
PENDINGTransaction created and awaiting confirmation from Bre-B.
APPROVEDFunds successfully transferred to the beneficiary.
REJECTEDTransaction rejected due to validation or settlement failure.
Reconcile notifications with your internal ledger and follow your retry or fallback strategy when you receive REJECTED statuses.