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.

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

Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the Create a checkout endpoint.

Follow this request with Retrieve a checkout to confirm its status.

path Parameters
id
required
string

Unique ID of the checkout resource.

Request Body schema: application/json

Details of the payment instrument for processing the checkout.

payment_type
required
string
Enum: "card" "token" "boleto" "ideal" "sofort" "bancontact"
installments
integer [ 1 .. 12 ]

Number of installments for deferred payments. Available only to merchant users in Brazil.

mandate
object (MandatePayload)

Mandate is passed when a card is to be tokenised

card
object (Card)

Required when payment type is card. Details of the payment card.

token
string

Required when the payment type is token. Unique token identifying the saved payment card for a customer.

customer_id
string

Required when the payment type is token. Unique ID of the customer.

Responses

200

OK

202

Accepted

400

Bad Request

401

Unauthorized

404

Not Found

409

Conflict

put /checkouts/{id}

Production server

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

Request samples

Content type
application/json
Example
ProcessCard

Process a checkout with a card

Copy
 Expand all Collapse all
{
  • "payment_type": "card"