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.
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.
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 |
---|
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:
|
clientCredentials OAuth Flow | Token URL: https://api.sumup.com/token Scopes:
|
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.
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.
payments
) 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 |
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. |
OK
Bad Request
Unauthorized
Forbidden
Conflict
Production server
{- "checkout_reference": "string",
- "amount": 0,
- "currency": "EUR",
- "merchant_code": "string",
- "pay_to_email": "user@example.com",
- "description": "string",
- "customer_id": "string"
}
{- "checkout_reference": "string",
- "amount": 0,
- "currency": "EUR",
- "pay_to_email": "user@example.com",
- "merchant_code": "string",
- "description": "string",
- "id": "string",
- "status": "PENDING",
- "date": "2020-02-29T10:56:56+00:00",
- "valid_until": "2020-02-29T10:56:56+00:00",
- "customer_id": "string",
- "transactions": [
- {
- "id": "string",
- "transaction_code": "string",
- "amount": 0,
- "currency": "EUR",
- "timestamp": "2020-02-29T10:56:56.876Z",
- "status": "SUCCESSFUL",
- "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
}
]
}
Lists created checkout resources according to the applied checkout_reference
.
payments
) checkout_reference | string Filters the list of checkout resources by the unique ID of the checkout. |
OK
Unauthorized
Production server
[- {
- "checkout_reference": "string",
- "amount": 0,
- "currency": "EUR",
- "pay_to_email": "user@example.com",
- "merchant_code": "string",
- "description": "string",
- "id": "string",
- "status": "PENDING",
- "date": "2020-02-29T10:56:56+00:00",
- "valid_until": "2020-02-29T10:56:56+00:00",
- "customer_id": "string",
- "transactions": [
- {
- "id": "string",
- "transaction_code": "string",
- "amount": 0,
- "currency": "EUR",
- "timestamp": "2020-02-29T10:56:56.876Z",
- "status": "SUCCESSFUL",
- "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
}
], - "mandate": {
- "userAgent": "MacOS safari",
- "userIp": "10.33.0.1",
- "type": "recurrent"
}, - "transaction_code": "string",
- "transaction_id": "string"
}
]
Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.
payments
) id required | string Unique ID of the checkout resource. |
OK
Unauthorized
Not Found
Production server
{- "checkout_reference": "string",
- "amount": 0,
- "currency": "EUR",
- "pay_to_email": "user@example.com",
- "merchant_code": "string",
- "description": "string",
- "id": "string",
- "status": "PENDING",
- "date": "2020-02-29T10:56:56+00:00",
- "valid_until": "2020-02-29T10:56:56+00:00",
- "customer_id": "string",
- "transactions": [
- {
- "id": "string",
- "transaction_code": "string",
- "amount": 0,
- "currency": "EUR",
- "timestamp": "2020-02-29T10:56:56.876Z",
- "status": "SUCCESSFUL",
- "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
}
], - "mandate": {
- "userAgent": "MacOS safari",
- "userIp": "10.33.0.1",
- "type": "recurrent"
}, - "transaction_code": "string",
- "transaction_id": "string"
}
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.
payments
) id required | string Unique ID of the checkout resource. |
Details of the payment instrument for processing the checkout.
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 Mandate is passed when a card is to be tokenised. |
card required | object (Card) Details of the payment card. |
OK
Accepted
Bad Request
Unauthorized
Not Found
Conflict
Production server
{- "payment_type": "card",
- "installments": 1,
- "mandate": {
- "userAgent": "MacOS safari",
- "userIp": "10.33.0.1",
- "type": "recurrent"
}, - "card": {
- "name": "FIRSTNAME LASTNAME",
- "number": "1234567890123456",
- "expiry_year": "2023",
- "expiry_month": "01",
- "cvv": "123",
- "zip_code": "12345"
}
}
{- "checkout_reference": "string",
- "amount": 0,
- "currency": "EUR",
- "pay_to_email": "user@example.com",
- "merchant_code": "string",
- "description": "string",
- "id": "string",
- "status": "PENDING",
- "date": "2020-02-29T10:56:56+00:00",
- "valid_until": "2020-02-29T10:56:56+00:00",
- "customer_id": "string",
- "transactions": [
- {
- "id": "string",
- "transaction_code": "string",
- "amount": 0,
- "currency": "EUR",
- "timestamp": "2020-02-29T10:56:56.876Z",
- "status": "SUCCESSFUL",
- "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
}
], - "mandate": {
- "userAgent": "MacOS safari",
- "userIp": "10.33.0.1",
- "type": "recurrent"
}, - "transaction_code": "string",
- "transaction_id": "string"
}
Deactivates an identified checkout resource.
payments
) id required | string Unique ID of the checkout resource. |
OK
Unauthorized
Not Found
Conflict
Production server
{- "checkout_reference": "string",
- "amount": 0,
- "currency": "EUR",
- "pay_to_email": "user@example.com",
- "merchant_code": "string",
- "description": "string",
- "id": "string",
- "status": "PENDING",
- "date": "2020-02-29T10:56:56+00:00",
- "valid_until": "2020-02-29T10:56:56+00:00",
- "customer_id": "string",
- "transactions": [
- {
- "id": "string",
- "transaction_code": "string",
- "amount": 0,
- "currency": "EUR",
- "timestamp": "2020-02-29T10:56:56.876Z",
- "status": "SUCCESSFUL",
- "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
}
]
}