Bancard VPOS Gateway

# Bancard VPOS Gateway for WooCommerce

Pasarela de pagos Bancard VPOS para WooCommerce que permite procesar pagos con tarjetas de crédito y débito de forma segura a través de la plataforma VPOS de Bancard.

🚀 Características

🎯 Funcionalidades Principales

• ✅ Procesamiento de pagos con tarjetas de crédito y débito
• ✅ Integración completa con WooCommerce
• ✅ Compatibilidad con Checkout clásico y Bloques (Block Checkout)
• ✅ Soporte para High-Performance Order Storage (HPOS)
• ✅ Redireccionamiento seguro a formulario de pago de Bancard
• ✅ Validación y verificación de webhooks
• ✅ Soporte para reembolsos (parciales y completos)
• ✅ Logging detallado para debugging
• ✅ Entornos de pruebas y producción separados

🔧 Características Técnicas

• ✅ Compatible con WordPress 6.0+ y WooCommerce 9.0+
• ✅ Soporte para WooCommerce Blocks (Checkout moderno)
• ✅ Responive design para todos los dispositivos
• ✅ Diseño compatible con dark mode
• ✅ Soporte para accesibilidad (WCAG)
• ✅ Optimizado para performance
• ✅ Código modular y extensible

🌐 Integración con Bancard

• ✅ Single Buy API (Iniciar transacción)
• ✅ Webhooks para confirmación de pagos
• ✅ Verificación de tokens de seguridad
• ✅ Soporte para diferentes códigos de respuesta
• ✅ Manejo automático de redirecciones

📋 Requisitos del Sistema

Requisitos Mínimos

• WordPress: 6.0 o superior
• WooCommerce: 8.0 o superior
• PHP: 7.4 o superior
• MySQL: 5.6 o superior (recomendado 8.0+)

Requisitos Recomendados

• WordPress: 6.7+
• WooCommerce: 8.0+
• PHP: 8.1+
• Servidor web: Apache/Nginx con HTTPS forzoso

Certificados Requeridos

• Certificado SSL válido (para producción)
• Credenciales de Bancard VPOS (clave pública y privada)

📦 Instalación

Instalación Manual

1. Descargar el plugin

   git clone https://github.com/clauvaldez/bancard-wordpress-plugin.git
   cd bancard-wordpress-plugin

2. Subir al servidor

   • Copia la carpeta completa del plugin a wp-content/plugins/bancard-vpos
   • O instala via ZIP desde el panel de WordPress

3. Activar el plugin

   • Ve a Plugins → Plugins instalados
   • Busca "Bancard VPOS Gateway"
   • Haz clic en Activar

4. Configurar permisos (opcional pero recomendado)

   # Asegurar que los archivos sean legibles por el servidor web
   chown -R www-data:www-data /var/www/html/wp-content/plugins/bancard-vpos/
   chmod -R 755 /var/www/html/wp-content/plugins/bancard-vpos/

Instalación via Composer (para desarrolladores)

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/clauvaldez/bancard-wordpress-plugin.git"
    }
  ],
  "require": {
    "clauvaldez/bancard-wordpress-plugin": "dev-main"
  }
}

Verificación de Instalación

Una vez instalado y activado, verificar:

• ✅ Plugin aparece en la lista de plugins activados
• ✅ Opción "Bancard VPOS" aparece en WooCommerce → Ajustes → Pagos
• ✅ No hay errores de PHP en los logs de WordPress
• ✅ Gateway está deshabilitado por defecto (configurar credenciales primero)

⚙️ Configuración

Configuración Básica

1. Ve a WooCommerce → Ajustes → Pagos
2. Localiza "Tarjeta de Crédito/Débito con Bancard VPOS"
3. Haz clic en Administrar (o Configurar)

Campos de Configuración

🎛️ Configuración General

• Habilitar/Deshabilitar: Activar el gateway de pago
• Título: Texto que verán los clientes (ej: "Pagar con tarjeta")
• Descripción: Información adicional mostrada en checkout
• Entorno: Ambiente para procesamiento de pagos
  • staging: Para pruebas y desarrollo
  • production: Para transacciones reales

🔑 Credenciales de Bancard

• Clave Pública: Proporcionada por Bancard
• Clave Privada: Proporcionada por Bancard

  ⚠️ IMPORTANTE: La clave privada nunca debe ser compartida

🔧 Opciones Avanzadas

• Modo Debug: Activar logging detallado (solo en desarrollo)
• X-Frame-Options: Política para iframes (CSP)

Configuración por Entorno

Ambiente de Pruebas (Staging)

Clave Pública: [proporcionada por Bancard]
Clave Privada: [proporcionada por Bancard]
Entorno: Staging
URLs: https://vpos.infonet.com.py:8888/*

Ambiente de Producción

