Conecte SumUp a WebBlocks Commerce

Esta guía consigue que el primer pago de SumUp Sandbox funcione sin cobrar dinero real. esta escrito para propietarios de tiendas y operadores de sitios. No es necesario crear un formulario de pago: los clientes ingresan los detalles de su tarjeta en la página de pago alojada de SumUp.

Lo que necesitas

  • an instaló y habilitó el complemento WebBlocks Commerce
  • acceso al Panel de SumUp
  • permiso para administrar la configuración de comercio, o un administrador de hosting que pueda agregar datos protegidos anulaciones de variables de entorno
  • una dirección HTTPS pública para la tienda
  • aproximadamente diez minutos para la configuración inicial de la zona de pruebas

Los pagos Sandbox son simulaciones. No mueven dinero real.

Antes de comenzar

WebBlocks Commerce acepta credenciales de pago a través de su formulario protegido de Configuración de Commerce. el los valores se cifran en reposo, los campos son de solo escritura y los secretos guardados nunca se vuelven a mostrar. Nunca deben ingresarse en una página de CMS, bloque, producto o campo de configuración pública.

Las variables de entorno administradas por Hosting permanecen disponibles como anulaciones opcionales. No enviar la API Introduzca un correo electrónico normal, un chat, una captura de pantalla o un ticket de soporte. Introdúcela directamente en el protegido formulario o utilice el administrador secreto de la plataforma de hosting u otro canal seguro aprobado.

Paso 1: Crear un comerciante de SumUp Sandbox

  1. Inicie sesión en SumUp Dashboard.
  2. Abrir Configuración de desarrollador.
  3. Obra la pestaña Sandboxes.
  4. Crear un comerciante sandbox si no existe ninguno.
  5. Utilice el selector de cuentas para seleccionar el comerciante sandbox.

La cuenta seleccionada debe estar claramente marcada como zona de pruebas. Nunca utilices un comerciante real para esto primera prueba.

Si su cuenta SumUp no tiene configuración de desarrollador ni opción de zona de pruebas, cree una cuenta de desarrollador desde el enlace en la guía oficial de pruebas de pago en línea de SumUp.

Paso 2: Copie el código de comerciante de Sandbox

Con el comerciante sandbox seleccionado, mire el área superior izquierda del Panel de SumUp. espectáculos resumidos el nombre de la cuenta y Merchant ID allí. WebBlocks Commerce llama a este valor código de comerciante. Normalmente tiene un aspecto similar al MXXXXXXX.

Copie ese valor para el Paso 4. No utilice el ID de comerciante de su cuenta real.

Paso 3: Crear una clave API de prueba

Mantenga seleccionado el comerciante sandbox y luego:

  1. Amplía tu perfil y abre Configuración.
  2. Ir a Para desarrolladores → Kit de herramientas.
  3. Abrir API Claves.
  4. Seleccione Create y asigne a la clave un nombre reconocible, como WebBlocks Commerce sandbox.
  5. Copie o descargue la clave secreta cuando SumUp la muestre.

No utilice la clave pública SumUp. WebBlocks Commerce necesita la clave API secreta del lado del servidor. un La clave secreta de prueba normalmente comienza con sk_test_. SumUp no vuelve a mostrar el secreto completo, por lo que guárdelo inmediatamente en un administrador secreto aprobado.

La integración directa actual es para una cuenta de comerciante controlada por el propietario del sitio. OAuth es no es necesario para esta configuración.

Paso 4: Configurar WebBlocks Commerce

  1. Inicie sesión en el administrador de CMS.
  2. Obra Comercio → Configuración de comercio.
  3. Seleccione puerta de enlace SumUp y modo Sandbox.
  4. Ingrese la clave API secreta y el ID del comerciante, luego guarde.

Los campos de credenciales son de solo escritura. Dejar un campo en blanco conserva el valor guardado; utilizar el control claro y explícito sólo cuando desee eliminarlo.

Las implementaciones administradas por hosting pueden agregar estas anulaciones de entorno opcionales:

Agregue estos valores a la configuración secreta o de variable de entorno de la plataforma de alojamiento:

