SumUp REST API (1.0.0)

Download OpenAPI specification:Download

E-mail: integration@sumup.com

Authentication

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

View and manage payment checkouts.

Create a checkout

Creates a new payment checkout resource.

Authorizations:
accessToken (payments)
Request Body schema: application/json
checkout_reference
required
string

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" "HRK" "HUF" "NOK" "PLN" "RON" "SEK" "USD"

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

pay_to_email
required
string <email>

Email address of the registered user (merchant) to whom the payment is made.

pay_from_email
string <email>

Email address of the registered user (merchant) who is making the payment.

description
string

Short description of the payment.

return_url
string <uri>

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

Responses

201

Created

400

Bad Request

401

Unauthorized

409

Conflict

post /checkouts
Production server
https://api.sumup.com/v0.1/checkouts

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "pay_from_email": "user@example.com",
  • "description": "string",
  • "return_url": "http://example.com"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "pay_from_email": "user@example.com",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2019-05-14T08:57:23Z",
  • "valid_until": "2019-05-14T08:57:23Z",
  • "transactions":
    [
    ]
}

List checkouts

Lists checkout resources according to specified criteria.

Authorizations:
accessToken (payments)
query Parameters
checkout_reference
string

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

client_transaction_id
string

Filters the list of checkout resources by client transaction ID. When you use this option, you also need to specify the merchant code in the merchant_code query parameter.

merchant_code
string

Filters the list of checkout resources by merchant code. This parameter is required when you are using the client_transaction_id query parameter for filtering the results.

Responses

200

OK

401

Unauthorized

get /checkouts
Production server
https://api.sumup.com/v0.1/checkouts

Response samples

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

Retrieve a checkout

Retrieves 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

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

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "pay_from_email": "user@example.com",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2019-05-14T08:57:23Z",
  • "valid_until": "2019-05-14T08:57:23Z",
  • "transactions":
    [
    ]
}

Process a checkout

Processes an identified checkout resource with the specified payment instrument and create a transaction.

Authorizations:
accessToken (payments)
path Parameters
id
required
string

Unique ID of the checkout resource.

Request Body schema: application/json
One of
  • CheckoutProcessCard
  • CheckoutProcessToken
payment_type
required
string
Value:"card"

Type of payment instrument used for processing the checkout.

installments
integer [ 1 .. 12 ]

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

card
required
object (Card)

Details of the payment card.

Responses

200

OK

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

application/json
Copy
 Expand all Collapse all
{
  • "payment_type": "card",
  • "installments": 1,
  • "card":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "pay_from_email": "user@example.com",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2019-05-14T08:57:23Z",
  • "valid_until": "2019-05-14T08:57:23Z",
  • "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

application/json
Copy
 Expand all Collapse all
{
  • "checkout_reference": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "pay_to_email": "user@example.com",
  • "pay_from_email": "user@example.com",
  • "description": "string",
  • "return_url": "http://example.com",
  • "id": "string",
  • "status": "PENDING",
  • "date": "2019-05-14T08:57:23Z",
  • "valid_until": "2019-05-14T08:57:23Z",
  • "transactions":
    [
    ]
}

Customers

View and manage saved customers and their payment instruments.

Create a customer

Creates a new saved customer resource.

Authorizations:
accessToken (payment_instruments)
Request Body schema: application/json
customer_id
required
string (CustomerID)

Unique ID of the customer.

personal_details
object (PersonalDetails)

Personal details for the customer.

Responses

201

Created

401

Unauthorized

403

Forbidden

409

Conflict

post /customers
Production server
https://api.sumup.com/v0.1/customers

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "customer_id": "string",
  • "personal_details":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "customer_id": "string",
  • "personal_details":
    {
    }
}

Retrieve a customer

Retrieves an identified saved customer resource.

Authorizations:
accessToken (payment_instruments)
path Parameters
customer_id
required
string

Unique ID of the saved customer resource.

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get /customers/{customer_id}
Production server
https://api.sumup.com/v0.1/customers/{customer_id}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "customer_id": "string",
  • "personal_details":
    {
    }
}

