SumUp REST API (1.0.0)

Download OpenAPI specification:Download

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

For testing our APIs, please contact us for a test account.

When you receive your test account you can create your client credentials and process different requests with real payment instruments, without charging them.

Authentication

accessToken

At SumUp authentication uses your API credentials and Basic HTTP auth. The API credentials consist of a client_id and client_secret key-value pair.

It is possible to create multiple API credentials for each of the applications you connect with your SumUp account.

Use the API credentials as an authorization header for requests that require such.

Authorization

SumUp uses the OAuth 2.0 authorization framework and supports two authorization flows for obtaining an access token.

The flow you choose will grant your access token specific permissions. All API calls should include the obtained access token in the Authorization: Bearer <<valid_access_token>> format.

To complete successful requests, ensure you have requested the necessary scopes for your authorization flow of choice.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://api.sumup.com/authorize
Token URL: https://api.sumup.com/token
Refresh URL: https://api.sumup.com/token
Scopes:
  • payments -

    Make payments by creating and processing checkouts.

  • transactions.history -

    View transactions and transaction history.

  • user.profile_readonly -

    View user profile details.

  • user.profile -

    View and manage your user profile.

  • user.app-settings -

    View and manage the SumUp mobile application settings.

  • payment_instruments -

    Manage customers and their payment instruments.

  • user.payout-settings -

    View and manage your payout settings.

  • user.subaccounts -

    View and manage the user profile details of your employees.

clientCredentials OAuth Flow
Token URL: https://api.sumup.com/token
Scopes:
  • payments -

    Make payments by creating and processing checkouts.

  • transactions.history -

    View transactions and transaction history.

  • user.profile_readonly -

    View user profile details.

  • user.profile -

    View and manage your user profile.

  • user.app-settings -

    View and manage the SumUp mobile application settings.

  • payment_instruments -

    Manage customers and their payment instruments.

  • user.payout-settings -

    View and manage your payout settings.

  • user.subaccounts -

    View and manage the user profile details of your employee.

Authorization

Retrieve access tokens to grant your application access to specific resources or generate refresh tokens for expired access tokens.

Request authorization from users

Request authorization from users and grant your application access to resources associated with the user's account.

query Parameters
response_type
string
Example: response_type=code

The type of the expected response. The value must be code to indicate that you expect to receive an authorization code.

client_id
string
Example: client_id=fOcmczrYtYMJ7Li5GjMLLcUeC9dN

The client ID of your application that was generated when you registered it.

redirect_uri
string
Example: redirect_uri=https://sample-app.example.com/callback

The URI to which the merchant user is redirected after authorizing your application to access their user's account data and to which the authorization code is sent. The value must match exactly one of the registered URIs for your application.

scope
string
Example: scope=payments

A space-separated list of scopes for which you request authorization. If you don't specify any scopes in the request, your application will be granted authorization for the default scopes.

state
string
Example: state=2cFCsY36y95lFHk4

A unique local state that can be used for correlating requests and responses and for preventing cross-site request forgery.

Responses

200

No Content

get /authorize
https://api.sumup.com/authorize

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Generate a token

Generate a token or a refresh token

Request Body schema: application/json
grant_type
required
string
Enum: "authorization_code" "refresh_token"

The grant type used for obtaining an access token.

client_id
required
string

The client ID of your application that was generated when you registered it.

client_secret
required
string

The client secret of your application that was generated when you registered it.

code
required
string

The authorization code that you received from requesting an authorization code.

refresh_token
string

A required parameter when generating a refresh token.

Responses

200

OK

400

Bad Request

post /token
https://api.sumup.com/token

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "grant_type": "refresh_token",
  • "client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
  • "client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
  • "code": "be366ce9fccd0c337d1da29b31d06dd1135ab95401562883",
  • "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"
}

Response samples

Content type
application/json
Example
access_token

Successfully created access token

Copy
 Expand all Collapse all
{
  • "access_token": "565e2d19cef68203170ddadb952141326d14e03f4ccbd46daa079c26c910a864",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"
}

Checkouts

Accept payments from your end users by adding the Checkouts model to your platform. SumUp supports standard and single payment 3DS checkout flows.

The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a checkout and then processing the checkout.

Get available payment methods

Get payment methods available for the given merchant to use with a checkout.

Authorizations:
accessToken (payments)
path Parameters
merchant_code
required
string
Example: M1234

The SumUp merchant code.

query Parameters
amount
integer
Example: amount=10000

