Cobrar con Yape y Plin en tu web: qué se automatiza y qué no
En Perú, muchos clientes no pagan con tarjeta: pagan con Yape o con Plin. Si tu sistema web solo acepta tarjeta, pierdes ventas que sí existían. El problema es que "aceptar Yape" puede significar tres cosas muy distintas, y solo una de ellas se puede automatizar sin que una persona mire el celular. Esta nota separa las tres, dice qué confirma la documentación oficial de cada pasarela y cómo diseñar el flujo para que un pago falso no active nada.
Parte de nuestra experiencia en Arca, que empezó cobrando por Yape de forma manual y después migró a pasarela, y de integrar Izipay y Culqi en otros sistemas. Todo lo que atribuimos a una pasarela está enlazado a su documentación; lo que no pudimos confirmar, lo decimos.
Las tres formas de cobrar con Yape
- Pago manual con tu QR. Muestras tu QR o tu número de Yape, el cliente paga, y alguien (tú o el sistema) confirma que el dinero llegó. No hay contrato con nadie, empiezas hoy.
- Yape dentro de una pasarela. El cliente paga en tu checkout con un código que genera la app de Yape, y la pasarela te responde si el cobro salió bien. Requiere afiliación con la pasarela.
- Una API de Yape directa para tu comercio. No encontramos documentación pública de una API de cobros de Yape para comercios. Si alguien te vende "la API de Yape" para cobrar, pide primero la documentación y comprueba si es un cobro en tu checkout o algo distinto.
Plin es parecido pero no idéntico: cada banco lo opera a su manera. Más abajo vemos qué dice Izipay de Plin Interbank.
Qué dicen las pasarelas (con enlace a su doc)
Izipay. Su documentación tiene un caso de uso
Pagar con Yape
dentro de su SDK Web: configuras payMethod: 'YAPE_CODE', el
cliente escribe en tu checkout el código de un solo uso que genera la app
de Yape, y el checkout valida ese código. El resultado llega al
callbackResponse en JSON. La página lista errores propios de
Yape: código vencido o incorrecto (Y12), límite diario de
compras por internet excedido (Y07), cuenta bloqueada
temporalmente (Y08) y "opción válida solo para Yape con BCP"
(Y09). Dos detalles útiles: si el monto supera el límite de
Yape y es tu único método, el checkout directamente no se muestra, y los
límites vigentes se consultan en una tabla de valores del sitio de
desarrolladores. Esa página no explica cómo se habilita el método en tu
comercio: eso se pide a Izipay.
Izipay también documenta Plin Interbank: el cliente escribe el celular asociado a una cuenta de Interbank, tiene 3 minutos para aprobar la operación en la app del banco, y el máximo por operación es de S/ 5000 o $ 1500 según su página. Además tiene pago con QR: generas un QR único para el monto y el cliente lo escanea con la billetera que prefiera; su página no nombra qué billeteras. La integración de tarjeta con Izipay está en cobrar con Izipay. Ojo: en esa nota hablamos del formulario embebido de micuentaweb; la documentación de Yape que citamos es la del SDK Web, que es otra superficie. Antes de prometer Yape en un sistema que ya usa el formulario embebido, confirma con Izipay qué integración necesitas.
Culqi. Su página de tokens Yape describe un cargo único en dos pasos: el cliente ingresa su número de Yape y el código de aprobación que obtiene en la app (con Culqi Checkout, en un pop-up), eso genera un token con tu llave pública, y tu backend crea el cargo con la llave privada. Según esa página, el código dura como máximo 2 minutos, el pago máximo con Yape es de S/ 2000 y solo se reciben soles. Si llamas la API de tokens directamente en lugar de usar el checkout, Culqi pide cumplir PCI DSS y enviar un formulario SAQ-D. La página describe solo cargos únicos; por eso, como contamos en suscripciones recurrentes, una suscripción nativa se hace con tarjeta y Yape queda para pagos sueltos. No encontramos mención de Plin en esa página.
Niubiz. En la página Pago Web el QR aparece como una opción adicional dentro del formulario para pagar con billetera, "sea Yape, Tunki, etc.". Según su tabla comparativa, el botón de pago lo acepta, la integración desacoplada no (aunque puede usar el QR integrado) y los CMS solo en Prestashop, WordPress y OpenCart. No encontramos ahí un flujo de código de Yape como el de Izipay o Culqi, ni límites de monto.
En las tres, lo mismo: el método se activa por contrato con la pasarela, no por código. Lo primero que tienes que hacer es preguntar si tu comercio puede usarlo, y en qué integración.
Qué se automatiza y qué no
Con pasarela, la confirmación es automática: el cliente paga, la pasarela te dice "aprobado" y tu sistema activa el servicio. Con el QR manual, no. Tu sistema no tiene cómo preguntarle a Yape "¿llegaron S/ 20 de este cliente?". El dinero cae en una cuenta personal o de negocio, y la única fuente de verdad es tu historial dentro de la app. Eso significa que cobrar con QR propio siempre incluye un paso humano de verificación.
Ese paso humano tiene un límite natural: sirve para cobros sueltos, no para renovaciones periódicas. En Arca el Yape manual convivió un tiempo con el pago con tarjeta; cuando migramos a las suscripciones nativas de Culqi, que solo funcionan con tarjeta, eliminamos el Yape manual por completo.
No confíes en una captura de pantalla
La captura de "Yapeaste S/ 20" es lo primero que mucha gente pide como comprobante, y es lo más fácil de falsificar: una captura es una imagen, y cualquiera puede editar un monto, una fecha o un nombre. Si tu sistema activa servicio al subirla, cualquiera lo activa gratis. Reglas que aplicamos al diseñar este flujo:
- La captura sirve para encontrar el pago, no para probarlo. El que confirma abre su propio historial de Yape y busca el movimiento. Si no aparece ahí, no existe.
- Un monto único por pedido. Si dos clientes pagan S/ 20 el mismo día, no sabes cuál es cuál. Añade céntimos como marca (S/ 20.07 en vez de S/ 20.00) y guárdalos en el pedido. Así el monto exacto identifica el pago. Haz antes un pago real pequeño para confirmar que Yape deja enviar ese monto con céntimos.
- El nombre que muestra el historial. El movimiento muestra el nombre del que pagó; pídele que lo escriba al reportar el pago y compara.
- Solo un administrador confirma. La acción de confirmar es una ruta protegida, con registro de quién y cuándo.
- El QR y el número se publican desde un solo lugar. En Arca el número de Yape al que se paga y el de soporte son distintos, y el QR tiene que corresponder al primero. Una vez estuvieron unificados en una constante porque tenían el mismo valor; al cambiar el de soporte se habrían redirigido los pagos sin que nadie lo notara. Hoy están separados, con un comentario que lo explica.
El modelo de datos mínimo para pagos manuales
Trata el pago manual como un pedido con estados, no como un botón. La tabla guarda lo que el cliente declara y lo que el administrador verifica:
CREATE TABLE pago_manual (
id uuid PRIMARY KEY,
usuario_id uuid NOT NULL,
plan text NOT NULL,
monto_cent integer NOT NULL, -- 2007 = S/ 20.07, resuelto en el servidor
estado text NOT NULL DEFAULT 'pendiente',
-- pendiente | confirmado | rechazado | vencido
nombre_pagador text, -- lo que declara el cliente
creado_at timestamptz NOT NULL DEFAULT now(),
vence_at timestamptz NOT NULL, -- p. ej. 48 h
confirmado_por uuid,
confirmado_at timestamptz
);
CREATE UNIQUE INDEX pago_manual_monto_pendiente
ON pago_manual (monto_cent) WHERE estado = 'pendiente'; El índice único parcial es la pieza clave: impide que dos pedidos pendientes compartan el mismo monto exacto. Al crear el pedido, si el monto choca, sumas otro céntimo y reintentas. Confirmar es una sola transacción que cambia el estado y activa el plan:
await withTransaction(async (tx) => {
const r = await tx.query(
`UPDATE pago_manual
SET estado='confirmado', confirmado_por=$2, confirmado_at=now()
WHERE id=$1 AND estado='pendiente'
RETURNING usuario_id, plan`, [id, adminId]);
if (r.rowCount === 0) return; // ya confirmado: idempotente
await activarPlan(tx, r.rows[0]); // mismo camino que el pago con pasarela
});
Dos cosas. El WHERE estado='pendiente' hace la confirmación
idempotente: dos admins pulsando a la vez no suman dos veces el plan. Y
activarPlan es la misma función que usa el flujo
con pasarela, para que no haya dos formas de activar servicio.
El bug que no se ve con un solo usuario
En Arca, el admin confirmaba un pago de Yape y el cliente no veía su plan activado hasta recargar. La causa no era Yape: la confirmación del admin actualizaba la base pero no avisaba al cliente afectado por el canal de tiempo real. Lo difícil fue reproducirlo, porque probando con un solo usuario (que es justo el caso que sí funcionaba) todo parecía bien. La corrección fue emitir de forma explícita al usuario dueño del pago. El detalle está en tiempo real: el evento que le toca a otro usuario. En un flujo manual, donde quien confirma y quien espera son personas distintas, esto no es opcional.
Conciliación: qué comparar y cuándo
Con pasarela, concilias contra el reporte de la pasarela: cada transacción aprobada tiene un identificador que tu base también guardó. Con QR manual, concilias contra el historial de Yape. Un proceso simple que sirve:
- Cada día, lista los
pago_manualpendientes con más de 24 horas. - Contrasta cada uno con el historial de la app: ¿hay un movimiento con ese monto exacto?
- Marca como confirmado, rechazado (no llegó nada) o déjalo hasta que venza.
- Al final del mes, suma lo confirmado en tu sistema y compáralo con lo recibido en Yape. La diferencia debe ser cero; si no lo es, hay un pago confirmado que no llegó o uno que llegó y no registraste.
Lo contable (comprobante electrónico, qué se declara) es aparte y depende de tu régimen; en validar una pasarela con un cobro de un sol contamos cómo probar un cobro real sin perder dinero antes de abrir al público.
Diseñar el flujo para el cliente
Un pago manual falla casi siempre por fricción del cliente, no por tecnología. Lo que ayuda:
- En móvil, el número y el monto copiables. Quien está en el celular no puede escanear su propia pantalla. Un botón "copiar número" y "copiar monto" evita errores de tecleo.
- Un solo paso por pantalla: elegir plan, ver QR con monto exacto, avisar "ya pagué" con el nombre del pagador. Sin registrarse dos veces.
- Estado visible. "Pendiente de confirmación" con la fecha límite, y aviso por correo o notificación cuando se confirme, para que el cliente no escriba preguntando.
- Vencimiento claro. Un pedido que nadie confirma en unas horas debe vencer y liberar el monto, para que el índice único no se llene de pendientes viejos.
- Con pasarela, mensajes de error en lenguaje humano. Mapea
los códigos (código vencido, límite diario) a frases como "el código
de Yape dura pocos minutos, genera uno nuevo". El cliente que ve
Y12se va.
Cuál elegir
- Empiezas, pocos clientes, cobros sueltos: QR manual con monto único, confirmación del admin y la tabla de arriba.
- Ya tienes volumen o necesitas cobrar sin intervenir: pasarela con Yape, pidiendo a Izipay o Culqi que habilite el método en tu comercio.
- Necesitas renovar solo cada mes: tarjeta con suscripción nativa. Yape no es el medio para eso.
Checklist
- Confirmé con la pasarela, por escrito, que Yape (y Plin, si lo quiero) está habilitado en mi comercio y en qué integración.
- Conozco los límites vigentes de monto de cada método.
- La captura de pantalla nunca activa servicio por sí sola.
- Cada pedido manual tiene monto único, estado y fecha de vencimiento.
- Confirmar es idempotente y usa la misma función que el pago con pasarela.
- El cliente afectado recibe el aviso en tiempo real y por correo.
- El número y el QR de cobro salen de un único lugar, separados del contacto de soporte.
- Concilio contra el historial de Yape (o el reporte de la pasarela) con una frecuencia fija.