Acepta pagos con Bre-B

🚧 Early Release — Beta

Este producto está en acceso temprano. Los parámetros, estructuras de respuesta y comportamientos pueden cambiar sin previo aviso. No uses esta versión en producción sin coordinarlo previamente con el equipo de integraciones de Kushki.

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.

Importante

Disponible exclusivamente para Colombia con el procesador Bre-B configurado en tu MID. Para habilitarlo, contacta a tu ejecutivo de cuenta.

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

Parámetro	Detalle
Moneda	COP
Tipo de integración	100% API — el token se solicita desde tu backend. Kajita y Kushki.js aún no soportan este flujo.
Campo adicional requerido	El objeto `processor` (`name` + `flowType`) en el cuerpo del token
Consulta de listado de bancos	No requerida para este flujo
Resultado del init	Código QR (base64 PNG) para pago desde app bancaria
Vigencia del QR	10 minutos. Pasado ese tiempo el QR se invalida y debe generarse un nuevo token e init.
Tiempo de procesamiento	Tiempo real
Cancelación	`PATCH /transfer/v1/cancel/{token}` — disponible mientras la transacción no tenga estado final. Retorna HTTP 204 No Content.
Webhook	Sin cambios respecto al flujo PSE
Códigos de error	Ver la sección 7. Errores de la API de esta guía

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

Campo	Tipo	Descripción
`amount.subtotalIva0`	number	Monto de la transacción (sin IVA)
`amount.subtotalIva`	number	Monto de la transacción (con IVA). Igual a subtotalIva0 si iva = 0
`amount.iva`	number	Valor del IVA (0 si no aplica)
`currency`	string	Moneda. Debe ser "COP"
`processor.name`	string	NUEVO campo requerido. Debe ser `"Bre-B Credibanco Processor"`, exactamente como lo devuelve la consulta de procesadores — sin alias cortos
`processor.flowType`	string	NUEVO campo requerido. Debe ser `"QR"`. No tiene valor por defecto

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?.

JavaScript

Python

PHP

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.

JavaScript

Python

PHP

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:

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.

Referencia técnica

Para mayor detalle sobre el comportamiento de la cancelación, consulta el documento de mapeo interno:
Cancelación — Referencia técnica

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.

JavaScript

Python

PHP

Sin cambios en el webhook

La estructura del webhook es idéntica al flujo PSE existente.

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.

Endpoint	HTTP	Código	¿Cuándo ocurre?	¿Qué debe hacer el comercio?
`GET /transfer/v1/config`	`500`	`E002`	Error al consultar la configuración del comercio. Mensaje: «Ha ocurrido un error inesperado.»	Reintenta; si persiste, contacta a soporte.
`POST /transfer/v1/tokens`	`400`	—	El body no cumple el contrato: campo requerido ausente, valor fuera del enumerado (`processor.name`, `processor.flowType`) o propiedad no permitida dentro de `processor`.	Corrige el body según la consulta de procesadores y el contrato del flujo elegido.
`POST /transfer/v1/init`	`422`	`E046`	El token no es compatible con el procesador resuelto.	Revisa la consulta de procesadores y regenera el token con el procesador correcto.
`POST /transfer/v1/init`	`404`	`E049`	El comercio no tiene un procesador Bre-B configurado (sin llaves).	Verifica la configuración del procesador con Kushki.
Todos	`401`	—	Credencial pública inválida o ausente.	Verifica el `Public-Merchant-Id`.

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.

Solo son simulaciones

Estos montos son identificadores de escenario en el sandbox. No tienen significado económico. No los uses en producción.

transaction_amount	HTTP status	Estado	Webhook	Nota
10000	201	SUCCESS	Dispara → PAID	Happy path con webhook
9999	201	SUCCESS	No dispara	La transacción queda inicializada
11000	500	ERROR	No dispara	QR-CODE-0001
12000	201	SUCCESS	Dispara → rejected	Transacción rechazada
13000	—	TIMEOUT	No dispara	Se deja la transacción inicializada. Reutiliza el DELAY_MS existente.
99999999	400	ERROR	No dispara	QR-CODE-0059 — monto fuera de rango
Cualquier otro	201	SUCCESS	No dispara	Respuesta exitosa genérica

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.

Acepta pagos con Bre-B

Así es la experiencia de pago de tu cliente#

Detalles de operación#

1. Consulta tus procesadores#

2. Crea el token#

3. Genera el código QR#

Cómo renderizar el campo qr#

4. Muestra el QR al usuario y espera el pago#

5. Cancela la transacción (opcional)#

6. Consulta el estado de la transacción#

7. Errores de la API#

8. Prueba tu integración#

9. Prepara tu certificación#

Artículos relacionados#

Así es la experiencia de pago de tu cliente

Detalles de operación

1. Consulta tus procesadores

2. Crea el token

3. Genera el código QR

Cómo renderizar el campo qr

4. Muestra el QR al usuario y espera el pago

5. Cancela la transacción (opcional)

6. Consulta el estado de la transacción

7. Errores de la API

8. Prueba tu integración

9. Prepara tu certificación

Artículos relacionados