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
- Your application creates a PayIn request with
payment_method: "BREB".
- TumiPay responds with a hosted
payment_url and the Bre-B transaction metadata (data.account_number) that the customer must use.
- 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.
- 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": "[email protected]",
"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. |
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.
