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

> Real-time disbursements in Colombia using Bre-B keys or interoperable QR codes.

## 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](./breb) 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/{key_value}/resolve`

### Example Request

```bash theme={null}
curl --request GET 'https://api-empresas.staging.topup.com.co/production/api/v1/breb/key/@tumipaybreb/resolve' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key'
```

### Example Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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": "johndoe@email.com",
    "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 Type     | Value             |
| ------------ | ----------------- |
| Phone        | `300000001`       |
| Email        | `breb@tumipay.co` |
| Document     | `1003191919`      |
| Alphanumeric | `@tumipaybreb`    |

Use the sandbox environment to validate your integration end-to-end before scheduling production activation.

## Status Notifications

| Status     | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| `PENDING`  | Transaction created and awaiting confirmation from Bre-B.     |
| `APPROVED` | Funds successfully transferred to the beneficiary.            |
| `REJECTED` | Transaction 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.