Update a customer

Updates an identified saved customer resource.

Authorizations:
accessToken (payment_instruments)
path Parameters
customer_id
required
string

Unique ID of the saved customer resource.

Request Body schema: application/json
personal_details
object (PersonalDetails)

Personal details for the customer.

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

put /customers/{customer_id}
Production server
https://api.sumup.com/v0.1/customers/{customer_id}

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "personal_details":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "customer_id": "string",
  • "personal_details":
    {
    }
}

Create a payment instrument

Creates and activates a new payment instrument resource by saving a payment card for an identified customer.

Authorizations:
accessToken (payment_instruments)
path Parameters
customer_id
required
string

Unique ID of the saved customer resource.

Request Body schema: application/json
type
required
string
Value:"card"

Type of the payment instrument.

card
required
object (Card)

Details of the payment card.

Responses

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict

post /customers/{customer_id}/payment-instruments
Production server
https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "type": "card",
  • "card":
    {
    }
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "active": true,
  • "type": "card",
  • "card":
    {
    }
}

List payment instruments

Lists all payment instrument resources that are saved for an identified customer.

Authorizations:
accessToken (payment_instruments)
path Parameters
customer_id
required
string

Unique ID of the saved customer resource.

Responses

200

OK

401

Unauthorized

403

Forbidden

404

Not Found

get /customers/{customer_id}/payment-instruments
Production server
https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments

Response samples

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

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Authorizations:
accessToken (payment_instruments)
path Parameters
customer_id
required
string

Unique ID of the saved customer resource.

token
required
string

Unique token identifying the card saved as a payment instrument resource.

Responses

204

No Content

401

Unauthorized

403

Forbidden

404

Not Found

delete /customers/{customer_id}/payment-instruments/{token}
Production server
https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token}

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Transactions

View transactions.

Retrieve a transaction

Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and one of following parameters is required:

  • id
  • internal_id
  • transaction_code
Authorizations:
accessToken (transactions.history)
query Parameters
id
string

Retrieves the transaction resource with the specified transaction ID (the id parameter in the transaction resource).

internal_id
string

Retrieves the transaction resource with the specified internal transaction ID (the internal_id parameter in the transaction resource).

transaction_code
string

Retrieves the transaction resource with the specified transaction code.

Responses

200

OK

401

Unauthorized

404

Not Found

get /me/transactions
Production server
https://api.sumup.com/v0.1/me/transactions

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "transaction_code": "string",
  • "amount": 0,
  • "currency": "EUR",
  • "timestamp": "2019-05-14T08:57:23Z",
  • "status": "PAID_OUT",
  • "payment_type": "ECOM",
  • "installments_count": 1,
  • "merchant_code": "string",
  • "vat_amount": 0,
  • "tip_amount": 0,
  • "entry_mode": "customer entry",
  • "auth_code": "string",
  • "internal_id": 0,
  • "product_summary": "string",
  • "payouts_total": 0,
  • "payouts_received": 0,
  • "payout_plan": "SINGLE_PAYMENT",
  • "username": "user@example.com",
  • "lat": 0,
  • "lon": 0,
  • "horizontal_accuracy": 0,
  • "simple_payment_type": "MOTO",
  • "verification_method": "none",
  • "card":
    {
    },
  • "local_time": "2019-05-14T08:57:23Z",
  • "payout_type": "BANK_ACCOUNT",
  • "products":
    [
    ],
  • "vat_rates":
    [
    ],
  • "transaction_events":
    [
    ],
  • "simple_status": "SUCCESSFUL",
  • "links":
    [],
  • "events":
    [
    ],
  • "location":
    {
    },
  • "tax_enabled": true
}

List transactions

Lists detailed history of all transactions associated with the merchant account.

Authorizations:
accessToken (transactions.history)
query Parameters
transaction_code
string

Retrieves the transaction resource with the specified transaction code.

order
string
Default: ["ascending"]
Enum:"ascending" "descending"

