Introducción
Guía de integración con la API de QvaPay para aceptar pagos en tu aplicación, gestionar tu balance, aplicar a ofertas P2P y realizar cobros automáticos a tus clientes.
Bienvenido a la API de QvaPay
La API de QvaPay te permite integrar pagos digitales directamente en tu aplicación. Con ella puedes:
- Crear y gestionar facturas de pago con URLs compartibles
- Cobrar directamente a usuarios que autoricen pagos recurrentes
- Consultar transacciones y su estado en tiempo real
- Obtener información de tu app y balance
La API está diseñada para desarrolladores que quieran ofrecer QvaPay como método de pago en sus plataformas, tiendas online, bots de Telegram, aplicaciones móviles o cualquier servicio digital.
URL Base
Todas las peticiones se realizan sobre:
https://api.qvapay.comAutenticación
La API soporta dos métodos de autenticación según el tipo de integración que necesites.
Bearer Token (usuario)
Ideal para aplicaciones que actúan en nombre de un usuario autenticado. El token se obtiene al iniciar sesión y se envía en el header Authorization:
curl -X GET https://api.qvapay.com/user/balance \
-H "Authorization: Bearer {token}"El token se recibe en la respuesta del endpoint de login. Por defecto expira en 2 horas, o en 180 días si se activa la opción "recordarme".
Credenciales de App (app-id + app-secret)
Ideal para integraciones servidor-a-servidor donde tu aplicación opera de forma autónoma. Las credenciales se envían como headers en cada petición:
curl -X POST https://api.qvapay.com/v2/balance \
-H "Content-Type: application/json" \
-H "app-id: {tu-app-uuid}" \
-H "app-secret: {tu-app-secret}"Para obtener tus credenciales de app:
- Inicia sesión en QvaPay
- Ve a Mis Aplicaciones
- Crea una nueva aplicación o selecciona una existente
- Copia el App ID (UUID) y App Secret
El App Secret solo se muestra una vez al crear la app. Guárdalo en un lugar seguro.
Cuándo usar cada método
| Método | Caso de uso | Endpoints |
|---|---|---|
| Bearer Token | Apps móviles, frontends, bots que actúan como un usuario | /user/*, /transaction/*, /p2p/* |
| Credenciales de App | Pasarelas de pago, cobros automáticos, integraciones backend | /v2/* (facturas, cobros, balance) |
Algunos endpoints aceptan ambos métodos. En ese caso, las credenciales de app tienen prioridad.
Rate Limiting
Los endpoints están protegidos con rate limiting para garantizar la estabilidad de la plataforma. Los límites varían según el endpoint, pero en general:
- Endpoints de cobro: 5 requests cada 20 segundos por app
- Endpoints generales: 3 requests cada 5 segundos
Si recibes un error 429 Too Many Requests, reduce la frecuencia de tus peticiones y reintenta con backoff exponencial.
Formato de Respuestas
Todas las respuestas son JSON. Las respuestas exitosas retornan código 200:
{
"message": "Operación exitosa",
"data": { ... }
}Los errores retornan el código HTTP correspondiente con un mensaje descriptivo:
{
"error": "Descripción del error"
}Códigos HTTP
| Código | Significado |
|---|---|
200 | Operación exitosa |
400 | Request inválido, datos faltantes o validación fallida |
401 | Credenciales inválidas o token expirado |
403 | No tienes permiso para esta operación (incluye code: "KYC_REQUIRED", ver abajo) |
404 | Recurso no encontrado |
429 | Rate limit excedido |
500 | Error interno del servidor |
Cuando el error tiene un contrato programático, la respuesta añade un campo code estable (p. ej. KYC_REQUIRED, W1_ATTESTATION_REQUIRED, DUPLICATE_REQUEST). Programa contra code, no contra el texto de error, que puede cambiar.
Cumplimiento normativo
QvaPay opera bajo el programa BSA/AML y las regulaciones OFAC de EE. UU. Tres reglas afectan a cualquier integración que mueva dinero:
- KYC obligatorio para operar. Toda cuenta necesita verificación de identidad aprobada antes de mover saldo. Sin ella, cualquier llamada que no sea de lectura responde
403con{ "code": "KYC_REQUIRED", "kyc_url": "/onboarding" }. Recibir saldo no requiere KYC. - Atestaciones de propósito. Los retiros cripto (
W-1), los depósitos bancarios y las operaciones con destino Cuba (P-1…P-4) llevan un objetocompliancecon la autocertificación del cliente. Hoy es obligatorio solo para el navegador web; apps móviles, apps de comercio y clientes API pueden omitirlo (se registra la ausencia) y deberían enviarlo. El formato completo está en Retiros → Cumplimiento. - Travel Rule. Envíos y retiros de $3,000 o más exigen nombre y dirección de calle del titular en su ficha, y del beneficiario en rails fiat.
Identifica tu cliente para que estas reglas se apliquen por canal: las apps móviles envían el header x-qvapay-client-platform: ios|android; las apps de comercio se autentican con app-id + app-secret; un Authorization: Bearer sin cookie de sesión se trata como cliente API.
Comisiones
Las comisiones por cada moneda están detalladas en coins.qvapay.com. En el caso de las transacciones por cargo automático, la comisión de procesamiento es del 0.5% (deducida del balance del pagador; el comercio recibe el monto completo). Esta comisión es waived cuando quien paga tiene plan GOLD.
Webhooks
Al crear una factura puedes especificar una URL de webhook. Cuando la factura sea pagada, QvaPay enviará una notificación POST a esa URL con los datos de la transacción, permitiéndote confirmar el pago automáticamente en tu sistema.
Integraciones y plugins
¿No quieres integrar la API desde cero? QvaPay ofrece plugins oficiales para las plataformas más populares, empezando por WooCommerce. Revisa todas las integraciones disponibles y los SDKs por lenguaje.
Comunidad
Si tienes dudas, quieres compartir tu integración o necesitas ayuda de otros desarrolladores, únete a nuestro grupo de Telegram para desarrolladores:
Grupo de Telegram para Desarrolladores
Próximos pasos
Explora los endpoints disponibles en el menú lateral para comenzar tu integración. Te recomendamos empezar por:
- Info — Verifica que tus credenciales funcionan
- Balance — Consulta tu balance disponible
- Crear Factura — Crea tu primera factura de pago