Getting started
API Overview
SumUp provides REST API for most of its services like creating and executing payments, storing cards for future payments, issuing refunds among others. Our API uses OAuth 2.0 authorization standards to authenticate applications access to its services. We also support Cross-origin resource sharing (CORS) allowing web browsers securely to consume our API from a different domain origin.
The API receives requests and communicates responses in JSON format. The API also supports the standard protocol content type - application/x-www-form-urlencoded.
Typically, the requests are data objects consisting of name/value pairs sent to the SumUp API URI: api.sumup.com
Error handling
SumUp uses predefined error codes for success and failures.
Retuned codes in the 2xx range indicate success. Returned codes in the 4xx range indicate errors where the information provided results in a failure, for example trying to create a checkout with an already existing reference. Returned codes in the 5xx range are rare and indicate server-side errors. Responses that come with a failure code would consists of a response code and a message that describes the failure reason. Successful responses will contain the success code plus a data object containg name/value pairs specific to the requested API call request, for example the ID of a created checkout.
Receive payments
In order to receive payments, you need to create a checkout. Whether you would like to receive payments as a merchant directly, or initiate payments on a merchant's behalf depends on the type of authorization provided.
Checkouts are created in a server-to-server communication. This ensures that you can keep your access token and client credentials secret and guarantees that sensitive checkout details, e.g. amount or recepient, cannot be changed.
Completing checkouts could be done via your web browser or mobile application, which guarantees you do not need to worry about sensitive data, like card data, ever hitting your servers and thus avoiding the need to be PCI DSS compliant.
A checkout can be completed in a browser only from a domain that is present as an authorized JavaScript origin when creating your client credentials.
SumUp provides flexibility to complete a checkout by offering three different card integration approaches:
- You could build a custom card form that you must submit to the SumUp servers for processing
- You could use the SumUp card widget
- You could use a previously created card token linked to a customer to execute the payment
Once you complete the checkout, you would have processed a payment successfully to a merchant’s SumUp account.