Specifies the order in which the returned results are displayed.

limit
integer

Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.

user_id
string

Filters the results by user ID and returns only transaction resources associated with the specified user. The user can be identified via one of the following parameters:

  • email
  • masked merchant ID
  • original user ID

If you do not specify user identification, the response contains transaction resources associated with the currently authenticated user account.

users
Array of string <email>

Filters the returned results by user email.

statuses
Array of string
Items Enum:"SUCCESSFUL" "CANCELLED" "FAILED"

Filters the returned results by the specified list of final statuses of the transactions.

payment_types
Array of string
Items Enum:"CASH" "POS" "ECOM" "BITCOIN" "BALANCE"

Filters the returned results by the specified list of payment types used for the transactions.

types
Array of string
Items Enum:"PAYMENT" "REFUND" "CHARGE_BACK"

Filters the returned results by the specified list of transaction types.

changes_since
string <date-time>

Filters the results by the latest modification time of resources and returns only transactions that are modified at or after the specified timestamp (in ISO8601 format).

newest_time
string <date-time>

Filters the results by the creation time of resources and returns only transactions that are created before the specified timestamp (in ISO8601 format).

newest_ref
string

Filters the results by the reference ID of transaciton events and returns only transactions with events whose IDs are smaller than the specified value. This parameters supersedes the newest_time parameter (if both are provided in the request).

oldest_time
string <date-time>

Filters the results by the creation time of resources and returns only transactions that are created at or after the specified timestamp (in ISO8601 format).

oldest_ref
string

Filters the results by the reference ID of transaciton events and returns only transactions with events whose IDs are greater than the specified value. This parameters supersedes the oldest_time parameter (if both are provided in the request).

Responses

200

OK

401

Unauthorized

get /me/transactions/history
Production server
https://api.sumup.com/v0.1/me/transactions/history

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "items":
    [
    ],
  • "links":
    []
}

Payouts

View list of transactions and payouts.

List payouts

Lists ordered payouts for the merchant account.

Authorizations:
accessToken (user.profileuser.profile_readonly)
path Parameters
start_date
required
string <date>

Start date (in ISO8601 format).

end_date
required
string <date>

End date (in ISO8601 format).

format
string
Enum:"json" "csv"
limit
integer
order
string
Enum:"desc" "asc"

Responses

200

OK

401

Unauthorized

get /me/financials/payouts
Production server
https://api.sumup.com/v0.1/me/financials/payouts

Response samples

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

List transactions

Lists a less detailed history of all transactions associated with the merchant account.

Authorizations:
accessToken (user.profileuser.profile_readonly)
path Parameters
start_date
required
string <date>

Start date (in ISO8601 format).

end_date
required
string <date>

End date (in ISO8601 format).

format
string
Enum:"json" "csv"
limit
integer
order
string
Enum:"desc" "asc"

Responses

200

OK

401

Unauthorized

get /me/financials/transactions
Production server
https://api.sumup.com/v0.1/me/financials/transactions

Response samples

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

Refunds

Refund a transaction.

Refund a transaction

Refunds an identified transaction either in full or partially.

Authorizations:
accessToken (payments)
path Parameters
txn_id
required
string

Unique ID of the transaction.

Request Body schema: application/json
amount
number <float>

Amount to refund for this transaction. The value cannot exceed the amount of the transaction. If you do not specify a value, the system performs a full refund of the transaction

Responses

204

No Content

404

Not Found

409

Conflict

post /me/refund/{txn_id}
Production server
https://api.sumup.com/v0.1/me/refund/{txn_id}

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "amount": 0
}

Response samples

application/json
Copy
 Expand all Collapse all
{ }

Receipts

View receipts.

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Authorizations:
accessToken
query Parameters
id
required
any

SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD.

mid
required
any

Merchant code.

tx_event_id
any

The ID of the transaction event (refund).

Responses

200

OK

400

Not Found

401

Unauthorized

get /receipts/:id
https://api.sumup.com/v1.0/receipts/:id

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "transaction_data":
    {