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.
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.
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:
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.
Antes de escribir código, asegúrate de tener lo siguiente:
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.
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.
Las claves de sandbox te permiten simular cobros sin mover dinero real. Esto es clave para probar el flujo completo:
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.
El flujo principal de pago QR con TAYPI funciona así:
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.
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.
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.
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.
El flujo de verificación típico es:
secret_key.hash_equals().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.
Antes de cobrar de verdad, usa el entorno sandbox para simular el flujo completo:
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.
| Característica | SDK oficial de PHP | API REST directa |
|---|---|---|
| Curva de aprendizaje | Baja | Media |
| Gestión de autenticación HMAC-SHA256 | Automática | Manual |
| Control de idempotencia | Integrado | Debes implementarlo |
| Validación de webhooks | Incluida | Manual |
| Flexibilidad de endpoints | La que expone el SDK | Total |
| Tiempo de integración típico | Alrededor de un día | Variable |
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.
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.
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.
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.
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.
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.
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.
Crea tu cuenta gratis y genera tu primer QR en minutos.
Abrir cuenta gratis