Integrar la API STK Push de KCB M PESA permite iniciar solicitudes de pago directamente al teléfono del cliente de forma segura y escalable. En este artículo detallamos paso a paso la autenticación, el envío de solicitudes STK Push, la recepción de callbacks y la interpretación de respuestas. Además mostramos cómo Q2BSTUDIO puede ayudar en la integración y en el diseño de soluciones de pagos dentro de ecosistemas más amplios que incluyen aplicaciones a medida, inteligencia artificial y ciberseguridad.
Sobre Q2BSTUDIO: somos una empresa de desarrollo de software especializada en aplicaciones a medida y software a medida, con experiencia en inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA y soluciones como power bi. Si necesitas una integración profesional de pagos dentro de una aplicación o plataforma, podemos diseñarla, implementarla y asegurarla. Conecta tu proyecto con nuestro servicio de desarrollo de aplicaciones a medida y potencia tus procesos con inteligencia artificial para empresas.
1 Autenticación y generación de token Antes de cualquier llamada al API se debe obtener un token usando el Consumer Key y Consumer Secret proporcionados por KCB durante el onboarding. Método HTTP POST al endpoint https://uat.buni.kcbgroup.com/token?grant_type=client_credentials Encabezado requerido Authorization Basic seguido del valor Base64 de consumerKey:consumerSecret Content Type application x www form urlencoded Si la autenticación es correcta se obtiene un access_token que se usa en todas las llamadas siguientes como Bearer token. Campos devueltos access_token token_type expires_in Donde expires_in indica segundos hasta que el token expira, típicamente 3600.
2 Iniciar una solicitud STK Push Con el token se realiza un POST al endpoint https://uat.buni.kcbgroup.com/mm/api/request/1.0.0/stkpush Encabezados Authorization Bearer access_token Content Type application json Parámetros de la petición phoneNumber - número del cliente en formato 2547XXXXXXXX amount - monto en KES invoiceNumber - referencia única opcional sharedShortCode - true si se usa short code compartido orgShortCode - paybill o till asignado orgPassKey - pass key asignado por KCB, suele estar en blanco callbackUrl - URL HTTPS en su servidor donde recibirá el resultado transactionDescription - descripción corta del pago Ejemplo de contenido de la petición sin formato JSON literal phoneNumber : 254708920430 amount : 1 invoiceNumber : 1123412831049 sharedShortCode : true orgShortCode : 522522 orgPassKey : [dejar en blanco si no aplica] callbackUrl : https://example.com/callback transactionDescription : pago escolar
3 Respuesta de aceptación Si la petición es válida la API responde con identificadores para seguimiento MerchantRequestID CheckoutRequestID ResponseCode y mensajes de confirmación. ResponseCode 0 indica que la solicitud fue aceptada y que se debe esperar un callback con el resultado final. Campos relevantes MerchantRequestID identificador único generado por la API CheckoutRequestID identificador de la transacción ResponseCode codigo de aceptación CustomerMessage mensaje para el cliente ResponseDescription detalle adicional
4 Ejecución y callback Cuando el cliente introduce su PIN y completa la transacción KCB envía un callback a la callbackUrl configurada. El callback incluye ResultCode ResultDesc y CallbackMetadata con detalles como Amount MpesaReceiptNumber TransactionDate y PhoneNumber. Interpretación común ResultCode 0 transacción exitosa ResultCode 1037 usuario no alcanzable ResultCode 2001 PIN inválido ResultCode 1032 usuario canceló la solicitud Al recibir el callback se debe validar CheckoutRequestID y MerchantRequestID contra su sistema, registrar el resultado y actualizar el estado del pedido o servicio.
5 Manejo de errores y códigos HTTP Errores típicos Invalid Credentials token inválido Missing Credentials credenciales ausentes Bad Request parámetros inválidos o faltantes Listado de códigos HTTP 200 solicitud procesada con éxito 400 petición errónea 401 no autorizado 403 prohibido 404 no encontrado 500 error interno 503 servicio no disponible Para errores específicos la API devuelve bloques con código y mensaje que deben registrarse y mapearse a las acciones de reintento o soporte.
6 Escenarios de callback y acciones recomendadas Transacción exitosa ResultCode 0 registrar recibo y entregar servicio Usuario cancela ResultCode 1032 notificar al usuario y permitir reintento Usuario unreachable ResultCode 1037 intentar nuevo STK Push según política de reintentos PIN inválido ResultCode 2001 bloquear temporalmente y notificar al usuario
7 Buenas prácticas de integración Seguridad almacenar consumerKey y consumerSecret en un vault o secret manager usar TLS y validar certificados en el servidor de callback implementar idempotencia con invoiceNumber y CheckoutRequestID registrar todas las solicitudes y callbacks con trazabilidad y timestamps crear métricas y alertas para fallos recurrentes y tiempos de respuesta En entornos productivos considere utilizar servicios cloud escalables y seguros y aplicar controles de ciberseguridad y pentesting antes del go live.
8 Cómo Q2BSTUDIO puede ayudar Q2BSTUDIO ofrece servicios completos para integrar STK Push dentro de aplicaciones web o móviles a medida, cubriendo diseño, desarrollo, seguridad y operaciones. Integramos soluciones con arquitecturas cloud en AWS y Azure, optimizamos procesos con automatización y aportamos analítica con power bi y servicios inteligencia de negocio para que los pagos se conviertan en insumos accionables. Si te interesa una integración segura y escalable podemos desarrollar una solución personalizada que incluya pruebas de penetración y monitorización continua.
9 Pasos para pasar a producción Reunir datos y requisitos con KCB solicitar go live mediante carta formal rellenar y firmar plantilla de solicitud enviar a buni@kcbgroup.com validar endpoints y certificados HTTPS en producción coordinar pruebas finales con KCB y programación de despliegue Para soporte con la integración o para que desarrollemos la solución completa ponte en contacto con nuestro equipo en Q2BSTUDIO y exploraremos la mejor arquitectura y las políticas de seguridad necesarias.
10 Recursos y contacto Para documentación técnica siga las guías del proveedor y ponga especial atención a los formatos de fecha y números en los callbacks. Si buscas una solución llave en mano que incluya desarrollo de aplicaciones, inteligencia artificial aplicada, agentes IA, ciberseguridad y despliegue en la nube, solicítanos una propuesta y te asesoramos desde la idea hasta la operación continua.
Palabras clave incluidas naturalmente en este artículo para mejorar posicionamiento: aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws y azure servicios inteligencia de negocio ia para empresas agentes IA power bi
Si necesitas que preparemos ejemplos de código adaptados a tu stack tecnológico o una guía de implementación paso a paso para tu equipo, contacta con Q2BSTUDIO y diseñamos la mejor solución para tu negocio.
