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

Overview

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

accessToken

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.

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
One of
  • CheckoutCreateRequest
  • Checkout3DS
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: "EUR" "BGN" "CHF" "CZK" "DKK" "GBP" "HUF" "NOK" "PLN" "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.

Responses

201

OK

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
CheckoutCreateRequest
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "merchant_code": "string",
  • "pay_to_email": "user@example.com",
  • "description": "string",
  • "return_url": "http://example.com",
  • "customer_id": "string"
}

Response samples

Content type
application/json
Example
Checkout
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "string",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2020-02-29T10:56:56+00:00",
  • "valid_until": "2020-02-29T10:56:56+00:00",
  • "customer_id": "string",
  • "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": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "string",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2020-02-29T10:56:56+00:00",
  • "valid_until": "2020-02-29T10:56:56+00:00",
  • "customer_id": "string",
  • "mandate":
    {
    },
  • "transactions":
    [
    ],
  • "transaction_code": "string",
  • "transaction_id": "string"
}

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.

One of
  • CheckoutProcessCard
  • CheckoutProcessToken
payment_type
required
string
Value: "card"
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
required
object (Card)

Details of the payment card.

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
CheckoutProcessCard
Copy
 Expand all Collapse all
{
  • "payment_type": "card",
  • "installments": 1,
  • "mandate":
    {
    },
  • "card":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "string",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2020-02-29T10:56:56+00:00",
  • "valid_until": "2020-02-29T10:56:56+00:00",
  • "customer_id": "string",
  • "mandate":
    {
    },
  • "transactions":
    [
    ],
  • "transaction_code": "string",
  • "transaction_id": "string"
}

Deactivate a checkout

Deactivates an identified checkout resource.

Authorizations:
accessToken (payments)
path Parameters
id
required
string

Unique ID of the checkout resource.

Responses

200

OK

401

Unauthorized

404

Not Found

409

Conflict

delete /checkouts/{id}

Production server

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

Response samples

Content type
application/json
Example
Checkout
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "merchant_code": "string",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2020-02-29T10:56:56+00:00",
  • "valid_until": "2020-02-29T10:56:56+00:00",
  • "customer_id": "string",
  • "mandate":
    {
    },
  • "transactions":
    [