> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.topup.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](./breb) 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.                                          |

<Note>
  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.
</Note>

## Example Request

```bash theme={null}
curl --request POST 'https://api-empresas.staging.topup.com.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": "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"
}'
```

## 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

```json theme={null}
{
  "code": "01",
  "status": "SUCCESS",
  "message": "Operacion exitosa",
  "data": {
    "ticket": "19kazMPNue2fOIp",
    "date": "2025-10-16 00:58:54",
    "payment_url": "https://link.staging.topup.com.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](/api-reference/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.