Clave Pública: [proporcionada por Bancard]
Clave Privada: [proporcionada por Bancard]
Entorno: Production
URLs: https://vpos.infonet.com.py/*
Modo Debug: Desactivado

URLs de Webhooks

Configurar en el panel de Bancard las siguientes URLs:

Para Staging

Éxito: https://tudominio.com/?wc-api=bancard_vpos
Error:  https://tudominio.com/?wc-api=bancard_vpos

Para Producción

Éxito: https://tudominio.com/?wc-api=bancard_vpos
Error:  https://tudominio.com/?wc-api=bancard_vpos

🎯 Uso

Para Compradores

1. Agregar productos al carrito
2. Ir al checkout
3. Seleccionar método de pago "Bancard VPOS"
4. Completar datos de envío y facturación
5. Confirmar orden
6. Será redirigido automáticamente al formulario seguro de Bancard

Flujo de Pago

sequenceDiagram
    participant Cliente
    participant WooCommerce
    participant Plugin
    participant Bancard
    participant Webhook

    Cliente->>WooCommerce: Selecciona Bancard VPOS
    WooCommerce->>Plugin: process_payment()
    Plugin->>Bancard: Single Buy API
    Bancard-->>Plugin: Process ID + Token
    Plugin-->>WooCommerce: Redirect URL
    WooCommerce-->>Cliente: Página de recibo con iframe
    Cliente->>Bancard: Completa pago en formulario seguro
    Bancard->>Webhook: Envía confirmación
    Webhook-->>Plugin: process_webhook()
    Plugin-->>WooCommerce: Actualiza orden
    WooCommerce-->>Cliente: Página de agradecimiento

Estados de Orden

El plugin maneja automáticamente los siguientes estados:

• Pendiente: Esperando pago (recibido process_id)
• En espera: Pago pendiente en Bancard
• Procesado: Pago completado exitosamente
• Rechazado: Pago fallido
• FALLIDO: Error en procesamiento

Procesamiento de Webhooks

El plugin maneja webhooks con diferentes formatos:

// Formato nuevo (recomendado)
{
  "operation": {
    "shop_process_id": "123",
    "response_code": "00",
    "transaction_id": "...",
    "response_description": "Pago aprobado"
  }
}

// Formato alternativo
{
  "shop_process_id": "123",
  "response_code": "00",
  "response": "S"
}

🛠️ Desarrollo

Arquitectura del Plugin

bancard-vpos/
├── bancard-vpos.php           # Plugin principal y hooks
├── bancard-gateway-classes.php # Clase WC_Bancard_VPOS_Gateway
├── bancard-debug.php          # Herramienta de diagnóstico (REMOVER EN PROD)
├── includes/
│   └── class-bancard-blocks-integration.php # Integración con bloques
└── assets/
    ├── bancard-blocks.asset.php    # Dependencias JS para bloques
    ├── bancard-blocks.js          # JavaScript para checkout blocks
    ├── bancard.js                 # JavaScript frontend (jQuery)
    └── bancard.css                 # Estilos CSS

Clases Principales

WC_Bancard_VPOS_Gateway

• Extiende WC_Payment_Gateway
• Maneja configuración y procesamiento de pagos
• Genera tokens de seguridad
• Maneja webhooks y confirmaciones

WC_Bancard_VPOS_Blocks_Integration

• Extiende AbstractPaymentMethodType
• Registra el método de pago en WooCommerce Blocks
• Proporciona data al frontend de bloques

Hooks y Filtros

Actions

• woocommerce_api_bancard_vpos: Procesar webhooks
• wp_enqueue_scripts: Cargar scripts frontend
• admin_enqueue_scripts: Cargar scripts admin
• add_meta_boxes: Agregar información en órdenes

Filters

• woocommerce_payment_gateways: Registrar gateway
• plugin_action_links: Agregar enlaces en plugins

API de Bancard VPOS

Endpoints por Entorno

Staging:

• Single Buy: https://vpos.infonet.com.py:8888/vpos/api/0.3/single_buy
• Confirmation: https://vpos.infonet.com.py:8888/vpos/api/0.3/confirmation
• JavaScript: https://vpos.infonet.com.py:8888/checkout/javascript/dist/bancard-checkout-4.0.0.js

Production:

• Single Buy: https://vpos.infonet.com.py/vpos/api/0.3/single_buy
• Confirmation: https://vpos.infonet.com.py/vpos/api/0.3/confirmation
• JavaScript: https://vpos.infonet.com.py/checkout/javascript/dist/bancard-checkout-4.0.0.js

Payload de Single Buy

{
  "public_key": "MI_PUBLIC_KEY",
  "operation": {
    "token": "md5_hash",
    "shop_process_id": "123",
    "currency": "PYG",
    "amount": "100000.00",
    "description": "Orden #123",
    "return_url": "https://tudominio.com/checkout/order-received/123",
    "cancel_url": "https://tudominio.com/checkout"
  }
}

