Bre-B PayIn

Accept instant inbound payments in Colombia through the Bre-B network.

Overview

Bre-B PayIn lets Colombian customers initiate instant transfers to your business using their registered Bre-B key or interoperable QR. Transactions settle in real time and TumiPay sends webhook updates so you can confirm funds immediately.

Review the Bre-B overview before configuring the PayIn-specific steps outlined here.

Flow Summary

1. Your application creates a PayIn request with payment_method: "BREB".
2. TumiPay responds with a hosted payment_url and the Bre-B transaction metadata (data.account_number) that the customer must use.
3. You redirect or show the payment_url, where the user retrieves the Bre-B key and completes the transfer from their bank or wallet app.
4. TumiPay sends webhook notifications once the network settles the instruction and reports the definitive status and amount.

Request Essentials

Parameter	Value / Requirement	Notes
Endpoint	POST /api/v1/payin	Same endpoint as other PayIn methods.
Currency	COP	Amount sent in minor units.
Country	CO	Indicates Colombia.
Payment Method	"BREB"	Restricts the experience to Bre-B flows.
redirect_url	Required	Customers return here after completing the flow.
ipn_url	Required	Receives asynchronous updates.
expiration_time	Optional (recommended)	Time in minutes that the Bre-B key remains valid on the hosted page. Default is 15.
customer_data	Must include legal_doc, legal_doc_type, phone_code, phone_number, email, full_name	Enables compliance validation and contact.

For Bre-B payments, the customer must complete the payment in their institution’s channel and can modify the amount before authorizing it, so make sure your application handles this case appropriately.

Example Request

curl --request POST 'https://api-empresas.staging.tumipay.co/production/api/v1/payin' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "BREB-PAYIN-001",
  "amount": 5000,
  "currency": "COP",
  "country": "CO",
  "payment_method": "BREB",
  "description": "Bre-B PayIn test",
  "customer_data": {
    "legal_doc": "1234567890",
    "legal_doc_type": "CC",
    "phone_code": "57",
    "phone_number": "3121234567",
    "email": "[e-mail]",
    "full_name": "John Doe"
  },
  "expiration_time": 30,
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'

Response Snapshot

A successful Bre-B PayIn request responds with HTTP 200 and provides:

• code: "01" indicating the instruction was accepted.
• status: "SUCCESS" confirming the Bre-B charge was created.
• data.payment_url: Hosted link that displays the payment instructions and Bre-B key.
• data.transaction: Echo of the request metadata.
• data.account_number: The Bre-B key the customer must enter in their bank or wallet.

Example Response

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "19kazMPNue2fOIp",
    "date": "2025-10-16 00:58:54",
    "payment_url": "https://link.staging.tumipay.co/payments/main?s=19kazMPNue2fOIp",
    "transaction": {
      "reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
      "amount": 1000,
      "currency": "COP",
      "payment_method": "BANK_TRANSFER"
    },
    "account_number": "@tumipaybreb"
  }
}

Webhook Notifications

Bre-B PayIn shares the same webhook contract as other PayIn methods. Expect the following statuses:

Status	Description
PENDING	Waiting for the customer to authorize the payment.
APPROVED	Funds settled successfully through Bre-B.
REJECTED	Customer cancelled the authorization or the institution declined it.

Reconcile each notification with your internal reference to update user experience, deliver products, or retry when necessary. Consult Webhooks for the full payload schema.

Handling Final Amounts

Bre-B participating institutions let payers overwrite the amount before authorizing the transfer. When that happens, TumiPay honors the final value sent by the network rather than the amount included in your original request. The synchronous response will still echo the amount you requested, so rely on webhook payloads for the definitive settled value. Adjust your reconciliation logic to detect under-payments or over-payments and surface any differences to your users or operations teams.