The amount for which the payment methods should be eligible, in minor units. Note that currency must also be provided when filtering by amount.

currency
string
Example: currency=EUR

The currency for which the payment methods should be eligible.

merchant_country_code
string
Example: merchant_country_code=DE

The merchant country code (ISO-3166 alpha-2) for which the payment methods should be eligble.

customer_country_code
string
Example: customer_country_code=DE

The customer country code (ISO-3166 alpha-2) for which the payment methods should be eligble

Responses

200

Available payment methods

400

Bad Request

401

Unauthorized

get /merchants/{merchant_code}/available-payment-methods

Production server

https://api.sumup.com/v0.1/merchants/{merchant_code}/available-payment-methods

Response samples

Content type
application/json

Available payment methods

Copy
 Expand all Collapse all
{
  • "available_payment_methods":
    [
    ]
}

Create a checkout

Creates a new payment checkout resource. The unique checkout_reference created by this request, is used for further manipulation of the checkout.

For 3DS checkouts, add the redirect_url parameter to your request body schema.

Follow by processing a checkout to charge the provided payment instrument.

Authorizations:
accessToken (payments)
Request Body schema: application/json
checkout_reference
required
string <= 90 characters

Unique ID of the payment checkout specified by the client application when creating the checkout resource.

amount
required
number <float>

Amount of the payment.

currency
required
string (Currency)
Enum: "BGN" "BRL" "CHF" "CLP" "CZK" "DKK" "EUR" "GBP" "HRK" "HUF" "NOK" "PLN" "RON" "SEK" "USD"

Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

merchant_code
required
string

Unique identifying code of the merchant profile.

pay_to_email
string <email>

Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

description
string

Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.

return_url
string <uri>

URL to which the SumUp platform sends the processing status of the payment checkout.

customer_id
string

Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced customer.

redirect_url
string

Required for 3DS checkouts. Refers to a url where the end user is redirected once the payment processing completes.

payment_type
string

Alternative payment method name

personal_details
object

Object containing personal details about the payer, typical for Boleto checkouts

Responses

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

409

Conflict

post /checkouts

Production server

https://api.sumup.com/v0.1/checkouts

Request samples

Content type
application/json
Example
Checkout

Standard request body for creating a checkout

Copy
 Expand all Collapse all
{
  • "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  • "amount": 10.1,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "MDUDGLR9",
  • "description": "Purchase",
  • "id": "2b79757a-de87-4a2e-90e4-b17c947c730d",
  • "status": "PAID",
  • "date": "2020-02-29T10:56:56+00:00",
  • "merchant_name": "John Doe LTD",
  • "redirect_url": "https://sumup.com"
}

Response samples

Content type
application/json
Example
Checkout

Standard response body for a successfully created checkout

Copy
 Expand all Collapse all
{
  • "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  • "amount": 10.1,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "MCNPLE22",
  • "description": "My Checkout",
  • "return_url": "http://example.com",
  • "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  • "status": "PENDING",
  • "date": "2020-02-29T10:56:56+00:00",
  • "valid_until": "2020-02-29T10:56:56+00:00",
  • "customer_id": "831ff8d4cd5958ab5670",
  • "mandate":
    {
    },
  • "transactions":
    [
    ]
}

List checkouts

Lists created checkout resources according to the applied checkout_reference.

Authorizations:
accessToken (payments)
query Parameters
checkout_reference
string

Filters the list of checkout resources by the unique ID of the checkout.

Responses

200

OK

401

Unauthorized

get /checkouts

Production server

https://api.sumup.com/v0.1/checkouts

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Retrieve a checkout

Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.

Authorizations:
accessToken (payments)
path Parameters
id
required
string

Unique ID of the checkout resource.

Responses

200

OK

401

Unauthorized

404

Not Found

get /checkouts/{id}

Production server

https://api.sumup.com/v0.1/checkouts/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  • "amount": 10.1,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "MH4H92C7",
  • "description": "Purchase",
  • "return_url": "http://example.com",
  • "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  • "status": "PENDING",
  • "date": "2020-02-29T10:56:56+00:00",
  • "valid_until": "2020-02-29T10:56:56+00:00",
  • "customer_id": "831ff8d4cd5958ab5670",
  • "mandate":
    {
    },
  • "transactions":
    [
    ],
  • "transaction_code": "TEENSK4W2K",
  • "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  • "merchant_name": "Sample Merchant",
  • "redirect_url": "https://mysite.com/completed_purchase",
  • "payment_instrument":
    {
    }
}

Process a checkout