Logging y Depuración

Tabla de Logs

wp_bancard_vpos_logs (
  id INT AUTO_INCREMENT PRIMARY KEY,
  order_id BIGINT NOT NULL,
  process_id VARCHAR(255),
  event_type VARCHAR(50) NOT NULL,
  message TEXT NOT NULL,
  data LONGTEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
)

Tipos de Evento

• request: Solicitud enviada a Bancard
• response: Respuesta recibida
• payment_success: Pago completado
• payment_failed: Pago fallido
• payment_pending: Pago en proceso
• webhook_received: Webhook procesado

Ver Logs

// Ver en WP-CLI
wp db query "SELECT * FROM wp_bancard_vpos_logs WHERE order_id = 123 ORDER BY created_at DESC;"

// O en PHP
global $wpdb;
$logs = $wpdb->get_results("SELECT * FROM {$wpdb->prefix}bancard_vpos_logs WHERE order_id = 123");

Testing

Herramienta de Diagnóstico

Sube temporalmente bancard-debug.php a la raíz del plugin y accede:

https://tudominio.com/wp-content/plugins/bancard-vpos/bancard-debug.php

⚠️ IMPORTANTE: Eliminar después de usar.

Probando con WooCommerce

1. Configurar entorno staging
2. Crear orden de prueba
3. Verificar logs: WooCommerce → Estado → Logs
4. Usar credenciales de prueba de Bancard

Desarrollo Local

# Clonar repositorio
git clone https://github.com/clauvaldez/bancard-wordpress-plugin.git
cd bancard-wordpress-plugin

# Instalar dependencias de desarrollo si existen
composer install
npm install

# Crear symlink
ln -s /path/to/plugin /path/to/wordpress/wp-content/plugins/bancard-vpos

# Activar debug
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'BANCARD_VPOS_DEBUG', true );

Contribuciones

1. Fork el proyecto
2. Crear rama feature: git checkout -b feature/nueva-funcionalidad
3. Commit cambios: git commit -am 'Agrega nueva funcionalidad'
4. Push: git push origin feature/nueva-funcionalidad
5. Crear Pull Request

Compilar Assets (si es necesario)

# Compilar CSS/JS si usas build tools
npm run build
# O manualmente concatenar y minimizar

🔧 Troubleshooting

Problemas Comunes

1. Gateway no aparece en checkout

Causa: Credenciales faltantes o WooCommerce inactivo Solución:

• Verificar credenciales configuradas
• Activar WooCommerce
• Limpiar cache: Ctrl+F5

2. Error "Invalid token"

Causa: Formato de webhook incorrecto Solución:

• Verificar fórmula de hash del token
• Revisar logs de webhook

3. Iframe no se carga

Causa: CSP o JavaScript bloqueado Solución:

• Configurar headers CORS
• Verificar URL del JavaScript de Bancard

4. Pago pendiente

Causa: Webhook no llegue o falla procesamiento Solución:

• Verificar URL de webhook en panel Bancard
• Revisar logs de webhook

Comandos Útiles

-- Ver órdenes con Bancard
SELECT * FROM wp_posts p 
JOIN wp_postmeta pm ON p.ID = pm.post_id 
WHERE p.post_type = 'shop_order' 
AND pm.meta_key = '_payment_method' 
AND pm.meta_value = 'bancard_vpos';

-- Contar pagos por estado
SELECT COUNT(*) as count, meta_value as status 
FROM wp_postmeta 
WHERE meta_key = '_bancard_process_id' 
GROUP BY meta_value;

📚 Recursos Adicionales

Documentación Bancard

• API VPOS Oficial
• Guía de Integración
• Webhook Documentation

WooCommerce

• Payment Gateway API
• Blocks Integration
• HPOS Compatibility

Desarrollo WordPress

• Plugin Development
• Security Best Practices
• WP-CLI

📄 Licencia

Este plugin está licenciado bajo GPL v2 or later.

Copyright (C) 2025 Cv

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

🤝 Soporte

Canales de Soporte

• GitHub Issues: Para bugs y feature requests
• WordPress Support: Para consultas generales
• Bancard Support: Para temas específicos de la API

Reportar Problemas

Al reportar bugs, incluye:

• ✅ Versión de WordPress, WooCommerce y PHP
• ✅ Log de errores (si aplica)
• ✅ Pasos para reproducir
• ✅ Configuración del plugin (sin credenciales)
• ✅ URL de webhook configurada

Donaciones

Si encuentras útil este plugin, considera hacer una donación para apoyar el desarrollo continuo.

---

⭐ Si te gusta este plugin, dale una estrella en GitHub!

Hecho con ❤️ por Cv para la comunidad WordPress.