Intégration API SumUp
Nous développons votre connecteur SumUp
Nous connectons votre logiciel à l'API SumUp pour encaisser en caisse et à distance, piloter un lecteur Solo et rapprocher chaque ticket à la commande.
- Équipe produit senior
- intégrations de paiement en production
- du cadrage au monitoring
À quoi sert l'API SumUp et pourquoi l'intégrer dans un logiciel de caisse ou de gestion ?
SumUp est un terminal de paiement et une solution d'encaissement en ligne utilisés par des centaines de milliers de commerçants et prestataires. Son API permet à votre application de créer un lien de paiement, de piloter le lecteur de carte à distance et de connecter les comptes de vos clients SumUp. On l'intègre quand la vente se conclut en présence du client : sur le terrain, en boutique ou à domicile, et que l'encaissement doit automatiquement mettre à jour le dossier dans le logiciel métier, sans que le vendeur saisisse le montant une deuxième fois dans un autre outil.
Ce que nos clients construisent sur l'API SumUp
Caisse web qui pilote le terminal
Le poste déclenche l'encaissement sur un Solo via Cloud API. Le ticket se rattache à la commande, sans application mobile intermédiaire.
Intervention payée sur place
Dépannage, installation, livraison : le bon se clôt à la confirmation du paiement, pas à la saisie d'un montant dans deux outils.
Acompte à distance, solde au comptoir
Checkout hébergé pour l'acompte, terminal pour le solde, même compte marchand, les deux flux dans le même référentiel client.
Réseau multi-établissements
Chaque marchand connecte son propre compte SumUp. Vous n'avez pas ses clés : vous encaissez dans son périmètre.
Ce que ça change dans votre caisse
La technique au service d'un résultat mesurable : plus d'écart de caisse, un ticket rattaché, moins de double saisie.
Fini la double saisie
Le montant part du logiciel métier vers le terminal. L'écart de caisse né d'une ressaisie disparaît du planning de fin de journée.
Le terminal ne dépend plus d'un téléphone
Le poste web pilote le lecteur à distance. Plus besoin de l'appareil personnel de qui est présent ce jour-là.
En ligne et en présence, même compte
Acompte par lien et solde au comptoir retombent dans le même historique. Le rapprochement cesse d'être deux exports.
Un écart vu le jour même
Chaque encaissement est relu et lettré. Vous voyez l'écart le soir, pas au moment de la clôture mensuelle.
Comment nous livrons votre connecteur SumUp
Cadrage
Cloud API ou SDK, en ligne ou présence, OAuth multi-marchand. On tranche le chemin d'intégration avant le premier prototype.
Développement
Connecteur typé, webhook traité comme un signal, relecture du checkout, verrou métier faute d'idempotence documentée.
Recette
Encaissement terminal, checkout hébergé, 402 et 424, panne plus longue que la fenêtre de 2 heures des retentatives.
Monitoring
Alertes sur checkout non terminal, journal des encaissements, tableau de bord de santé. Vous savez qu'un flux est cassé avant vos clients.
Ce que permet l'API SumUp
- Checkout en ligne
- POST /v0.1/checkouts puis relecture de l'état. Checkout hébergé ou widget carte, le statut final se lit sur la ressource, pas sur le webhook.
- Cloud API lecteurs
- Déclenchement d'un encaissement sur Solo ou Go par HTTPS. Webhooks de statut et multi-lecteurs n'existent que sur ce chemin.
- OAuth multi-marchand
- Chaque client connecte son compte. Les scopes payments et payment_instruments exigent une validation manuelle SumUp, à caler dans le calendrier.
- Erreurs lisibles
- RFC 9457 sur les API récentes, plus 402 (requête valide non aboutie) et 424 (dépendance amont). Les confondre produit le mauvais message utilisateur.
Le vocabulaire de l'API SumUp
- CHECKOUT_STATUS_CHANGED
- Seul type d'événement documenté à ce jour. La charge utile tient en un event_type et un id. De nouveaux types peuvent arriver sans préavis : on les ignore, on n'explose pas.
- Cloud API
- Chemin HTTPS vers les lecteurs Solo et Go. Seul ce chemin donne les webhooks de statut de transaction et la gestion de plusieurs lecteurs sur un compte.
- checkout_reference
- Référence marchand unique posée à la création. C'est la clé métier que nous dérivons de la commande, faute d'en-tête d'idempotence documenté.
- 402 Request Failed
- La requête était bien formée mais n'a pas abouti. Distinct du 400 (contrat) et du 424 (dépendance amont). Le message utilisateur n'est pas le même.
- Scope payments
- Créer et traiter des encaissements en OAuth. Avec payment_instruments, il est soumis à vérification manuelle SumUp : un délai à poser au cadrage, pas la veille de la prod.
- Clé d'affiliation
- Troisième secret, obligatoire en présence pour attribuer les transactions à votre intégration. Distinct de la clé d'API et du jeton OAuth.
Les contraintes réelles de l'API SumUp
Le webhook n'est qu'un signal API
SumUp l'écrit : après réception, il faut vérifier que l'événement a eu lieu en appelant l'API. Aucune signature n'est documentée sur la page webhooks publique. La relecture est la protection.
Retentatives bornées à 2 heures
1 minute, 5 minutes, 20 minutes, 2 heures. Une panne de nuit fait perdre la notification. Un balayage des checkouts non terminaux n'est pas une option, c'est une obligation.
Cloud API et SDK ne se valent pas
Webhooks et multi-lecteurs : Cloud API seulement. Transactions hors ligne : SDK seulement. Le choix se fait au début du projet et se paie cher s'il est revu.
Le lecteur se verrouille au pays
Au premier paiement, le lecteur est lié au pays du compte marchand. Un parc mutualisé ou un déploiement multi-pays se conçoit autour de cette contrainte, pas après.
Cloud API ou SDK lecteurs ?
Deux façons de piloter un terminal. Le bon choix dépend des capacités dont vous ne pourrez plus vous passer.
| Critère | Cloud APIHTTPS vers le lecteur | SDK lecteursApp mobile, Bluetooth |
|---|---|---|
| Déclenchement | Requête HTTPS depuis votre serveur | Application Android ou iOS près du lecteur |
| Webhooks de statut | Oui | Non |
| Plusieurs lecteurs | Oui, sur le même compte | Non |
| Hors ligne | Non | Oui |
| Tap to Pay | Hors de ce chemin | Oui, sur iPhone via le SDK |
| Dépendance matérielle | Le lecteur, pas le téléphone du salarié | Un appareil mobile apparié |
| Le bon cas | Caisse web, borne, multi-postes | Tournée, hors réseau, Tap to Pay |
Le tableau officiel des capacités est tranché au cadrage. Revenir sur ce choix plus tard, c'est reprendre le connecteur, pas ajouter une option.
Ce que nous mesurons sur une intégration SumUp
Les autres API de paiement
Si SumUp n'est pas le bon choix pour votre modèle, ces options se discutent au cadrage.
SumUpNous développons votre connecteur SumUpCette page
StripeL'encaissement en ligne le plus complet, quand vous n'avez pas de terminal en présence.
PayPalUn moyen que l'acheteur possède déjà, souvent en complément du terminal.
GoCardlessLe prélèvement SEPA récurrent, pour l'abonnement plutôt que le passage en caisse.
MollieNous développons votre connecteur MollieOn combine SumUp avec
La stack qui entoure SumUp sur nos projets.
Intégration SumUp : vos questions
Trois étapes. D'abord choisir le chemin d'intégration : Cloud API si vous pilotez le terminal depuis un poste web et que vous avez besoin des webhooks, SDK si vous devez encaisser hors ligne. Ensuite créer le checkout ou déclencher le lecteur, avec une checkout_reference dérivée de la commande, parce qu'aucun en-tête d'idempotence n'est documenté. Enfin traiter CHECKOUT_STATUS_CHANGED comme un signal : relire GET /v0.1/checkouts/{id} et décider sur la réponse API. La partie sensible n'est pas l'appel, c'est le filet de rattrapage : les retentatives s'arrêtent à 2 heures.
Un premier flux utile, typiquement déclencher un Solo depuis la caisse et rattacher le ticket, se livre en deux à trois semaines. Une chaîne complète avec checkout distant, OAuth multi-marchand et rapprochement quotidien demande plutôt six à huit semaines, surtout si les scopes payments doivent passer la validation manuelle SumUp. Nous cadrons le périmètre en amont et donnons une estimation ferme avant de commencer.
Le tableau officiel des capacités tranche plus vite qu'un prototype. Cloud API donne les webhooks de statut et la gestion de plusieurs lecteurs, et se pilote depuis un serveur : c'est le bon choix pour une caisse web ou une borne. Les SDK (Android, iOS, Bluetooth, Tap to Pay) donnent les transactions hors ligne, et rien de tout cela. Les deux ne se combinent pas à la carte. On documente les capacités perdues au cadrage, pour que le choix soit une décision tracée et non l'effet de bord du premier essai.
En ne faisant jamais confiance à la charge utile. Elle contient un type et un identifiant. SumUp demande de vérifier que l'événement a eu lieu en appelant l'API. Nous persistons le signal, relisons le checkout, et ne passons la commande en payé que sur l'état API. Les types inconnus s'acquittent en 2xx : de nouveaux événements peuvent arriver sans préavis. Sans signature documentée sur la page webhooks publique, cette relecture est aussi la seule protection réellement opposable. Un job balaie les checkouts non terminaux au-delà de la fenêtre de 2 heures.
Oui. Nous poussons chaque encaissement (présence et ligne) avec la référence de commande vers Odoo, Pennylane ou votre logiciel comptable, puis un contrôle de cohérence périodique signale l'écart plutôt que de le corriger en silence. Le cas fréquent est l'artisan qui encaisse un acompte par lien et le solde au comptoir : les deux doivent retomber sur la même pièce. Une écriture de caisse ne se répare pas dans le dos du comptable.
Un projet d'intégration SumUp ?
Parlons-en. 30 minutes pour cadrer caisse et terminal, vérifier ce que l'API permet vraiment et vous dire franchement ce qui est faisable.
Parler de mon projet SumUp