API Reference | SumUp Developer

SumUp’s REST API operates with JSON HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard HTTP response codes.

You can experiment and work on your integration in a sandbox that doesn't affect your regular data and doesn't process real transactions. To create a sandbox merchant account visit the dashboard. To use the sandbox when interacting with SumUp APIs create an API key and use it for authentication.

View YAML spec View JSON spec

1
https://api.sumup.com

SDKs

The SumUp SDKs reduce the amount of work required to use our REST APIs. SumUp maintains SDKs for PHP, Node.js, Python, Java, Go, Rust, and .NET.

SDKs

1
# Select a client library to see installation instructions.

1
npm install --save @sumup/sdk

1
go get github.com/sumup/sumup-go

1
// Maven
2
<dependency>
3
  <groupId>com.sumup</groupId>
4
  <artifactId>sumup-sdk</artifactId>
5
  <version>0.0.6</version>
6
</dependency>
7

8
// Gradle
9
implementation "com.sumup:sumup-sdk:0.0.6"

1
dotnet add package SumUp

1
pip install sumup
2
# or
3
uv add sumup

1
composer require sumup/sumup-php

1
cargo add sumup

You can also explore our APIs in Postman using SumUp Developers public collection.

Authentication

The SumUp API uses API keys to authenticate requests. You can view, create, and manage your API keys in the Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Keep your API keys secret and safe. Do not share your API keys or expose them in a publicly accessible areas such as client-side code (browser or apps) or in the GitHub.

All API requests must be made over HTTPS and authenticated. Calls made over plain HTTP or calls without authentication will fail.

1
curl https://api.sumup.com/v0.1/checkouts \
2
  -H "Authorization: Bearer sup_sk_MvxmLOl0..."

1
import { SumUp } from '@sumup/sdk';
2

3
const sumup = new SumUp({ apiKey: 'sup_sk_MvxmLOl0...' });

1
package main
2

3
import (
4
  "github.com/sumup/sumup-go/client"
5
  sumup "github.com/sumup/sumup-go"
6
)
7

8
func main() {
9
  client := sumup.NewClient(client.WithAPIKey("sup_sk_MvxmLOl0..."))
10
}

1
SumUpClient client =
2
    SumUpClient.builder()
3
        .accessToken("sup_sk_MvxmLOl0...")
4
        .build();

1
using SumUp;
2

3
var client = new SumUpClient(new SumUpClientOptions
4
{
5
    AccessToken = "sup_sk_MvxmLOl0...",
6
});

1
from sumup import Sumup
2

3
client = SumUp(api_key="sup_sk_MvxmLOl0...")

1
$sumup = new \SumUp\SumUp("sup_sk_MvxmLOl0...");

1
use sumup::Client;
2

3
let client = Client::default().with_authorization("sup_sk_MvxmLOl0...");

Errors

Newer APIs use Problem Details (RFC 9457) for error responses.

Some APIs support both application/problem+json and application/json for backwards compatibility.

If you do not use our SDKs, send the header Accept: application/problem+json, application/json to ensure you receive the newer Problem Details error format.

Status	Type	When it is returned
`200`	OK	The request finished successfully.
`400`	Bad Request	The payload is invalid, incomplete, or does not match the API contract.
`401`	Unauthorized	Authentication is missing or the provided API key is invalid.
`402`	Request Failed	The request format is valid, but it could not be completed.
`403`	Forbidden	The authenticated key does not have permission for this operation.
`404`	Not Found	The requested endpoint or resource could not be located.
`409`	Conflict	The request collides with the current resource state.
`422`	Unprocessable Entity	The payload is syntactically valid, but semantic validation failed.
`424`	External Dependency Failed	A required upstream service failed, so the request could not finish.
`429`	Too Many Requests	Rate limits were exceeded. Retry with exponential backoff.
`5XX`	Server Errors	An issue occurred on our side. These failures should be uncommon.

Problem schema

type string required format: uri

A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
title string

A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
status integer

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detail string

A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instance string format: uri

A URI reference that identifies the specific occurrence of the problem.

1
application/problem+json

1
{
2
  "type": "https://developer.sumup.com/problem/not-found",
3
  "title": "Requested resource couldn't be found.",
4
  "status": 404,
5
  "detail": "The requested resource doesn't exist or does not belong to you.",
6
  "instance": null
7
}