API integration for SumUp
We build your SumUp connector
We connect your software to the SumUp API to take payment at the till and remotely, drive a Solo reader and match every ticket to the order.
- Senior product team
- payment integrations in production
- from scoping to monitoring
What does the SumUp API provide and why integrate it into a cash register or management software?
SumUp is a payment terminal and online checkout solution used by hundreds of thousands of merchants and service providers. Its API lets your application create a payment link, remotely control the card reader, and connect the accounts of your SumUp clients. You integrate it when the sale closes in the customer's presence: in the field, in a shop or at home, and the payment must automatically update the file in the business software, without the seller entering the amount a second time in another tool.
What our clients build on the SumUp API
Web till that drives the terminal
The station triggers collection on a Solo via Cloud API. The ticket is attached to the order, with no mobile app in between.
On-site job paid on the spot
Repair, install, delivery: the work order closes on payment confirmation, not on an amount typed into two tools.
Remote deposit, balance at the counter
Hosted checkout for the deposit, terminal for the balance, same merchant account, both flows in the same customer record.
Multi-site network
Each merchant connects their own SumUp account. You do not hold their keys: you collect inside their perimeter.
What it changes at the till
Engineering in service of a measurable outcome: no till gap, a ticket attached, less double entry.
No more double entry
The amount goes from the business software to the terminal. The till gap born of retyping leaves the end-of-day schedule.
The terminal no longer depends on a phone
The web station drives the reader remotely. No more relying on whoever's personal device is on shift.
Online and in person, same account
A deposit by link and a balance at the counter land in the same history. Reconciliation stops being two exports.
A gap seen the same day
Each collection is reread and matched. You see the gap that evening, not at month-end close.
How we ship your SumUp connector
Scoping
Cloud API or SDK, online or in person, multi-merchant OAuth. We settle the integration path before the first prototype.
Development
Typed connector, webhook treated as a signal, checkout re-read, business lock because no documented idempotency.
Acceptance testing
Terminal collection, hosted checkout, 402 and 424, an outage longer than the 2-hour retry window.
Monitoring
Alerts on non-terminal checkouts, a collection log, a health dashboard. You know a flow is broken before your customers do.
What the SumUp API allows
- Online checkout
- POST /v0.1/checkouts then re-read state. Hosted checkout or card widget, final status is read from the resource, not from the webhook.
- Readers Cloud API
- Trigger a collection on Solo or Go over HTTPS. Transaction-status webhooks and multi-reader management exist only on this path.
- Multi-merchant OAuth
- Each customer connects their account. The payments and payment_instruments scopes need a manual SumUp review, to be scheduled at scoping.
- Readable errors
- RFC 9457 on newer APIs, plus 402 (valid request that did not complete) and 424 (upstream dependency). Mixing them produces the wrong user message.
The vocabulary of the SumUp API
- CHECKOUT_STATUS_CHANGED
- The only event type documented today. The payload is an event_type and an id. New types may arrive without notice: ignore them, do not throw.
- Cloud API
- HTTPS path to Solo and Go readers. Only this path gives transaction-status webhooks and managing several readers on one account.
- checkout_reference
- Unique merchant reference set at creation. It is the business key we derive from the order, because no idempotency header is documented.
- 402 Request Failed
- The request was well formed but did not complete. Distinct from 400 (contract) and 424 (upstream dependency). The user message is not the same.
- payments scope
- Create and process collections under OAuth. With payment_instruments, it needs a manual SumUp review: a delay to put in the plan, not the night before go-live.
- Affiliate key
- A third secret, required in person to attribute transactions to your integration. Distinct from the API key and the OAuth token.
The real constraints of the SumUp API
The webhook is only a signal
SumUp writes it: after receipt, you must check the event really took place by calling the API. No signature is documented on the public webhooks page. Re-reading is the protection.
Retries stop after 2 hours
1 minute, 5 minutes, 20 minutes, 2 hours. A night outage drops the notification. Sweeping non-terminal checkouts is not optional, it is required.
Cloud API and SDK are not equivalent
Webhooks and multi-reader: Cloud API only. Offline transactions: SDK only. The choice is made at the start of the project and is expensive to reverse.
The reader locks to a country
On the first payment, the reader is bound to the merchant account's country. A shared fleet or a multi-country rollout is designed around that constraint, not after.
Cloud API or reader SDKs?
Two ways to drive a terminal. The right choice depends on the capabilities you will not be able to do without.
| Criterion | Cloud APIHTTPS to the reader | Reader SDKsMobile app, Bluetooth |
|---|---|---|
| Trigger | HTTPS request from your server | Android or iOS app next to the reader |
| Status webhooks | Yes | No |
| Several readers | Yes, on the same account | No |
| Offline | No | Yes |
| Tap to Pay | Not on this path | Yes, on iPhone via the SDK |
| Hardware dependency | The reader, not the employee's phone | A paired mobile device |
| The right case | Web till, kiosk, multi-station | Field work, offline, Tap to Pay |
The official capability table is settled at scoping. Reversing this choice later means rebuilding the connector, not adding an option.
What we measure on a SumUp integration
The other payment APIs
If SumUp is not the right fit for your model, these options are worth discussing during scoping.
SumUpWe build your SumUp connectorThis page
StripeThe most complete online collection, when you have no in-person terminal.
PayPalA method the buyer already has, often alongside the terminal.
GoCardlessRecurring SEPA Direct Debit, for the subscription rather than the till.
MollieWe build your Mollie connectorWe combine SumUp with
The stack that surrounds SumUp on our projects.
SumUp integration: your questions
Three steps. First choose the integration path: Cloud API if you drive the terminal from a web station and need webhooks, SDK if you must collect offline. Then create the checkout or trigger the reader, with a checkout_reference derived from the order, because no idempotency header is documented. Finally treat CHECKOUT_STATUS_CHANGED as a signal: re-read GET /v0.1/checkouts/{id} and decide on the API response. The sensitive part is not the call, it is the catch-up net: retries stop after 2 hours.
A first useful flow, typically triggering a Solo from the till and attaching the ticket, ships in two to three weeks. A full chain with remote checkout, multi-merchant OAuth and daily reconciliation is closer to six to eight weeks, especially if the payments and payment_instruments scopes must pass SumUp's manual review. That review is a project delay, not a last-minute surprise. We scope the perimeter up front and give a firm estimate before we start.
The official capability table settles it faster than a prototype. Cloud API gives status webhooks and multi-reader management, and is driven from a server: the right choice for a web till or a kiosk. The SDKs (Android, iOS, Bluetooth, Tap to Pay) give offline transactions, and none of the rest. The two do not mix and match. We document the capabilities you give up at scoping, so the choice is a recorded decision, not a side effect of the first trial.
By never trusting the payload. It holds a type and an identifier. SumUp asks you to check the event really took place by calling the API. We persist the signal, re-read the checkout, and only mark the order paid on API state. Unknown types are acknowledged with 2xx: new events may arrive without notice. With no signature documented on the public webhooks page, that re-read is also the only protection you can actually stand on. A job sweeps non-terminal checkouts beyond the 2-hour window.
Yes. We push each collection (in person and online) with the order reference into Odoo, Pennylane or your accounting software, then a periodic consistency check flags the gap rather than silently fixing it. The common case is a tradesperson who takes a deposit by link and the balance at the counter: both must land on the same document. A till entry is not repaired behind the accountant's back. The catch-up job on non-terminal checkouts is what keeps the books aligned after a night outage.
A SumUp integration project?
Let's talk. 30 minutes to scope till and terminal, check what the API actually allows and tell you honestly what is feasible.
Discuss my SumUp project