WEBBLOCKS_COMMERCE_GATEWAY=sumup
WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY=EUR
WEBBLOCKS_COMMERCE_SUMUP_MODE=sandbox
WEBBLOCKS_COMMERCE_SUMUP_API_KEY=replace-with-your-sk_test-key
WEBBLOCKS_COMMERCE_SUMUP_MERCHANT_CODE=replace-with-your-sandbox-merchant-id

E Los valores del entorno tienen prioridad y hacen que los controles de formulario correspondientes sean de solo lectura. si el La instalación utiliza un archivo Laravel .env, agregue los valores allí. Luego borre el caché configuración:

php artisan config:clear

Si su implementación normalmente almacena en caché la configuración, reconstruya esa caché usando su implementación normal procedimiento. Reinicie los trabajadores PHP de larga ejecución cuando su plataforma de alojamiento lo requiera.

La etiqueta de modo sandbox ayuda a los operadores a ver qué entorno está previsto. SumUp usa una API nombre de host, por lo que la clave API y el código de comerciante deben pertenecer a la cuenta sandbox.

Paso 5: Confirmar que el comercio esté listo

  1. Inicie sesión en el administrador de CMS.
  2. Abra Commerce → Configuración de comercio, o visite /webadmin/plugins/webblocks-commerce/settings.
  3. Confirme todo lo siguiente:
    • puerta de enlace activa: sumup
    • moneda predeterminada: EUR (u otra moneda compatible con SumUp)
    • Modo resumen: sandbox
    • Clave API: configurada
    • código de comerciante: configurado
    • pago: listo
    • esquema del complemento: listo

La pantalla de configuración deliberadamente dice solo "configurado" o "faltante". Nunca muestra la API clave en sí, incluso después de guardar con éxito.

Si el esquema no está listo, abra System → Plugins → WebBlocks Commerce y ejecute la configuración del complemento o migraciones primero.

Paso 6: Crear un producto de prueba

  1. abrir Comercio → Productos.
  2. Crear o editar un producto.
  3. Establezca un título, slug, precio, moneda y clase de impuestos.
  4. Elija EUR para la primera prueba SumUp a menos que el comerciante sandbox utilice otra opción que se muestra en el selector de moneda.
  5. Establezca el estado del producto en Active.
  6. Guardar el producto.

A El producto borrador o archivado no se puede retirar. Si el stock rastreado está habilitado, asegúrese de al menos una unidad está disponible.

Paso 7: Agregar el bloque de comercio nativo

  1. Obra la página CMS deseada en el generador de páginas.
  2. Agregue un bloque Commerce Buy Button a un espacio de página normal.
  3. Seleccione el producto activo.
  4. Elija las opciones de etiqueta de botón, alineación y visualización de precio.
  5. Previsualice y publique la página a través del flujo de trabajo normal de CMS.

No utilice un bloque HTML de confianza ni pegue una URL de pago de SumUp en el contenido. Una URL de pago se crea para cada pedido y caduca después de aproximadamente 30 minutos.

Paso 8: Realice un pago exitoso en Sandbox

  1. Obra la página pública del producto o la página que contiene el botón Comercio.
  2. Añadir el producto al carrito.
  3. Consulta la cantidad, el IVA, la moneda y el importe final.
  4. Seleccione Continuar para asegurar el pago.
  5. En la página alojada por SumUp, utilice esta tarjeta de prueba oficial de sandbox: 
Card number: 4200 0000 0000 0091
Expiry date: any future date, for example 12/30
CVV: any three digits, for example 123
Cardholder: any name
  1. Completa el pago y utiliza la acción de devolución para volver a la tienda.
  2. En el administrador de CMS, abra Commerce → Pedidos.
  3. Confirma que el pedido cambia a paid y el intento de pago a succeeded.

La página de retorno del navegador no es prueba de pago. El pedido se paga sólo después de WebBlocks Comercio recibe la notificación de SumUp, recupera el pago de SumUp y verifica el comerciante, referencia, monto, moneda, estado final y transacción exitosa.

No se necesita configuración manual del webhook SumUp

Para esta integración, no cree ni pegue una URL de webhook en el Panel de SumUp. WebBlocks Comercio envía automáticamente esta devolución de llamada como pago return_url:

https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup

La tienda pública debe utilizar HTTPS y SumUp debe poder acceder a esta URL. Un cortafuegos, mantenimiento. La página, la autenticación HTTP o la regla de proxy no deben bloquear la solicitud POST de SumUp.

Prueba de falla opcional

SumUp El sandbox utiliza ciertos totales para simular un pago rechazado. Para probar la ruta de falla, cree un producto temporal cuyo total de pago final sea exactamente 11.00 EUR, luego use una zona de pruebas tarjeta de prueba. Confirme que el pedido no esté marcado como pagado y que el stock reservado se libere después del Se procesa el error.

No cambie el precio de un producto real para esta prueba.

Cambiar a pagos en vivo

Cambiar solo después de que el flujo completo de la zona de pruebas sea exitoso:

  1. Seleccione la cuenta de comerciante real en SumUp Dashboard.
  2. Complete cualquier verificación comercial y configuración de pago requerida por SumUp.
  3. Copiar el ID de comerciante activo.
  4. Cree una clave API secreta activa separada. Una clave activa normalmente comienza con sk_live_.
  5. Reemplace los valores de la zona de pruebas guardados en Configuración de comercio, cambie el modo a Live y guarde. Las implementaciones administradas por hosting pueden reemplazar sus anulaciones de entorno:
WEBBLOCKS_COMMERCE_GATEWAY=sumup
WEBBLOCKS_COMMERCE_SUMUP_MODE=live
WEBBLOCKS_COMMERCE_SUMUP_API_KEY=replace-with-your-sk_live-key
WEBBLOCKS_COMMERCE_SUMUP_MERCHANT_CODE=replace-with-your-live-merchant-id
  1. Si se utilizan anulaciones de entorno, actualice la configuración de la aplicación mediante el procedimiento de implementación normal.
  2. Vuelva a verificar Configuración comercial.
  3. Realice una compra real aceptable de bajo valor y verifique el pedido y el pago en ambos sistemas.

Nunca combine una clave de prueba con una identificación de comerciante activa ni reutilice la clave de la zona de pruebas en producción.

Solución de problemas

La configuración de comercio dice "Falta la clave API"

  • Vuelva a ingresar la clave API en el campo de solo escritura y guárdela.
  • Si se muestra una anulación de entorno, verifique su ortografía y confirme que se actualizó la implementación o el proceso PHP.
  • Si la configuración está almacenada en caché, bórrela y reconstrúyala usando el procedimiento de implementación normal.

La configuración de comercio dice listo, pero el pago falla

  • Confirme que la clave y el ID del comerciante pertenecen a la misma cuenta sandbox.
  • Confirme que la clave es la clave API secreta, no la clave pública.
  • Confirmar que el producto está activo, tiene precio positivo y tiene stock disponible.
  • Confirme que la moneda del producto coincida con la moneda admitida por el comerciante.

El cliente pagó, pero el pedido queda pendiente

  • Confirmar que https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup es accesible públicamente mediante POST a través de HTTPS.
  • Compruebe que un firewall, una página de mantenimiento o una contraseña HTTP no estén bloqueando la devolución de llamada.
  • Confirme que la clave API aún puede recuperar el pago y pertenece al comerciante configurado.
  • Confirmar que SumUp informa el pago como PAID con una transacción exitosa.

El pago alojado dice caducado o no encontrado

Comenzar a pagar nuevamente desde el carrito. Las sesiones de pago alojadas caducan después de aproximadamente 30 minutos. no marcar o reutilizar una URL de pago alojada antigua.

Reglas de seguridad

  • Nunca coloque la clave API en un bloque, página, producto, script del navegador, repositorio, captura de pantalla o captura de pantalla de CMS. registro de soporte.
  • Nunca pegue una clave API real en el chat.
  • Mantenga las credenciales activas y de entorno de pruebas separadas.
  • Revoque y reemplace la clave inmediatamente si pudo haber estado expuesta.
  • Trate el estado del pedido del CMS (no la pantalla de éxito del navegador) como la señal de cumplimiento.

Para arquitectura, verificación de webhook, estados de pedidos y solución de problemas avanzada, continúe con la Guía del operador WebBlocks Commerce.

Referencias oficiales de resumen: