Acepta pagos con Bre-B

16 octubre 2026

Bre-B es uno de los procesadores de APM (métodos alternativos de pago) en Colombia: en lugar de pedir los datos bancarios del pagador y redirigirlo a su banco, Kushki genera un código QR que el usuario escanea desde su aplicación bancaria para autorizar el pago en tiempo real.

Qué procesadores tiene tu comercio lo responde la consulta de configuración (GET /transfer/v1/config) — el modelo completo está en ¿Cómo funcionan los pagos con APM?. Las integraciones existentes con PSE no cambian: siguen su guía de transferencias bancarias.

Así es la experiencia de pago de tu cliente

Tu comercio muestra el código QR en el checkout, el cliente lo escanea desde la app de su banco, revisa el monto y confirma, y el pago se aprueba en tiempo real.

Detalles de operación

1. Consulta tus procesadores

Este paso es opcional si Bre-B es tu único procesador, pero recomendado siempre: será la regla a medida que se habiliten más procesadores y flujos. Antes de tokenizar, llama a Consulta la configuración de Transfer In (GET /transfer/v1/config) con tu credencial pública. La entrada de Bre-B llega con supportedFlows: copia su name y el type del flujo en el objeto processor del token.

{
  "processors": [
    { "name": "Pse Processor", "currency": "COP" },
    {
      "name": "Bre-B Credibanco Processor",
      "currency": "COP",
      "supportedFlows": [
        { "type": "QR", "name": "QR Code", "description": "QR code payment" }
      ]
    }
  ]
}

2. Crea el token

Realiza la petición del token usando el mismo endpoint que el flujo PSE. Para activar el flujo Bre-B, incluye el objeto processor con las propiedades name y flowType, copiadas exactamente de la respuesta de la consulta de procesadores. No es necesario consultar el listado de bancos antes de este paso.

Campos requeridos

El objeto processor no admite propiedades adicionales: cualquier otra propiedad produce 400.

Campos opcionales

callbackUrl · userType · documentType · documentNumber · paymentDescription · email

El campo bankId no aplica en este flujo.

Si envías userType, documentType o documentNumber, aplican las reglas condicionales para COP — consulta ¿Cómo funcionan los pagos con APM?.

var options = {
  'method': 'POST',
  'url': 'https://api-uat.kushkipagos.com/transfer/v1/tokens',
  'headers': { 'Public-Merchant-Id': '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "amount": { "subtotalIva0": 1000, "subtotalIva": 1000, "iva": 0 },
    "currency": "COP",
    "processor":{
        "name":"Bre-B Credibanco Processor",
        "flowType":"QR"
    }
  })
};
request(options, function(error, response) {
  var data = JSON.parse(response.body);
  console.log('token:', data.token);
});

payload = json.dumps({
  "amount": { "subtotalIva0": 1000, "subtotalIva": 1000, "iva": 0 },
  "currency": "COP",
  "processor":{
        "name":"Bre-B Credibanco Processor",
        "flowType":"QR"
    }
})
headers = {'Public-Merchant-Id': '', 'Content-Type': 'application/json'}
response = requests.post('https://api-uat.kushkipagos.com/transfer/v1/tokens',
                          headers=headers, data=payload)
print('token:', response.json()['token'])

$body->append(json_encode([
  "amount" => ["subtotalIva0" => 1000, "subtotalIva" => 1000, "iva" => 0],
  "currency" => "COP",
  "processor" => [
        "name" => "Bre-B Credibanco Processor",
        "flowType" => "QR"
    ]
]));
// POST a /transfer/v1/tokens con Public-Merchant-Id
echo json_decode($client->getResponse()->getBody(), true)['token'];

3. Genera el código QR

Con el token obtenido, inicializa la transacción. Kushki retorna un código QR en formato base64 que debes mostrar al usuario para que lo escanee desde su aplicación bancaria.

var options = {
  'method': 'POST',
  'url': 'https://api-uat.kushkipagos.com/transfer/v1/init',
  'headers': { 'Private-Merchant-Id': '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "token": "{{token}}",
    "amount": { "subtotalIva": 0, "subtotalIva0": 1000, "iva": 0 },
    // "fullResponse": "v2"  // opcional — incluye el objeto details en la respuesta
  })
};
request(options, function(error, response) {
  var data = JSON.parse(response.body);
  console.log('qr:', data.qr);
  console.log('ref:', data.transactionReference);
});

payload = json.dumps({
  "token": "{{token}}",
  "amount": { "subtotalIva": 0, "subtotalIva0": 1000, "iva": 0 },
  # "fullResponse": "v2"  # opcional — incluye el objeto details en la respuesta
})
headers = {'Private-Merchant-Id': '', 'Content-Type': 'application/json'}
data = requests.post('https://api-uat.kushkipagos.com/transfer/v1/init',
                      headers=headers, data=payload).json()
print('qr:', data['qr'])

$body->append(json_encode([
  "token" => "{{token}}",
  "amount" => ["subtotalIva" => 0, "subtotalIva0" => 1000, "iva" => 0],
  // "fullResponse" => "v2"  // opcional
]));
// POST a /transfer/v1/init con Private-Merchant-Id
$data = json_decode($client->getResponse()->getBody(), true);
echo $data['qr'];

Ejemplo de respuesta — sin fullResponse

{
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "transactionReference": "f2110170-8eec-4214-b2d0-38970d44f8e1"
}

Ejemplo de respuesta — con fullResponse: “v2”

{
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "transactionReference": "f2110170-8eec-4214-b2d0-38970d44f8e1",
  "details": {
    "status": "initializedTransaction",
    "amount": { "currency": "COP", "iva": 0, "subtotalIva": 1000, "subtotalIva0": 1000 },
    "created": 1784125900901,
    "description": "-",
    "merchantId": "20000000106921087000",
    "merchantName": "Mi Comercio Colombia"
  }
}

Cómo renderizar el campo qr

El campo qr contiene una cadena Data URI completa (data:image/png;base64,...). Para mostrarlo en web:

<img src="{qr}" alt="Escanea para pagar" width="250" />

En apps nativas, decodifica el base64 y renderiza el bitmap con el componente de imagen de tu plataforma.

4. Muestra el QR al usuario y espera el pago

El usuario escanea el QR desde su aplicación bancaria y autoriza el pago. Kushki notifica el resultado de forma asíncrona. El QR expira en 10 minutos. Si el usuario no escanea en ese tiempo, deberás generar un nuevo token e init. Para monitorear el resultado: configura un webhook (ver paso 6) o consulta Get Status manualmente. Mientras el pago está pendiente, puedes cancelar la transacción (ver paso 5).

5. Cancela la transacción (opcional)

Si el usuario no puede completar el pago o necesitas invalidar el QR activo, cancela la transacción antes de que alcance un estado final.

Cuándo usar la cancelación Usa este endpoint cuando el usuario ingrese un monto incorrecto, decida no completar el pago, o necesites emitir un nuevo QR antes de que el QR original expire (vigencia de 10 minutos). Solo es posible si la transacción aún no tiene un estado final.

Endpoint PATCH https://{api-url}/transfer/v1/cancel/{token}

Donde {token} es el token obtenido en el paso 2.

Respuesta exitosa (HTTP 204 No Content) La cancelación exitosa retorna HTTP 204 sin cuerpo en la respuesta.

Error — transacción con estado final (HTTP 400)

{
  "code": "T023",
  "message": "Transacción posee un estado final."
}

6. Consulta el estado de la transacción

El estado final del pago llega de forma asíncrona. Puedes recibirlo de dos maneras:

• Webhook: Kushki notifica automáticamente cuando el pago es aprobado o rechazado. Sin cambios respecto al flujo PSE.
• Get Status: Consulta manualmente el estado usando el token en el path.

var options = {
  'method': 'GET',
  'url': 'https://api-uat.kushkipagos.com/transfer/v1/status/{{token}}', // token del paso 2
  'headers': { 'Private-Merchant-Id': '' }
};
request(options, function(error, response) {
  console.log(response.body);
});

token = '{{token}}'  # token obtenido en el paso 2
url = f'https://api-uat.kushkipagos.com/transfer/v1/status/{token}'
headers = {'Private-Merchant-Id': ''}
response = requests.get(url, headers=headers)
print(response.text)

$token = '{{token}}';  // token del paso 2
$request->setRequestUrl("https://api-uat.kushkipagos.com/transfer/v1/status/{$token}");
$request->setRequestMethod('GET');
$request->setHeaders(['Private-Merchant-Id' => '']);
$client->enqueue($request)->send();
echo $client->getResponse()->getBody();

7. Errores de la API

Al operar con el flujo multiprocesador puedes recibir errores de la API en la consulta de procesadores, la tokenización o al iniciar la transacción. Los campos de la respuesta de error son code y message.

Los errores de las transferencias bancarias con PSE están en Códigos de error para transferencias.

8. Prueba tu integración

El ambiente UAT simula escenarios mediante el valor de transaction_amount, que corresponde a la suma de todos los campos del objeto amount en la petición (subtotalIva0 + subtotalIva + iva). Por ejemplo, para activar el escenario 10000 envía subtotalIva0: 5000, subtotalIva: 5000, iva: 0. Si la suma no coincide con ningún valor de la tabla, la respuesta es exitosa sin webhook.

9. Prepara tu certificación

Toma en consideración las siguientes pautas para aprobar la certificación técnica:

• Los cálculos de los montos son correctos (subtotalIva, subtotalIva0, iva).
• El objeto processor se envía con name: "Bre-B Credibanco Processor" y flowType: "QR" en la petición del token.
• El código QR se muestra correctamente al usuario desde el campo qr de la respuesta del init.
• Se implementa el endpoint de cancelación para los flujos donde el usuario no completa el pago.
• Se muestran mensajes en pantalla de acuerdo con las respuestas de Kushki.
• Si se reciben notificaciones por webhook, se responde con HTTP 200.
• El botón de pago se deshabilita después del primer clic para evitar doble envío.
• Todas las respuestas de Kushki se guardan y registran (requeridas en caso de soporte).
• El logo de Kushki es visible. Descárgalo en s3.amazonaws.com/kushki-cdn-production/docs/Logo+Kushki.zip
• Se envían todos los campos requeridos según la referencia API.

Artículos relacionados

• Acepta pagos con transferencia Recibe transferencias bancarias

• Configura tus webhooks Recibe notificaciones del estado de tus pagos.

• Cancelación - Referencia técnica Referencia técnica