¿Cómo funcionan los pagos con APM?

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

Te explicamos cómo funcionan los métodos alternativos de pago (APM) y el flujo multiprocesador en Kushki

Los métodos alternativos de pago (APM) permiten a tus clientes pagar sin tarjeta, con rieles de pago en tiempo real. En Colombia hoy puedes aceptar pagos con Bre-B: el cliente escanea un código QR desde su app bancaria y autoriza el pago al instante.

Los APM funcionan con un flujo multiprocesador: una sola integración con la API de Kushki, en la que el procesador que uses en cada transacción define cómo integras y cómo paga tu cliente. Tu comercio puede tener habilitado uno o varios procesadores, y a medida que se habiliten más, tu integración no cambia: solo consultas qué procesadores tienes y armas el token según cada uno.

¿Buscas pagos con PSE?

PSE es la integración tradicional de transferencias bancarias y no cambia. Consulta Recibe transferencias bancarias.

Disponible solo para integraciones 100% API

El flujo multiprocesador aplica a integraciones directas con la API: el token se solicita desde tu backend. Kajita y Kushki.js aún no soportan el objeto processor.

El modelo: consulta tus procesadores

Toda integración APM empieza por la misma pregunta: ¿qué procesadores tiene mi comercio? La respuesta vive en un solo lugar:

GET /transfer/v1/config (con tu credencial pública) → processors[]

Cada entrada de la respuesta te dice cómo continuar:

La entrada elegida...	Es un procesador de...	El token se arma...
Con `supportedFlows` (Bre-B)	Flujos de pago APM	Con `processor: { name, flowType }`, copiado tal cual de la respuesta; solo `amount` y `currency` siguen requeridos.
Sin `supportedFlows` (PSE)	Redirección bancaria (tradicional)	Sin el objeto `processor`. Sigue la guía de transferencias bancarias.

Si tu comercio tiene varios procesadores, usa supportedFlows de cada entrada para saber cómo armar el token con cada uno. Si tiene uno solo puedes omitir la consulta, pero intégrala desde el inicio: es la regla del producto a medida que se habilitan más procesadores y flujos.

El flujo, de punta a punta

Procesadores disponibles

Bre-B — pago con código QR en tiempo real

Consultas tus procesadores y eliges la entrada de Bre-B — no necesitas listado de bancos.

Solicitas el token con el objeto processor y luego inicias la transacción.

Kushki responde con un código QR (base64) que muestras a tu cliente.

Tu cliente lo escanea desde su app bancaria y autoriza el pago en tiempo real. El QR vence en 10 minutos y puedes cancelar la transacción mientras no tenga estado final.

Recibes el estado final por webhook o consultándolo con Get Status.

La guía completa está en Acepta pagos con Bre-B.

Arma el token según el procesador

Caso	`processor`	Requeridos	Notas
Bre-B QR	`{ "name": "Bre-B Credibanco Processor", "flowType": "QR" }`	`amount`, `currency`, `processor`	`bankId` no aplica; los demás campos son opcionales.

El objeto processor no admite propiedades adicionales (produce 400) y flowType no tiene valor por defecto: sus valores se copian de la consulta de procesadores, sin alias.

Reglas condicionales para COP

Aplican siempre que envíes estos campos opcionales:

Condición	Regla
`userType: "1"` (persona jurídica)	`documentType` debe ser `"NIT"`.
`userType: "0"` (persona natural)	`documentType` no puede ser `"NIT"`.
`documentType: "PP"` (pasaporte)	`documentNumber` alfanumérico, mínimo 6 (`^[0-9a-zA-Z]{6,}$`).
Cualquier otro `documentType`	`documentNumber` solo dígitos, mínimo 6 (`^[0-9]{6,}$`).

Compatibilidad token ↔ procesador

El token queda ligado al procesador con el que fue generado; POST /transfer/v1/init lo valida:

Token generado	Procesador del comercio	Resultado
Con `processor` Bre-B	Bre-B	Continúa (la respuesta trae `qr`).
Con `processor`	Otro procesador	`422 E046`.
Sin `processor`	Bre-B	`422 E046`.
Con `processor` Bre-B	Bre-B sin llaves configuradas	`404 E049`.

Si recibes E046, revisa la consulta de procesadores y regenera el token con el procesador correcto. Los errores de cada caso están en la sección Errores de la guía Acepta pagos con Bre-B.

Integra cada procesador

Acepta pagos con Bre-B

Integración del pago con código QR en tiempo real

¿Cómo funcionan los pagos con APM?

El modelo: consulta tus procesadores#

El flujo, de punta a punta#

Procesadores disponibles#

Bre-B — pago con código QR en tiempo real#

Arma el token según el procesador#

Reglas condicionales para COP#

Compatibilidad token ↔ procesador#

Integra cada procesador#