Resumen rápido
- La API REST de SumUp permite trabajar con pagos, checkouts, clientes, transacciones, recibos, payouts y otros recursos.
- Para integrar pagos online puedes usar Hosted Checkout, Payment Widget o la Checkout API, según cuánto quieras personalizar el proceso.
- SumUp ofrece SDK oficiales de servidor para JavaScript/TypeScript, PHP, Python, Java, Go, Rust y .NET.
- Si la integración pertenece únicamente a tu comercio, normalmente utilizarás una API Key. Si otros comercios van a conectar sus cuentas a tu aplicación, entra en juego OAuth 2.0.
- Las integraciones presenciales pueden requerir además una Affiliate Key, que identifica la integración pero no sustituye la autenticación.
- Para controlar un SumUp Solo desde un software propio existe Cloud API.
- Tap to Pay tiene una arquitectura específica: en Android utiliza un SDK separado, mientras que en iOS forma parte del SDK correspondiente.
- Puedes desarrollar y probar primero con un entorno sandbox, sin procesar transacciones reales.
- Si trabajas con WooCommerce, Shopify u otra solución ya compatible, comprueba primero si realmente necesitas desarrollar contra la API.
Qué es la API de SumUp y para qué sirve
Cuando hablamos de la API de SumUp, en realidad estamos hablando de un ecosistema de herramientas para desarrolladores que permite conectar SumUp con sistemas externos.
La plataforma SumUp puede utilizarse sin tocar una sola línea de código, pero la API abre otras posibilidades: crear pagos desde un backend, consultar transacciones, conectar un ecommerce personalizado o hacer que un software de caja envíe una operación a un lector físico.
La clave está en no meter todas esas posibilidades en el mismo saco.
| Si quieres hacer esto | Lo más lógico es investigar |
|---|---|
| Cobrar online con poco desarrollo | Hosted Checkout |
| Insertar el pago dentro de tu web | Payment Widget |
| Controlar el flujo desde tu backend | REST API + SDK |
| Crear una plataforma para varios comercios | OAuth 2.0 |
| Conectar un software con SumUp Solo | Cloud API |
| Cobrar directamente con un móvil compatible | Tap to Pay SDK |
| Usar SumUp con WooCommerce | Integración para WooCommerce |
| Usar SumUp con Shopify | Integración con Shopify |
SumUp utiliza una API REST con intercambio de datos en JSON. Su referencia técnica se encuentra dentro de SumUp Developer y utiliza como URL base https://api.sumup.com.
Documentación oficial de SumUp Developer
Consejo práctico: decide primero qué experiencia quieres ofrecer al cliente. Después elige la herramienta. Empezar directamente por los endpoints suele complicar un proyecto que podría resolverse con bastante menos código.
Cómo empezar con la API de SumUp
Antes de crear el primer checkout necesitas preparar dos cosas: un entorno de pruebas y la autenticación adecuada.
SumUp permite crear un merchant sandbox para desarrollar y probar operaciones sin afectar a los datos normales ni procesar dinero real. Es el entorno que deberías utilizar mientras construyes la integración.
No pruebes directamente sobre producción solo porque el primer ejemplo de código parece sencillo. Los problemas importantes suelen aparecer precisamente en pagos rechazados, reintentos, estados pendientes o callbacks duplicados.
API Key, OAuth y Affiliate Key: no sirven para lo mismo
Esta distinción merece entenderse antes de programar.
| Credencial | Cuándo encaja |
|---|---|
| API Key | Tu servidor accede directamente a tu propia cuenta SumUp |
| OAuth 2.0 | Otros comercios conectan sus cuentas SumUp a tu aplicación |
| Affiliate Key | Identifica determinadas integraciones de pagos presenciales |
Una API Key secreta da acceso a la cuenta que la ha generado. Debe vivir exclusivamente en el servidor o en un gestor seguro de secretos.
Nunca la incrustes en:
- JavaScript que se ejecuta en el navegador.
- Una aplicación distribuida sin una arquitectura segura.
- Un repositorio público.
- Un ejemplo de GitHub.
- Un archivo que termine accidentalmente en control de versiones.
SumUp recomienda OAuth cuando construyes una plataforma que deben autorizar otros merchants. Además, los permisos se controlan mediante scopes, por lo que conviene solicitar solamente los que realmente necesita la aplicación.
La Affiliate Key, por su parte, no autentica las llamadas a la API. Se utiliza en determinadas integraciones presenciales para identificar de dónde procede la operación y debe combinarse con el mecanismo de autorización correspondiente.
Qué puedes hacer con la REST API de SumUp
La API no se limita a “cobrar una tarjeta”. Hay distintas familias de recursos que permiten construir flujos bastante más completos.
Entre otras posibilidades, un desarrollo puede:
- Crear y consultar checkouts.
- Recuperar información sobre operaciones.
- Consultar transacciones.
- Trabajar con clientes e instrumentos guardados cuando el flujo lo permita.
- Consultar payouts.
- Recuperar datos relacionados con recibos.
- Gestionar determinadas operaciones sobre lectores compatibles.
- Procesar reembolsos mediante los mecanismos disponibles.
La referencia REST de SumUp es la que debes utilizar cuando necesites parámetros, respuestas, códigos HTTP y schemas concretos. Para una primera integración, sin embargo, intentar aprender todos los endpoints antes de decidir el flujo suele ser contraproducente.
La documentación debe funcionar como referencia técnica; tu arquitectura debe empezar por la necesidad del negocio.
SumUp Checkout API: cómo funciona un pago online
La Checkout API es una de las partes más importantes para quien quiere integrar pagos online con SumUp.
Un checkout representa un intento de pago. Al crearlo defines información como:
- referencia interna del pedido;
- importe;
- moneda;
- merchant que recibirá el pago;
- descripción;
- callback, cuando corresponda.
Hay una distinción importante: crear el checkout no significa haber cobrado al cliente. El checkout se crea primero y después debe completarse mediante el flujo de pago correspondiente.
Ejemplo: crear un checkout de 25 €
Imagina que tienes un ecommerce y el pedido PEDIDO-1001 asciende a 25 €.
Una petición simplificada podría tener esta forma:
curl --request POST 'https://api.sumup.com/v0.1/checkouts'
--header 'Authorization: Bearer '"$SUMUP_API_KEY"
--header 'Content-Type: application/json'
--data '{
"checkout_reference": "PEDIDO-1001",
"amount": 25.00,
"currency": "EUR",
"merchant_code": "TU_MERCHANT_CODE",
"description": "Pedido 1001",
"return_url": "https://tu-dominio.es/webhooks/sumup",
"hosted_checkout": {
"enabled": true
}
}'Los valores anteriores son un ejemplo hipotético. La API Key, el merchant code y la URL deben sustituirse por los datos correspondientes a tu proyecto.
Al habilitar Hosted Checkout, el flujo puede devolver una URL alojada por SumUp a la que redirigir al cliente para completar el pago.
Esta arquitectura tiene una ventaja importante: reduces la cantidad de lógica sensible relacionada con la captura de datos de pago que tiene que gestionar tu propia aplicación.
Hosted Checkout o Payment Widget
No existe una opción universalmente mejor.
Hosted Checkout tiene más sentido cuando quieres reducir la complejidad: creas el checkout y el usuario completa el pago en una página alojada por SumUp.
Payment Widget encaja mejor cuando quieres que el formulario forme parte visualmente de tu propia web.
Si tu objetivo es simplemente aceptar pagos online, revisa primero ambas alternativas antes de desarrollar una experiencia de checkout completamente personalizada.
SDK de SumUp: qué opciones tienes
No es obligatorio escribir manualmente todas las peticiones HTTP.
SumUp mantiene SDK de servidor que abstraen parte del trabajo habitual de autenticación y acceso a los recursos de la API.
Entre las opciones documentadas están:
| Lenguaje | SDK |
|---|---|
| JavaScript / TypeScript | @sumup/sdk |
| PHP | sumup/sumup-php |
| Python | sumup-py |
| Java | SDK Java de SumUp |
| Go | sumup-go |
| Rust | crate sumup |
| .NET | paquete SumUp |
También existe una herramienta CLI para interactuar con las APIs desde terminal.
Si buscas código fuente, ejemplos o paquetes mantenidos por el propio proveedor, conviene utilizar el GitHub oficial de SumUp y no repositorios de terceros que podrían estar abandonados.
Ejemplo de SumUp API con PHP
La intención sumup api php tiene sentido dentro de esta misma guía porque PHP sigue siendo habitual en ecommerce, WordPress y aplicaciones de negocio.
El SDK oficial puede instalarse mediante Composer:
composer require sumup/sumup-phpUna implementación simplificada para crear el checkout anterior podría partir de algo similar a esto:
<?php
require 'vendor/autoload.php';
use SumUpSumUp;
$sumup = new SumUp();
$checkout = $sumup->checkouts->create([
'merchant_code' => getenv('SUMUP_MERCHANT_CODE'),
'amount' => 25.00,
'currency' => 'EUR',
'checkout_reference' => 'PEDIDO-1001',
'description' => 'Pedido 1001',
]);
echo $checkout->id;La clave debería estar almacenada en una variable de entorno como SUMUP_API_KEY, no escrita directamente dentro del archivo PHP.
El ejemplo sirve para entender el flujo, pero una aplicación real necesita además gestionar excepciones, estados del pago, logs, reintentos y respuestas inesperadas.
Error común: confundir “he podido crear el checkout” con “el cliente ya ha pagado”. Son dos estados completamente diferentes.
Webhooks de SumUp: cómo enterarte de que cambia un pago
Consultar continuamente la API preguntando si un checkout ha cambiado de estado sería poco eficiente.
Para los checkouts online, SumUp documenta notificaciones mediante una return_url. Cuando se produce un cambio relevante, el servidor puede recibir una petición HTTP POST con información del evento.
El flujo correcto es, simplificando:
- Tu servidor crea un checkout.
- Incluyes una
return_url. - SumUp envía una notificación cuando cambia el estado.
- Tu endpoint responde rápidamente con un código
2xx. - Tu servidor consulta después la API de SumUp para comprobar el estado real.
- Solo entonces actualizas el pedido en tu sistema.
Este último punto es especialmente importante.
Recibir el webhook no significa que debas marcar automáticamente el pedido como pagado. La propia documentación de SumUp indica que la aplicación debe verificar posteriormente el evento consultando la API.
Documentación oficial de webhooks de SumUp
Qué ocurre si tu servidor no responde
Las notificaciones pueden volver a enviarse cuando el endpoint no responde correctamente. Eso significa que tu código debe estar preparado para recibir un mismo evento más de una vez.
Aquí aparece otro concepto importante: idempotencia.
Imagina que recibes dos veces la notificación correspondiente al mismo checkout de 25 €. Tu aplicación no debería:
- generar dos pedidos;
- enviar dos veces el producto;
- contabilizar dos ventas;
- ejecutar dos procesos internos idénticos.
Antes de actuar, comprueba si ese pago ya ha sido procesado por tu sistema.
Cloud API: conectar SumUp Solo con tu propio software
Hasta aquí hemos hablado principalmente de pagos online. Pero una empresa también puede querer controlar un terminal físico desde su propio software.
Ahí entra Cloud API.
La integración permite conectar un sistema propio con un lector SumUp Solo y lanzar operaciones de pago desde el backend. SumUp también ofrece una modalidad Virtual Solo para probar determinados flujos sin disponer del lector físico.
Ejemplo práctico: un restaurante con TPV propio
Imagina un restaurante que utiliza un software desarrollado internamente.
Una mesa tiene que pagar 37,50 €.
En lugar de que el camarero escriba manualmente 37,50 € en el datáfono:
- El TPV calcula la cuenta.
- El backend inicia el checkout correspondiente.
- La operación llega al Solo asociado.
- El cliente paga en el terminal.
- El software recibe y comprueba el resultado.
- La mesa se cierra solamente cuando la operación ha terminado correctamente.
Es una integración muy diferente de un checkout web.
Cloud API no es “la API para cobrar online con un Solo”. Es una arquitectura para conectar un sistema con determinados lectores físicos compatibles.
También requiere prestar atención a la Affiliate Key y al método de autorización adecuado.
Tap to Pay SDK: cobrar directamente desde el móvil
Otra posibilidad es convertir un dispositivo compatible en terminal de cobro sin utilizar un lector físico independiente.
Puedes profundizar en el funcionamiento comercial, dispositivos y uso diario en nuestra guía de Tap to Pay de SumUp. Desde el punto de vista del desarrollo, lo importante es entender que no debe tratarse como si fuera simplemente otro endpoint de Checkout.
En Android, SumUp utiliza un SDK específico para Tap to Pay, separado del SDK destinado a lectores Bluetooth. En iOS, Tap to Pay on iPhone está integrado dentro del SDK de iOS.
Eso tiene consecuencias prácticas.
Antes de plantear la arquitectura debes comprobar:
- sistema operativo;
- compatibilidad del dispositivo;
- requisitos de seguridad;
- autenticación;
- permisos requeridos;
- disponibilidad para el mercado donde operará el negocio.
No fijaría una arquitectura a partir de una lista antigua de versiones de iOS o Android. En este tipo de integración es preferible consultar los requisitos técnicos oficiales durante el desarrollo.
Ejemplos de integraciones que puedes construir con SumUp
La mejor forma de entender el ecosistema es verlo mediante proyectos concretos.
Ecommerce desarrollado a medida
Si tienes una tienda completamente personalizada, puedes crear los checkouts desde tu backend y utilizar Hosted Checkout o Payment Widget para completar el pago.
Tiene sentido cuando necesitas controlar pedidos, referencias, inventario o lógica de negocio desde tus propios sistemas.
SaaS que conecta las cuentas SumUp de sus clientes
Imagina un software para centros de belleza o restaurantes que permite a cientos de negocios conectar su propia cuenta.
No sería razonable pedirles que te entregasen sus API Keys.
Ese es precisamente uno de los escenarios en los que OAuth 2.0 tiene sentido: cada merchant autoriza a tu aplicación y tú trabajas únicamente con los permisos concedidos.
Software de caja conectado con un terminal
Si tienes un POS propio y quieres que el importe llegue al lector sin introducirlo manualmente, Cloud API puede ser la vía a estudiar.
El software genera la operación; el terminal se ocupa del pago presencial.
App móvil con pagos presenciales
Dependiendo del dispositivo y del flujo, puedes estudiar:
- SDK para lectores;
- Tap to Pay;
- herramientas específicas de iOS;
- SDK específico de Tap to Pay en Android.
No deberías escoger el SDK solo por el lenguaje de la app. Primero decide qué hardware y experiencia de cobro necesitas.
Cuándo no merece la pena integrar directamente la API
Este es uno de los puntos que más dinero y horas de desarrollo puede ahorrarte.
Tener una API disponible no significa que debas utilizarla.
Si tu negocio funciona sobre una plataforma ya conocida, comprueba primero si existe una solución preparada. Por ejemplo, puedes revisar las opciones para integrar SumUp con WooCommerce o las posibilidades de usar SumUp con Shopify.
Lo mismo ocurre fuera del checkout. Si lo que buscas es conectar operaciones con tu contabilidad, resulta más lógico estudiar primero la integración entre SumUp y Xero que diseñar desde cero un conector contable completo.
Para necesidades todavía más sencillas, el desarrollo puede ser innecesario.
| Necesidad | Antes de crear una integración propia, valora |
|---|---|
| Cobrar a un cliente a distancia | Enlaces de pago de SumUp |
| Crear un ecommerce básico | Tienda online de SumUp |
| WooCommerce | Plugin/integración disponible |
| Shopify | Opciones de integración existentes |
| Checkout web personalizado | API / SDK |
| SaaS para múltiples comercios | API + OAuth |
| POS propio con terminal | Cloud API |
Consejo experto: no compares únicamente el coste inicial del desarrollo. Una integración propia también implica mantenimiento, cambios de API, control de errores, seguridad, pruebas y soporte cuando algo falla.
A veces la solución con menos código es también la mejor solución técnica.
Errores frecuentes al integrar la API de SumUp
Una API de pagos exige bastante más cuidado que una integración con un servicio de contenido convencional.
Estos son los errores que evitaríamos desde el principio.
1. Poner la API Key en el frontend
Una credencial secreta nunca debería viajar dentro del JavaScript público de una web.
Guárdala en el servidor y utiliza variables de entorno o un gestor de secretos.
2. Subir las credenciales a GitHub
Un .env incluido accidentalmente en el repositorio puede comprometer la cuenta.
Añádelo al .gitignore y utiliza secretos diferentes para desarrollo, pruebas y producción cuando la arquitectura lo permita.
3. Marcar el pedido como pagado tras una redirección
Que el usuario vuelva a /pedido-completado no demuestra por sí solo que el dinero se haya cobrado.
Comprueba el checkout desde el servidor.
4. Confiar ciegamente en el webhook
El webhook sirve para avisarte de que debes revisar algo.
No debería convertirse en una orden ciega de “entregar pedido”.
5. Procesar dos veces una notificación repetida
Diseña la lógica para poder recibir el mismo evento varias veces sin provocar duplicados.
6. Confundir Affiliate Key y API Key
La primera puede identificar una integración presencial.
La segunda autoriza llamadas a la API para una cuenta concreta.
No son sustitutas.
7. Utilizar API Keys de clientes en una plataforma multiusuario
Si estás construyendo una solución que conectarán otros negocios, estudia OAuth en lugar de almacenar secretos que pertenecen a cada merchant.
8. Desarrollar directamente en producción
Utiliza sandbox para simular tanto el camino feliz como los fallos.
No pruebes solo un pago correcto. Prueba también:
- rechazo;
- cancelación;
- checkout pendiente;
- callback duplicado;
- respuesta lenta de tu servidor;
- pérdida temporal de conexión;
- datos inesperados.
9. Enviar datos de tarjeta por tu servidor sin necesidad
Para la mayoría de integraciones web resulta más sensato utilizar las soluciones de checkout proporcionadas por SumUp que asumir directamente el tratamiento de datos de tarjeta.
La gestión directa de esa información introduce obligaciones y riesgos de seguridad adicionales, incluido el marco PCI DSS.
10. No registrar correctamente lo que ocurre
Cuando un cliente diga “he pagado pero el pedido no aparece”, necesitarás reconstruir la operación.
Guarda identificadores útiles como:
- referencia propia del pedido;
- checkout ID;
- estado consultado;
- identificador de la transacción cuando exista;
- momento de cada cambio.
Eso sí: logs útiles no significa logs llenos de información sensible.
Qué revisar antes de poner la integración en producción
Antes de procesar pagos reales, haríamos como mínimo esta comprobación:
- La integración ha sido probada en sandbox.
- Cada intento de pago utiliza una referencia inequívoca.
- Las claves secretas solo existen del lado servidor.
- Los permisos OAuth son los mínimos necesarios.
- El sistema verifica el estado del checkout desde la API.
- Los callbacks pueden recibirse varias veces sin duplicar pedidos.
- Se han probado operaciones rechazadas y canceladas.
- Los logs permiten investigar errores sin guardar información sensible.
- Los SDK y dependencias utilizados proceden de fuentes oficiales.
- La compatibilidad del hardware se ha comprobado para la integración elegida.
- Los errores de red no dejan pedidos en un estado incoherente.
- Producción utiliza sus propias credenciales y configuración.
Si estás desarrollando para un negocio real, esta parte importa bastante más que conseguir que el primer pago de prueba funcione.
¿API, SDK, Cloud API o integración preparada? Nuestra recomendación
La forma más sencilla de decidir es pensar en el problema antes que en la tecnología.
Si quieres cobrar online rápidamente, empezaría estudiando Hosted Checkout.
Si quieres el pago integrado visualmente en tu web, revisaría Payment Widget.
Si tu backend necesita controlar el proceso y consultar recursos, utilizaría la API directamente o uno de los SDK oficiales.
Si estás construyendo una plataforma que conectarán otros comercios, diseñaría la autorización alrededor de OAuth.
Si tienes un POS propio que debe enviar importes a un terminal, estudiaría Cloud API y SumUp Solo.
Si quieres que un móvil compatible actúe como terminal, revisaría la integración específica de Tap to Pay.
Y si utilizas un ecommerce o software que ya dispone de integración, no desarrollaría una API personalizada hasta demostrar que realmente hace falta.
Ese último punto suele olvidarse. La mejor integración no es la que tiene más código, sino la que resuelve el problema con seguridad, mantenimiento razonable y la menor complejidad necesaria.
Conclusión
La API de SumUp ofrece suficientes opciones para ir desde un checkout sencillo hasta una plataforma SaaS, una aplicación móvil o un POS conectado con un terminal. Precisamente por eso, el primer trabajo no debería ser escribir código: debería ser elegir bien la arquitectura.
Para un comercio pequeño puede bastar Hosted Checkout, un enlace de pago o una integración preparada. Una plataforma que conecta varios negocios probablemente necesitará OAuth. Un software de caja puede tener sentido con Cloud API. Y una app orientada al cobro presencial tendrá que estudiar los SDK y Tap to Pay.
Una vez tengas clara la parte técnica, conviene revisar también los precios y comisiones de SumUp. Que una integración sea técnicamente viable no significa automáticamente que sea la opción más adecuada para el volumen y modelo de negocio que tienes.
