InicioPago con QRPreciosSeguridadDevelopersBlog Ingresar Crear cuenta
Blog / Developers
Developers · 10 nov 2026 · 9 min de lectura · por TAYPI

Cómo integrar pagos QR en PHP con el SDK de TAYPI

Integra pagos QR en cualquier proyecto PHP con el SDK oficial: crear cobros, leer estados y validar webhooks.

</>

Si desarrollas con PHP y quieres aceptar pagos con QR interoperable en Perú, integrar un SDK de pagos QR en PHP es una de las rutas más rápidas y seguras. En este artículo te explicamos cómo usar el SDK oficial de TAYPI para crear cobros, leer estados y validar webhooks sin depender de capturas de pantalla ni conciliaciones manuales.

¿Qué es un SDK de pagos QR PHP y por qué usarlo?

Un SDK (Software Development Kit) de pagos QR en PHP es una librería lista para incluir en tu proyecto, que encapsula la autenticación, las llamadas a la API REST y la verificación de firmas. En lugar de construir manualmente cada petición HTTP y calcular firmas HMAC-SHA256 a mano, el SDK te expone métodos más simples para el flujo de cobro.

TAYPI, pasarela de pagos QR interoperable para e-commerce y comercios en Perú, ofrece un SDK oficial de PHP que cubre tres necesidades centrales:

  • Crear un cobro y obtener un QR dinámico único más una URL de checkout.
  • Manejar la idempotencia para evitar cobros duplicados.
  • Verificar webhooks usando HMAC-SHA256.

Esto es especialmente útil si tu stack es PHP puro, Laravel, Symfony o cualquier framework compatible con Composer. El SDK te ahorra tiempo y reduce el riesgo de errores en integraciones sensibles.

Requisitos previos para integrar pagos QR con PHP

Antes de escribir código, asegúrate de tener lo siguiente:

  • PHP 7.4 o superior (idealmente PHP 8.1+ para mejor rendimiento y soporte de librerías modernas).
  • Composer para instalar dependencias.
  • Claves de sandbox de TAYPI, disponibles al registrarte en la plataforma.
  • Una cuenta de comercio Nivel 2 (KYB verificado) si vas a pasar a producción.
  • Un endpoint HTTPS en tu backend para recibir webhooks.
  • Conocimientos básicos de programación en PHP y consumo de APIs REST.

Importante: TAYPI opera sobre la infraestructura de pagos interoperables del BCRP, vía la Cámara de Compensación Electrónica (CCE). Eso implica que el pago se verifica directamente con la entidad financiera, no con capturas de pantalla. Por eso, una integración bien hecha debe confiar en los estados confirmados por la pasarela y no en comprobantes enviados por el cliente.

Instalación y configuración del SDK pagos QR PHP

Instalación mediante Composer

Aunque el SDK puede distribuirse como paquete Composer, el flujo típico consiste en agregar la dependencia a tu proyecto. Por ejemplo, una instalación conceptual sería:

composer require taypi/sdk-php

Luego, en tu archivo de configuración, defines las credenciales:

$config = [
    'api_key'    => 'tu_api_key_sandbox',
    'secret_key' => 'tu_secret_key_sandbox',
    'mode'       => 'sandbox', // Cambia a 'production' cuando estés listo
];

El SDK se encarga de firmar cada petición con HMAC-SHA256. No expongas nunca tu secret_key en el frontend ni en repositorios públicos.

Configuración de claves de sandbox

Las claves de sandbox te permiten simular cobros sin mover dinero real. Esto es clave para probar el flujo completo:

  • Creación de cobro.
  • Lectura del estado.
  • Recepción y validación de webhooks.

Para producción necesitarás completar la verificación de tu negocio y obtener credenciales reales. La activación de la cuenta no tiene costo de instalación, mensualidad ni permanencia.

Cómo crear un cobro con QR y checkout_url en PHP

El flujo principal de pago QR con TAYPI funciona así:

  1. Tu backend recibe la orden del cliente.
  2. Tu código PHP llama al SDK para crear un cobro.
  3. La API responde con un QR dinámico único y un checkout_url.
  4. Muestras el QR al cliente o rediriges a la URL de pago.
  5. El cliente paga desde Yape, Plin o cualquier billetera interoperable.
  6. Recibes la confirmación vía webhook y/o consultando el estado.

Un ejemplo conceptual de creación de cobro sería:

$cobro = $sdk->payments()->create([
    'amount' => 100.00,
    'currency' => 'PEN',
    'reference' => 'pedido-12345',
    'idempotency_key' => 'clave-unica-para-este-pedido',
]);

echo $cobro['qr_image'];       // Imagen del QR en base64 o URL
echo $cobro['checkout_url'];   // URL de pago para redirigir

El QR generado por cada cobro es dinámico y único, con monto fijo y referencia, y expira en 15 minutos. No es un QR estático reutilizable. Esta es una diferencia clave frente a los QR genéricos que algunos negocios imprimen una sola vez.

El monto mínimo por transacción es S/ 1.00. La comisión se descuenta solo de los cobros confirmados, con una fórmula clara: (monto × 2.50% + S/ 0.20) × 1.18, e incluye IGV. Te recomendamos revisar los precios de TAYPI para entender cuánto recibirás neto en cada liquidación.

Manejo de idempotencia y estados de pago en el SDK

¿Por qué la idempotencia es crítica?

En APIs de pago, un mismo pedido puede reintentarse por timeout, falla de red o doble clic. Sin idempotencia, podrías crear dos cobros para la misma orden, confundir al cliente y generar reclamos.

El SDK de TAYPI soporta idempotency_key para evitar cobros duplicados. Si envías la misma clave para el mismo pedido, la API devuelve el cobro original en lugar de crear uno nuevo. Esto es especialmente relevante en e-commerce, donde la experiencia de pago debe ser confiable.

Lectura del estado de un cobro

Además del webhook, puedes consultar el estado activamente:

$estado = $sdk->payments()->getStatus($paymentId);

if ($estado === 'confirmed') {
    // Entregar el producto o servicio
} elseif ($estado === 'expired') {
    // Sugerir reintentar el pago
}

Un cobro puede estar en estados como pending, confirmed, expired o failed. La lógica de tu aplicación debe tratar cada estado correctamente. Nunca entregues el producto antes de la confirmación bancaria directa.

Para profundizar en este tema, te recomendamos leer idempotencia en APIs de pago: por qué es crítica.

Verificación de webhooks con HMAC-SHA256 en PHP

Los webhooks son la forma más eficiente de enterarte en tiempo real cuando un pago se confirma. TAYPI envía una notificación HTTP a tu endpoint con los datos del cobro. Para evitar que un tercero te envíe notificaciones falsas, cada petición incluye una firma HMAC-SHA256.

Cómo validar la firma

El flujo de verificación típico es:

  1. Recibe el payload crudo (string JSON) y el header de firma.
  2. Calcula la firma con tu secret_key.
  3. Compara con la firma recibida usando hash_equals().
  4. Si no coinciden, descarta la petición.

Un ejemplo conceptual de validación:

$payload = file_get_contents('php://input');
$firmaRecibida = $_SERVER['HTTP_X_TAYPI_SIGNATURE'] ?? '';

$firmaCalculada = hash_hmac('sha256', $payload, $secretKey);

if (!hash_equals($firmaCalculada, $firmaRecibida)) {
    http_response_code(401);
    exit('Firma inválida');
}

$data = json_decode($payload, true);
// Procesar la confirmación...

Esta técnica protege contra ataques de suplantación y garantiza que solo aceptes notificaciones legítimas. Si quieres entender los fundamentos, consulta HMAC-SHA256 explicado: cómo proteger tus transacciones.

Recomendaciones para tu endpoint de webhook

  • Responde rápido con HTTP 200 para evitar retries innecesarios.
  • Procesa la confirmación de forma asíncrona si tu lógica es pesada.
  • Registra los payloads para auditoría y resolución de disputas.
  • Usa HTTPS y TLS 1.3 de extremo a extremo.

Pruebas en sandbox y puesta en producción

Antes de cobrar de verdad, usa el entorno sandbox para simular el flujo completo:

  • Crea cobros con distintos montos y referencias.
  • Prueba la idempotencia enviando la misma clave dos veces.
  • Verifica que tu endpoint de webhook valide firmas correctamente.
  • Simula pagos expirados y confirmados para ajustar tu lógica de negocio.

Una vez que todo funcione, pasa a producción. Recuerda que TAYPI requiere que tu negocio esté Nivel 2 (KYB verificado) para recibir liquidaciones. El dinero se deposita a tu CCI desde el día hábil siguiente (desde T+1), sujeto a un depósito mínimo que se acumula sin cargo si no se alcanza.

Si buscas una guía más visual sobre montos y tarifas, consulta precios de TAYPI y seguridad de TAYPI para conocer las certificaciones ISO 27001:2022 e ISO 9001:2015.

Comparativa: SDK PHP vs API REST directa

CaracterísticaSDK oficial de PHPAPI REST directa
Curva de aprendizajeBajaMedia
Gestión de autenticación HMAC-SHA256AutomáticaManual
Control de idempotenciaIntegradoDebes implementarlo
Validación de webhooksIncluidaManual
Flexibilidad de endpointsLa que expone el SDKTotal
Tiempo de integración típicoAlrededor de un díaVariable

En general, si tu proyecto es PHP, el SDK te ahorra trabajo y reduce errores. La API REST es útil si necesitas un control muy fino o usas un lenguaje sin SDK oficial.

Preguntas frecuentes

¿El SDK de pagos QR PHP de TAYPI acepta tarjetas de crédito?

No. TAYPI no procesa tarjetas de crédito ni débito. Solo acepta pagos con QR interoperable peruano, es decir, Yape, Plin y cualquier billetera interoperable conectada a la CCE del BCRP. Esto elimina contracargos y comisiones de marca de tarjetas.

¿Necesito ser un comercio verificado para probar el SDK en sandbox?

Puedes usar las claves de sandbox para pruebas antes de completar la verificación total. Sin embargo, para recibir pagos reales y liquidaciones desde T+1, tu negocio debe estar Nivel 2 (KYB verificado) conforme a la normativa PLAFT peruana.

¿Cómo se verifica la firma HMAC-SHA256 de los webhooks?

El payload crudo se firma con tu secret_key usando el algoritmo HMAC-SHA256. La firma viaja en un header de la petición. En tu backend, recalcula la firma y compárala con hash_equals(). Si no coincide, descarta la petición.

¿Qué pasa si el cliente no paga el QR generado?

Cada cobro genera un QR dinámico único que expira en 15 minutos. Si no se paga dentro de ese plazo, el cobro pasa a estado expirado y puedes sugerir al cliente crear uno nuevo.

¿El SDK oficial de PHP es compatible con Laravel o Symfony?

Sí. Al ser una librería PHP estándar, puede integrarse en proyectos Laravel, Symfony o PHP puro, siempre que tu entorno cumpla los requisitos de PHP y Composer.

Conclusión

Integrar pagos QR en PHP con un SDK de pagos QR PHP es una forma práctica de aceptar Yape, Plin y cualquier billetera interoperable sin tarjetas ni validación manual de capturas. El SDK oficial de TAYPI cubre lo esencial: crear cobros con QR dinámico y checkout_url, manejar idempotencia para evitar duplicados y verificar webhooks con HMAC-SHA256.

Si tu e-commerce o comercio peruano busca una pasarela de QR interoperable con verificación bancaria directa, liquidación desde T+1 y comisiones claras, este camino técnico te ahorra tiempo y reduce riesgos. Revisa la documentación para developers y crea tus claves de sandbox para empezar hoy.


¿Listo para integrar pagos QR en tu proyecto PHP? Crea tu cuenta gratuita en TAYPI y prueba el SDK oficial con claves de sandbox.

¿Listo para cobrar con QR?

Crea tu cuenta gratis y genera tu primer QR en minutos.

Abrir cuenta gratis