Bre-B PayIn - Tumipay API

Overview

Bre-B PayIn lets Colombian customers initiate instant transfers using their Bre-B key or interoperable QR. With PayIn v2, hybrid mode returns both a hosted page and payment instructions in one call. Review the Bre-B overview before configuring the PayIn-specific steps outlined here.

Flow Summary

Create a PayIn with POST /api/v2/payin and payment_method: "BREB" or "BREB_QR".
TumiPay responds with payment_url and payment_information (key or QR data).
Show payment_information in your UI or redirect the customer to payment_url.
TumiPay sends webhook notifications when the payment settles.

Request Essentials

Parameter	Value / Requirement	Notes
Endpoint	`POST /api/v2/payin`	PayIn v2
Currency	`COP`	Colombian Peso
Country	`CO`	Colombia
Payment Method	`"BREB"` or `"BREB_QR"`	Hybrid experience
redirect_url	Optional	Return URL after hosted flow
ipn_url	Optional	Webhook for status updates
expiration_time	Optional	Minutes the key/QR remains valid (default 15 for BREB)
customer_data	Standard identity fields	Required

For Bre-B payments, the customer may adjust the amount before authorizing in their bank app. Handle partial or modified amounts in your reconciliation logic.

Response fields (UTC)

All timestamps use UTC (Y-m-d H:i:s):

Field	BREB	BREB_QR
`data.date`	Transaction creation	Transaction creation
`payment_information.expiration_date`	Key validity end	QR validity end

In Checkout flows (not Bre-B), payment_information is not returned. Bre-B methods are always Hybrid: you receive both payment_url and payment_information.

Example Request (BREB)

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v2/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": 50000,
  "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": "johndoe@example.com",
    "full_name": "John Doe"
  },
  "expiration_time": 30,
  "ipn_url": "https://your-domain.com/webhook",
  "redirect_url": "https://your-domain.com/payment/ok"
}'

Example Response (BREB)

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "breb-ticket-id",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/breb-payment?s=breb-ticket-id",
    "payment_information": {
      "key_value": "@TUMI1234567890123",
      "expiration_date": "2025-10-15 16:14:57"
    },
    "transaction": {
      "reference": "BREB-PAYIN-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "BREB"
    }
  }
}

Example Request (BREB_QR)

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

Example Response (BREB_QR)

{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "breb-qr-ticket-id",
    "date": "2025-10-15 15:44:57",
    "payment_url": "https://link.staging.topup.com.co/breb-qr-payment?s=breb-qr-ticket-id",
    "payment_information": {
      "qr_code": "iVBORw0KGgoAAAANSUhEUgAA...",
      "expiration_date": "2025-10-15 16:14:57"
    },
    "transaction": {
      "reference": "BREB-QR-PAYIN-001",
      "amount": 50000,
      "currency": "COP",
      "payment_method": "BREB_QR"
    }
  }
}