SumUp REST API

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 make sure you have a SumUp Profile (you can create one here). To activate your SumUp Profile follow these steps.

Once you have an active SumUp Profile, go to developer.sumup.com and click on “Create” On the top right side, click on “Profile” followed by “Test profiles” Select your business country Click “Create” Copy and store safely the user name (format: 32 [email protected]) and randomly generated unique password.

Note: You will not be able to access your password afterwards make sure to store it safely before dismissing the message

Note: SumUp merchants are able to create up to 20 test profiles

When you receive your test profile you can create your client credentials and process different requests with real payment instruments, without charging them. Legal note: We reserve the right to change, modify, or remove the contents of this Website and SumUp APIs at any time without notice.

Server URL
 https://api.sumup.com 

Authorization

SumUp API uses API keys for authentication. You can view and manage your API keys in the API Keys section of the Developer Portal.

API keys are short static tokens that are passed in the Authorization header to authenticate the requests.

The tokens have a sup_sk_ prefix. Your API keys have access to the whole SumUp API, so make sure to keep them secure.

All requests must be made over HTTPS and must be authenticated.

Alternatively, SumUp APIs support OAuth2 authentication for applications that want to use SumUp as a platform for other users.

Read more about authorization in our Authorization guide.

Authorization

Request authorization from users

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

Query Parameters

response_type string
client_id string
redirect_uri string
scope string
state string

Response 200

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

{}

Authorization

Generate a token

Generate a token or a refresh token

Body Parameters

client_id string required

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

Example: "fOcmczrYtYMJ7Li5GjMLLcUeC9dN"
client_secret string required

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

Example: "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c"
code string required

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

Example: "be366ce9fccd0c337d1da29b31d06dd1135ab95401562883"
grant_type string required

Options: authorization_code refresh_token

The grant type used for obtaining an access token.

Example: "refresh_token"
refresh_token string

A required parameter when generating a refresh token.

Example: "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"

Response 200

access_token string

The access token that you need to use in your requests to the SumUp API.

Example: "ec410d10ad7f06d3c2598473c9cd61189abcc016900a9938068542bcf9754073"
expires_in integer

The validity of the access token in seconds.

Example: 3600
refresh_token string

The refresh token provided in the request call

Example: "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"
scope string

List of authorization scopes granted to your access token.

Example: "payments user.app-settings transactions.history user.profile_readonly"
token_type string

The type of the token. The value is always Bearer.

Example: "Bearer"

error_code string

Platform code for the error.
message string

Short description of the error.

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

Successfully created access token

{
  "access_token": "565e2d19cef68203170ddadb952141326d14e03f4ccbd46daa079c26c910a864",
  "expires_in": 3600,
  "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
  "token_type": "Bearer"
}

Successfully created access token with the refresh token

{
  "access_token": "ec410d10ad7f06d3c2598473c9cd61189abcc016900a9938068542bcf9754073",
  "expires_in": 3600,
  "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
  "scope": "payments user.app-settings transactions.history user.profile_readonly",
  "token_type": "Bearer"
}

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.

The Checkout object

Details of the payment checkout.

Attributes

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

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

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

Example: "EUR"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object

Created mandate
Show attributes
Close

Attributes
- merchant_code string
  
  Merchant code which has the mandate
- status string
  
  Mandate status
- type string
  
  Indicates the mandate type
Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

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

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

The Checkout object
 {
  "amount": 10.1,
  "checkout_reference": null,
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": null,
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": null,
  "pay_to_email": null,
  "return_url": null,
  "status": null,
  "transactions": [
    {
      "amount": 10.1,
      "currency": "EUR",
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "installments_count": null,
      "payment_type": null,
      "status": null,
      "timestamp": "2020-02-29T10:56:56.876Z",
      "transaction_code": "TEENSK4W2K",
      "auth_code": "053201",
      "entry_mode": null,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "tip_amount": 3,
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
} 

Checkouts

List checkouts

Lists created checkout resources according to the applied checkout_reference.

Scopes: payments

Query Parameters

checkout_reference string

Response 200

[]object

Show attributes

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

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

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

Example: "EUR"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object

Created mandate
Show attributes
Close

Attributes
- merchant_code string
  
  Merchant code which has the mandate
- status string
  
  Mandate status
- type string
  
  Indicates the mandate type
Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

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

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"
merchant_name string

Name of the merchant

Example: "Sample Merchant"
payment_instrument object

Object containing token information for the specified payment instrument
Show attributes
Close

Attributes
- token string
  
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
redirect_url string

Refers to a url where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
transaction_code string

Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_id string

Transaction ID of the successful transaction with which the payment for the checkout is completed.

Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"

error_code string

Platform code for the error.
message string

Short description of the error.

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

List checkouts response
 [
  {
    "amount": 10.1,
    "checkout_reference": null,
    "currency": "EUR",
    "customer_id": "831ff8d4cd5958ab5670",
    "date": "2020-02-29T10:56:56+00:00",
    "description": null,
    "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
    "mandate": {
      "merchant_code": "MDASYTPD",
      "status": "active",
      "type": "recurrent"
    },
    "merchant_code": null,
    "pay_to_email": null,
    "return_url": null,
    "status": null,
    "transactions": [
      {
        "amount": 10.1,
        "currency": "EUR",
        "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
        "installments_count": null,
        "payment_type": null,
        "status": null,
        "timestamp": "2020-02-29T10:56:56.876Z",
        "transaction_code": "TEENSK4W2K",
        "auth_code": "053201",
        "entry_mode": null,
        "internal_id": 1763892018,
        "merchant_code": "MH4H92C7",
        "tip_amount": 3,
        "vat_amount": 6
      }
    ],
    "valid_until": "2020-02-29T10:56:56+00:00",
    "merchant_name": "Sample Merchant",
    "payment_instrument": {
      "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
    },
    "redirect_url": "https://mysite.com/completed_purchase",
    "transaction_code": "TEENSK4W2K",
    "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
  }
] 

Checkouts

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.

Scopes: payments

Body Parameters

amount number required

Amount of the payment.
checkout_reference string required

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

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

Example: "EUR"
customer_id string

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

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.
merchant_code string required

Unique identifying code of the merchant profile.
pay_to_email string

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.
payment_type string

Alternative payment method name

Example: "boleto"
personal_details object

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

Attributes
- address object
  
  Payer's address information
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  Payer's city
  
  Example: "Rio de Janeiro"
  
  country string
  
  Payer's country
  
  Example: "BR"
  
  line_1 string
  
  Field for address details
  
  postal_code string
  
  Payer's postal code. Must be eight digits long, however an optional dash could be applied after the 5th digit (more information about the format available here). Both options are accepted as correct.
  
  Example: "20000-000"
  
  state string
  
  Options: AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO
  
  Payer's state code
  
  Example: "RJ"
- email string
  
  Payer's email address
  
  Example: "[email protected]"
- first_name string
  
  Payer's first name
  
  Example: "John"
- last_name string
  
  Payer's last name
  
  Example: "Doe"
- tax_id string
  
  Payer's tax identification number (CPF)
  
  Example: "423.378.593-47"
purpose string

Options: CHECKOUT SETUP_RECURRING_PAYMENT

Purpose of the checkout.
redirect_url string

Required for APMs and recommended for card payments. Refers to a url where the end user is redirected once the payment processing completes. If not specified, the Payment Widget renders 3DS challenge within an iframe instead of performing a full-page redirect.

Example: "https://mysite.com/completed_purchase"
return_url string

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

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

Response 201

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

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

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

Example: "EUR"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object

Created mandate
Show attributes
Close

Attributes
- merchant_code string
  
  Merchant code which has the mandate
- status string
  
  Mandate status
- type string
  
  Indicates the mandate type
Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

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

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

error_code string

Platform code for the error.
message string

Short description of the error.
param string

Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, card.name refers to the name parameter embedded in the card object.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

Standard response body for a successfully created checkout

{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "pay_to_email": "[email protected]",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

Response body for a successfully created 3DS checkout

{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "pay_to_email": "[email protected]",
  "redirect_url": "https://mysite.com/completed_purchase",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

Response body for APMs, including Blik, iDeal, ...

{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "date": "2021-06-29T11:08:36.000+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "merchant_name": "My company",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "redirect_url": "https://sumup.com",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ]
}

Checkouts

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.

Scopes: payments

Path Parameters

id string required

Response 200

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

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

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

Example: "EUR"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object

Created mandate
Show attributes
Close

Attributes
- merchant_code string
  
  Merchant code which has the mandate
- status string
  
  Mandate status
- type string
  
  Indicates the mandate type
Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

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

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"
merchant_name string

Name of the merchant

Example: "Sample Merchant"
payment_instrument object

Object containing token information for the specified payment instrument
Show attributes
Close

Attributes
- token string
  
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
redirect_url string

Refers to a url where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
transaction_code string

Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_id string

Transaction ID of the successful transaction with which the payment for the checkout is completed.

Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

Retrieve a checkout response
 {
  "amount": 10.1,
  "checkout_reference": null,
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": null,
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": null,
  "pay_to_email": null,
  "return_url": null,
  "status": null,
  "transactions": [
    {
      "amount": 10.1,
      "currency": "EUR",
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "installments_count": null,
      "payment_type": null,
      "status": null,
      "timestamp": "2020-02-29T10:56:56.876Z",
      "transaction_code": "TEENSK4W2K",
      "auth_code": "053201",
      "entry_mode": null,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "tip_amount": 3,
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00",
  "merchant_name": "Sample Merchant",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "redirect_url": "https://mysite.com/completed_purchase",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
} 

Checkouts

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 string required

Body Parameters

card object

Required when payment type is card. Details of the payment card.
Show attributes
Close

Attributes
- cvv string required
  
  Three or four-digit card verification value (security code) of the payment card.
  
  Example: "123"
- expiry_month string required
  
  Options: 01 02 03 04 05 06 07 08 09 10 11 12
  
  Month from the expiration time of the payment card. Accepted format is MM.
- expiry_year string required
  
  Year from the expiration time of the payment card. Accepted formats are YY and YYYY.
  
  Example: "2023"
- last_4_digits string required
  
  Last 4 digits of the payment card number.
  
  Example: "3456"
- name string required
  
  Name of the cardholder as it appears on the payment card.
  
  Example: "FIRSTNAME LASTNAME"
- number string required
  
  Number of the payment card (without spaces).
  
  Example: "1234567890123456"
- type string required
  
  Options: AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card.
- zip_code string
  
  Required five-digit ZIP code. Applicable only to merchant users in the USA.
  
  Example: "12345"
customer_id string

Required when token is provided. Unique ID of the customer.
installments integer

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
Show attributes
Close

Attributes
- type string required
  
  Options: recurrent
  
  Indicates the mandate type
- user_agent string required
  
  Operating system and web client used by the end-user
- user_ip string
  
  IP address of the end user. Supports IPv4 and IPv6
Example: {"type":"recurrent","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36","user_ip":"172.217.169.174"}
payment_type string required

Options: card boleto ideal blik bancontact
token string

Required when using a tokenized card to process a checkout. Unique token identifying the saved payment card for a customer.

Response 200

amount number

Amount of the payment.

Example: 10.1
checkout_reference string

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

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

Example: "EUR"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object

Created mandate
Show attributes
Close

Attributes
- merchant_code string
  
  Merchant code which has the mandate
- status string
  
  Mandate status
- type string
  
  Indicates the mandate type
Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
merchant_code string

Unique identifying code of the merchant profile.
pay_to_email string

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

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

Options: PENDING FAILED PAID

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"
merchant_name string

Name of the merchant

Example: "Sample Merchant"
payment_instrument object

Object containing token information for the specified payment instrument
Show attributes
Close

Attributes
- token string
  
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
redirect_url string

Refers to a url where the end user is redirected once the payment processing completes.

Example: "https://mysite.com/completed_purchase"
transaction_code string

Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_id string

Transaction ID of the successful transaction with which the payment for the checkout is completed.

Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

Successfully processed checkout with Bancontact

{
  "next_step": {
    "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
      "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB",
      "tx": "624788471"
    },
    "url": "https://r3.girogate.de/ti/simbcmc"
  }
}

Successfully processed checkout with Boleto

{
  "amount": 10.1,
  "boleto": {
    "barcode": "34191090081790614310603072340007886840000000200",
    "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto"
  },
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "BRL",
  "date": "2021-07-06T12:34:02.000+00:00",
  "description": "Boleto checkout",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample shop",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "redirect_url": "https://website.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "currency": "BRL",
      "entry_mode": "BOLETO",
      "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C9",
      "payment_type": "BOLETO",
      "status": "PENDING",
      "timestamp": "2021-07-06T12:34:16.460+00:00",
      "tip_amount": 3,
      "transaction_code": "TEN3E696NP",
      "vat_amount": 6
    }
  ]
}

Successfully processed checkout with a card

{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MH4H92C7",
  "pay_to_email": "[email protected]",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "053201",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

Successfully processed checkout with a token

{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase with token",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample Merchant",
  "pay_to_email": "[email protected]",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "redirect_url": "https://mysite.com/completed_purchase",
  "status": "PENDING",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "053201",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ]
}

Successfully processed checkout with iDeal

{
  "next_step": {
    "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
      "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz",
      "tx": "961473700"
    },
    "url": "https://r3.girogate.de/ti/simideal"
  }
}

Checkouts

Deactivate a checkout

Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.

Scopes: payments

Path Parameters

id string required

Response 200

amount number

Amount of the payment.
checkout_reference string

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

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

Example: "EUR"
date string

Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56+00:00"
description string

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

Unique ID of the checkout resource.
merchant_code string

Unique identifying code of the merchant profile.
merchant_country string

The merchant's country
merchant_name string

Merchant name
pay_to_email string

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.
purpose string

Options: SETUP_RECURRING_PAYMENT CHECKOUT

Purpose of the checkout creation initially
status string

Options: EXPIRED

Current status of the checkout.
transactions []object

List of transactions related to the payment.
Show attributes
Close

Attributes
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- installments_count integer
  
  Current number of the installment for deferred payments.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- timestamp string
  
  Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.
  
  Example: "2020-02-29T10:56:56.876Z"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- auth_code string
  
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
- entry_mode string
  
  Options: CUSTOMER_ENTRY BOLETO
  
  Entry mode of the payment details.
- internal_id integer
  
  Internal unique ID of the transaction on the SumUp platform.
  
  Example: 1763892018
- merchant_code string
  
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- tip_amount number
  
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- vat_amount number
  
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
valid_until string

Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

Example: "2020-02-29T10:56:56+00:00"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

Response body for a successfully deactivated checkout

{
  "amount": 2,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Deletion example",
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample Merchant",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "status": "EXPIRED",
  "transactions": [],
  "valid_until": "2020-02-29T10:56:56+00:00"
}

Checkouts

Get available payment methods

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

Scopes: payments

Path Parameters

merchant_code string required

Example: M1234

Query Parameters

amount number

Example: 9.99
currency string

Example: EUR

Response 200

available_payment_methods []object
Show attributes
Close

Attributes
- id string required
  
  The ID of the payment method.
  
  Example: "qr_code_pix"

details string

Details of the error.
failed_constraints []object
Show attributes
Close

Attributes
- message string
- reference string
status number

The status code.
title string

Short title of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

Available payment methods

{
  "available_payment_methods": [
    {
      "id": "apple_pay"
    },
    {
      "id": "blik"
    }
  ]
}

Customers

Allow your regular customers to save their information with the Customers model. This will prevent re-entering payment instrument information for recurring payments on your platform.

Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.

The Customer object

Attributes

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string required
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"
- birthdate string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

Create a customer

Creates a new saved customer resource which you can later manipulate and save payment instruments to.

Scopes: payment_instruments

Body Parameters

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string required
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"
- birthdate string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"

Response 201

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string required
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"
- birthdate string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

 post 
 /v0.1/customers  
 curl https://api.sumup.com/v0.1/customers 

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

Retrieve a customer

Retrieves an identified saved customer resource through the unique customer_id parameter, generated upon customer creation.

Scopes: payment_instruments

Path Parameters

customer_id string required

Response 200

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string required
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"
- birthdate string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

Update a customer

Updates an identified saved customer resource's personal details.

The request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.

Scopes: payment_instruments

Path Parameters

customer_id string required

Body Parameters

personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string required
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"
- birthdate string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"

Response 200

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string required
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"
- birthdate string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}

Customers

List payment instruments

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

Scopes: payment_instruments

Path Parameters

customer_id string required

Response 200

[]object

Show attributes

active boolean

Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a DELETE request to the resource endpoint.
card object

Details of the payment card.
Show attributes
Close

Attributes
- last_4_digits string
  
  Last 4 digits of the payment card number.
  
  Example: "3456"
- type string
  
  Options: AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card.
created_at string

Creation date of payment instrument. Response format expressed according to ISO8601 code.
mandate object

Created mandate
Show attributes
Close

Attributes
- merchant_code string
  
  Merchant code which has the mandate
- status string
  
  Mandate status
- type string
  
  Indicates the mandate type
Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
token string

Unique token identifying the saved payment card for a customer.
type string

Options: card

Type of the payment instrument.

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

List payment instruments response
 [
  {
    "active": true,
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00",
    "mandate": {
      "merchant_code": "MDASYTPD",
      "status": "active",
      "type": "recurrent"
    },
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "type": "card"
  }
] 

Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Scopes: payment_instruments

Path Parameters

customer_id string required
token string required

Response 204

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

{}

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Attributes

account object

Profile information.
Show attributes
Close

Attributes
- type string
  
  Options: normal operator
  
  The role of the user.
- username string
  
  Username of the user profile.
app_settings object

Mobile app settings
Show attributes
Close

Attributes
- advanced_mode string
  
  Advanced mode.
- barcode_scanner string
  
  Barcode scanner.
- cash_payment string
  
  Cash payment.
- checkout_preference string
  
  Checkout preference
- expected_max_transaction_amount number
  
  Expected max transaction amount.
- include_vat boolean
  
  Include vat.
- manual_entry string
  
  Manual entry.
- manual_entry_tutorial boolean
  
  Manual entry tutorial.
- mobile_payment string
  
  Mobile payment.
- mobile_payment_tutorial boolean
  
  Mobile payment tutorial.
- reader_payment string
  
  Reader payment.
- referral string
  
  Referral.
- tax_enabled boolean
  
  Tax enabled.
- terminal_mode_tutorial boolean
  
  Terminal mode tutorial.
- tip_rates []number
  
  Tip rates.
  
  Show attributes
  
  Close
  
  Attributes
- tipping string
  
  Tipping.
is_migrated_payleven_br boolean

Merchant comes from payleven BR migration
merchant_profile object

Account's merchant profile
Show attributes
Close

Attributes
- address object
  
  Details of the registered address.
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  company string
  
  undefined
  
  country string
  
  Country ISO 3166-1 code
  
  country_details object
  
  Country Details
  
  Show attributes
  
  Close
  
  Attributes
  
  currency string
  
  Currency ISO 4217 code
  
  en_name string
  
  Country EN name
  
  iso_code string
  
  Country ISO code
  
  native_name string
  
  Country native name
  
  first_name string
  
  undefined
  
  landline string
  
  Landline number
  
  last_name string
  
  undefined
  
  post_code string
  
  Postal code
  
  region_code string
  
  Region code
  
  region_id number
  
  Country region id
  
  region_name string
  
  Region name
  
  state_id string
  
  undefined
  
  timeoffset_details object
  
  TimeOffset Details
  
  Show attributes
  
  Close
  
  Attributes
  
  dst boolean
  
  Daylight Saving Time
  
  offset number
  
  UTC offset
  
  post_code string
  
  Postal code
- bank_accounts []object
  
  Show attributes
  
  Close
  
  Attributes
  
  account_category string
  
  Account category - business or personal
  
  account_holder_name string
  
  account_number string
  
  Account number
  
  account_type string
  
  Type of the account
  
  bank_code string
  
  Bank code
  
  bank_name string
  
  Bank name
  
  branch_code string
  
  Branch code
  
  created_at string
  
  Creation date of the bank account
  
  iban string
  
  IBAN
  
  primary boolean
  
  The primary bank account is the one used for settlements
  
  status string
  
  Status in the verification process
  
  swift string
  
  SWIFT code
- business_owners []object
  
  Business owners information.
- company_name string
  
  Company name
- company_registration_number string
  
  Company registration number
- country string
  
  Merchant country isocode (for internal usage only)
- doing_business_as object
  
  Doing Business As information
  
  Show attributes
  
  Close
  
  Attributes
  
  address object
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  country string
  
  Country ISO 3166-1 code
  
  post_code string
  
  Postal code
  
  region_id number
  
  Country region ID
  
  region_name string
  
  Country region name
  
  business_name string
  
  Doing business as name
  
  company_registration_number string
  
  Doing business as company registration number
  
  email string
  
  Doing business as email
  
  vat_id string
  
  Doing business as VAT ID
  
  website string
  
  Doing business as website
- extdev boolean
  
  True if the merchant is extdev
- legal_type object
  
  Id of the legal type of the merchant profile
  
  Show attributes
  
  Close
  
  Attributes
  
  description string
  
  Legal type short description
  
  full_description string
  
  Legal type description
  
  id number
  
  Unique id
  
  sole_trader boolean
  
  Sole trader legal type if true
- locale string
  
  Merchant locale (for internal usage only)
- merchant_category_code string
  
  Merchant category code
- merchant_code string
  
  Unique identifying code of the merchant profile
- mobile_phone string
  
  Mobile phone number
- nature_and_purpose string
  
  Nature and purpose of the business
- payout_zone_migrated boolean
  
  True if the payout zone of this merchant is migrated
- permanent_certificate_access_code string
  
  Permanent certificate access code (Portugal)
- settings object
  
  Merchant settings (like "payout_type", "payout_period")
  
  Show attributes
  
  Close
  
  Attributes
  
  daily_payout_email boolean
  
  Whether merchant will receive daily payout emails
  
  gross_settlement boolean
  
  Whether merchant has gross settlement enabled
  
  monthly_payout_email boolean
  
  Whether merchant will receive monthly payout emails
  
  moto_payment string
  
  Options: UNAVAILABLE ENFORCED ON OFF
  
  Whether merchant can make MOTO payments
  
  payout_instrument string
  
  Payout Instrument
  
  payout_on_demand boolean
  
  Whether merchant will receive payouts on demand
  
  payout_on_demand_available boolean
  
  Whether merchant can edit payouts on demand
  
  payout_period string
  
  Payout frequency
  
  payout_type string
  
  Payout type
  
  printers_enabled boolean
  
  Whether to show printers in mobile app
  
  stone_merchant_code string
  
  Stone merchant code
  
  tax_enabled boolean
  
  Whether to show tax in receipts (saved per transaction)
- vat_id string
  
  Vat ID
- vat_rates object
  
  Merchant VAT rates
  
  Show attributes
  
  Close
  
  Attributes
  
  country string
  
  Country ISO code
  
  description string
  
  Description
  
  id number
  
  Internal ID
  
  ordering number
  
  Ordering
  
  rate number
  
  Rate
- website string
  
  Website
permissions object

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- create_referral boolean
  
  Create referral
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
personal_profile object

Account's personal profile.
Show attributes
Close

Attributes
- address object
  
  Details of the registered address.
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  company string
  
  undefined
  
  country string
  
  Country ISO 3166-1 code
  
  country_details object
  
  Country Details
  
  Show attributes
  
  Close
  
  Attributes
  
  currency string
  
  Currency ISO 4217 code
  
  en_name string
  
  Country EN name
  
  iso_code string
  
  Country ISO code
  
  native_name string
  
  Country native name
  
  first_name string
  
  undefined
  
  landline string
  
  Landline number
  
  last_name string
  
  undefined
  
  post_code string
  
  Postal code
  
  region_code string
  
  Region code
  
  region_id number
  
  Country region id
  
  region_name string
  
  Region name
  
  state_id string
  
  undefined
  
  timeoffset_details object
  
  TimeOffset Details
  
  Show attributes
  
  Close
  
  Attributes
  
  dst boolean
  
  Daylight Saving Time
  
  offset number
  
  UTC offset
  
  post_code string
  
  Postal code
- complete boolean
- date_of_birth string
  
  Date of birth
- first_name string
  
  First name of the user
- last_name string
  
  Last name of the user
- mobile_phone string
  
  Mobile phone number

The Merchant Account object
 {
  "account": {
    "type": null,
    "username": null
  },
  "app_settings": {
    "advanced_mode": null,
    "barcode_scanner": null,
    "cash_payment": null,
    "checkout_preference": null,
    "expected_max_transaction_amount": null,
    "include_vat": null,
    "manual_entry": null,
    "manual_entry_tutorial": null,
    "mobile_payment": null,
    "mobile_payment_tutorial": null,
    "reader_payment": null,
    "referral": null,
    "tax_enabled": null,
    "terminal_mode_tutorial": null,
    "tip_rates": [
      null
    ],
    "tipping": null
  },
  "is_migrated_payleven_br": null,
  "merchant_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "bank_accounts": [
      {
        "account_category": null,
        "account_holder_name": null,
        "account_number": null,
        "account_type": null,
        "bank_code": null,
        "bank_name": null,
        "branch_code": null,
        "created_at": null,
        "iban": null,
        "primary": null,
        "status": null,
        "swift": null
      }
    ],
    "business_owners": [
      {
        "date_of_birth": null,
        "first_name": null,
        "landline": null,
        "last_name": null,
        "mobile_phone": null,
        "ownership": null
      }
    ],
    "company_name": null,
    "company_registration_number": null,
    "country": null,
    "doing_business_as": {
      "address": {
        "address_line1": null,
        "address_line2": null,
        "city": null,
        "country": null,
        "post_code": null,
        "region_id": null,
        "region_name": null
      },
      "business_name": null,
      "company_registration_number": null,
      "email": null,
      "vat_id": null,
      "website": null
    },
    "extdev": null,
    "legal_type": {
      "description": null,
      "full_description": null,
      "id": null,
      "sole_trader": null
    },
    "locale": null,
    "merchant_category_code": null,
    "merchant_code": null,
    "mobile_phone": null,
    "nature_and_purpose": null,
    "payout_zone_migrated": null,
    "permanent_certificate_access_code": null,
    "settings": {
      "daily_payout_email": null,
      "gross_settlement": null,
      "monthly_payout_email": null,
      "moto_payment": null,
      "payout_instrument": null,
      "payout_on_demand": null,
      "payout_on_demand_available": null,
      "payout_period": null,
      "payout_type": null,
      "printers_enabled": null,
      "stone_merchant_code": null,
      "tax_enabled": null
    },
    "vat_id": null,
    "vat_rates": {
      "country": null,
      "description": null,
      "id": null,
      "ordering": null,
      "rate": null
    },
    "website": null
  },
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "personal_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "complete": null,
    "date_of_birth": null,
    "first_name": null,
    "last_name": null,
    "mobile_phone": null
  }
} 

Merchant

Retrieve a profile

Returns user profile information.

Scopes: user.profile user.profile_readonly

Query Parameters

include[] []string

Response 200

account object

Profile information.
Show attributes
Close

Attributes
- type string
  
  Options: normal operator
  
  The role of the user.
- username string
  
  Username of the user profile.
app_settings object

Mobile app settings
Show attributes
Close

Attributes
- advanced_mode string
  
  Advanced mode.
- barcode_scanner string
  
  Barcode scanner.
- cash_payment string
  
  Cash payment.
- checkout_preference string
  
  Checkout preference
- expected_max_transaction_amount number
  
  Expected max transaction amount.
- include_vat boolean
  
  Include vat.
- manual_entry string
  
  Manual entry.
- manual_entry_tutorial boolean
  
  Manual entry tutorial.
- mobile_payment string
  
  Mobile payment.
- mobile_payment_tutorial boolean
  
  Mobile payment tutorial.
- reader_payment string
  
  Reader payment.
- referral string
  
  Referral.
- tax_enabled boolean
  
  Tax enabled.
- terminal_mode_tutorial boolean
  
  Terminal mode tutorial.
- tip_rates []number
  
  Tip rates.
  
  Show attributes
  
  Close
  
  Attributes
- tipping string
  
  Tipping.
is_migrated_payleven_br boolean

Merchant comes from payleven BR migration
merchant_profile object

Account's merchant profile
Show attributes
Close

Attributes
- address object
  
  Details of the registered address.
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  company string
  
  undefined
  
  country string
  
  Country ISO 3166-1 code
  
  country_details object
  
  Country Details
  
  Show attributes
  
  Close
  
  Attributes
  
  currency string
  
  Currency ISO 4217 code
  
  en_name string
  
  Country EN name
  
  iso_code string
  
  Country ISO code
  
  native_name string
  
  Country native name
  
  first_name string
  
  undefined
  
  landline string
  
  Landline number
  
  last_name string
  
  undefined
  
  post_code string
  
  Postal code
  
  region_code string
  
  Region code
  
  region_id number
  
  Country region id
  
  region_name string
  
  Region name
  
  state_id string
  
  undefined
  
  timeoffset_details object
  
  TimeOffset Details
  
  Show attributes
  
  Close
  
  Attributes
  
  dst boolean
  
  Daylight Saving Time
  
  offset number
  
  UTC offset
  
  post_code string
  
  Postal code
- bank_accounts []object
  
  Show attributes
  
  Close
  
  Attributes
  
  account_category string
  
  Account category - business or personal
  
  account_holder_name string
  
  account_number string
  
  Account number
  
  account_type string
  
  Type of the account
  
  bank_code string
  
  Bank code
  
  bank_name string
  
  Bank name
  
  branch_code string
  
  Branch code
  
  created_at string
  
  Creation date of the bank account
  
  iban string
  
  IBAN
  
  primary boolean
  
  The primary bank account is the one used for settlements
  
  status string
  
  Status in the verification process
  
  swift string
  
  SWIFT code
- business_owners []object
  
  Business owners information.
- company_name string
  
  Company name
- company_registration_number string
  
  Company registration number
- country string
  
  Merchant country isocode (for internal usage only)
- doing_business_as object
  
  Doing Business As information
  
  Show attributes
  
  Close
  
  Attributes
  
  address object
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  country string
  
  Country ISO 3166-1 code
  
  post_code string
  
  Postal code
  
  region_id number
  
  Country region ID
  
  region_name string
  
  Country region name
  
  business_name string
  
  Doing business as name
  
  company_registration_number string
  
  Doing business as company registration number
  
  email string
  
  Doing business as email
  
  vat_id string
  
  Doing business as VAT ID
  
  website string
  
  Doing business as website
- extdev boolean
  
  True if the merchant is extdev
- legal_type object
  
  Id of the legal type of the merchant profile
  
  Show attributes
  
  Close
  
  Attributes
  
  description string
  
  Legal type short description
  
  full_description string
  
  Legal type description
  
  id number
  
  Unique id
  
  sole_trader boolean
  
  Sole trader legal type if true
- locale string
  
  Merchant locale (for internal usage only)
- merchant_category_code string
  
  Merchant category code
- merchant_code string
  
  Unique identifying code of the merchant profile
- mobile_phone string
  
  Mobile phone number
- nature_and_purpose string
  
  Nature and purpose of the business
- payout_zone_migrated boolean
  
  True if the payout zone of this merchant is migrated
- permanent_certificate_access_code string
  
  Permanent certificate access code (Portugal)
- settings object
  
  Merchant settings (like "payout_type", "payout_period")
  
  Show attributes
  
  Close
  
  Attributes
  
  daily_payout_email boolean
  
  Whether merchant will receive daily payout emails
  
  gross_settlement boolean
  
  Whether merchant has gross settlement enabled
  
  monthly_payout_email boolean
  
  Whether merchant will receive monthly payout emails
  
  moto_payment string
  
  Options: UNAVAILABLE ENFORCED ON OFF
  
  Whether merchant can make MOTO payments
  
  payout_instrument string
  
  Payout Instrument
  
  payout_on_demand boolean
  
  Whether merchant will receive payouts on demand
  
  payout_on_demand_available boolean
  
  Whether merchant can edit payouts on demand
  
  payout_period string
  
  Payout frequency
  
  payout_type string
  
  Payout type
  
  printers_enabled boolean
  
  Whether to show printers in mobile app
  
  stone_merchant_code string
  
  Stone merchant code
  
  tax_enabled boolean
  
  Whether to show tax in receipts (saved per transaction)
- vat_id string
  
  Vat ID
- vat_rates object
  
  Merchant VAT rates
  
  Show attributes
  
  Close
  
  Attributes
  
  country string
  
  Country ISO code
  
  description string
  
  Description
  
  id number
  
  Internal ID
  
  ordering number
  
  Ordering
  
  rate number
  
  Rate
- website string
  
  Website
permissions object

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- create_referral boolean
  
  Create referral
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
personal_profile object

Account's personal profile.
Show attributes
Close

Attributes
- address object
  
  Details of the registered address.
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  company string
  
  undefined
  
  country string
  
  Country ISO 3166-1 code
  
  country_details object
  
  Country Details
  
  Show attributes
  
  Close
  
  Attributes
  
  currency string
  
  Currency ISO 4217 code
  
  en_name string
  
  Country EN name
  
  iso_code string
  
  Country ISO code
  
  native_name string
  
  Country native name
  
  first_name string
  
  undefined
  
  landline string
  
  Landline number
  
  last_name string
  
  undefined
  
  post_code string
  
  Postal code
  
  region_code string
  
  Region code
  
  region_id number
  
  Country region id
  
  region_name string
  
  Region name
  
  state_id string
  
  undefined
  
  timeoffset_details object
  
  TimeOffset Details
  
  Show attributes
  
  Close
  
  Attributes
  
  dst boolean
  
  Daylight Saving Time
  
  offset number
  
  UTC offset
  
  post_code string
  
  Postal code
- complete boolean
- date_of_birth string
  
  Date of birth
- first_name string
  
  First name of the user
- last_name string
  
  Last name of the user
- mobile_phone string
  
  Mobile phone number

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me  
 curl https://api.sumup.com/v0.1/me 

Retrieve a profile response
 {
  "account": {
    "type": null,
    "username": null
  },
  "app_settings": {
    "advanced_mode": null,
    "barcode_scanner": null,
    "cash_payment": null,
    "checkout_preference": null,
    "expected_max_transaction_amount": null,
    "include_vat": null,
    "manual_entry": null,
    "manual_entry_tutorial": null,
    "mobile_payment": null,
    "mobile_payment_tutorial": null,
    "reader_payment": null,
    "referral": null,
    "tax_enabled": null,
    "terminal_mode_tutorial": null,
    "tip_rates": [
      null
    ],
    "tipping": null
  },
  "is_migrated_payleven_br": null,
  "merchant_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "bank_accounts": [
      {
        "account_category": null,
        "account_holder_name": null,
        "account_number": null,
        "account_type": null,
        "bank_code": null,
        "bank_name": null,
        "branch_code": null,
        "created_at": null,
        "iban": null,
        "primary": null,
        "status": null,
        "swift": null
      }
    ],
    "business_owners": [
      {
        "date_of_birth": null,
        "first_name": null,
        "landline": null,
        "last_name": null,
        "mobile_phone": null,
        "ownership": null
      }
    ],
    "company_name": null,
    "company_registration_number": null,
    "country": null,
    "doing_business_as": {
      "address": {
        "address_line1": null,
        "address_line2": null,
        "city": null,
        "country": null,
        "post_code": null,
        "region_id": null,
        "region_name": null
      },
      "business_name": null,
      "company_registration_number": null,
      "email": null,
      "vat_id": null,
      "website": null
    },
    "extdev": null,
    "legal_type": {
      "description": null,
      "full_description": null,
      "id": null,
      "sole_trader": null
    },
    "locale": null,
    "merchant_category_code": null,
    "merchant_code": null,
    "mobile_phone": null,
    "nature_and_purpose": null,
    "payout_zone_migrated": null,
    "permanent_certificate_access_code": null,
    "settings": {
      "daily_payout_email": null,
      "gross_settlement": null,
      "monthly_payout_email": null,
      "moto_payment": null,
      "payout_instrument": null,
      "payout_on_demand": null,
      "payout_on_demand_available": null,
      "payout_period": null,
      "payout_type": null,
      "printers_enabled": null,
      "stone_merchant_code": null,
      "tax_enabled": null
    },
    "vat_id": null,
    "vat_rates": {
      "country": null,
      "description": null,
      "id": null,
      "ordering": null,
      "rate": null
    },
    "website": null
  },
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "personal_profile": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "company": null,
      "country": null,
      "country_details": {
        "currency": null,
        "en_name": null,
        "iso_code": null,
        "native_name": null
      },
      "first_name": null,
      "landline": null,
      "last_name": null,
      "post_code": null,
      "region_code": null,
      "region_id": null,
      "region_name": null,
      "state_id": null,
      "timeoffset_details": {
        "dst": null,
        "offset": null,
        "post_code": null
      }
    },
    "complete": null,
    "date_of_birth": null,
    "first_name": null,
    "last_name": null,
    "mobile_phone": null
  }
} 

Merchant

Retrieve a merchant profile

Retrieves merchant profile data.

Scopes: user.profile user.profile_readonly

Response 200

address object

Details of the registered address.
Show attributes
Close

Attributes
- address_line1 string
  
  Address line 1
- address_line2 string
  
  Address line 2
- city string
  
  City
- company string
  
  undefined
- country string
  
  Country ISO 3166-1 code
- country_details object
  
  Country Details
  
  Show attributes
  
  Close
  
  Attributes
  
  currency string
  
  Currency ISO 4217 code
  
  en_name string
  
  Country EN name
  
  iso_code string
  
  Country ISO code
  
  native_name string
  
  Country native name
- first_name string
  
  undefined
- landline string
  
  Landline number
- last_name string
  
  undefined
- post_code string
  
  Postal code
- region_code string
  
  Region code
- region_id number
  
  Country region id
- region_name string
  
  Region name
- state_id string
  
  undefined
- timeoffset_details object
  
  TimeOffset Details
  
  Show attributes
  
  Close
  
  Attributes
  
  dst boolean
  
  Daylight Saving Time
  
  offset number
  
  UTC offset
  
  post_code string
  
  Postal code
bank_accounts []object
Show attributes
Close

Attributes
- account_category string
  
  Account category - business or personal
- account_holder_name string
- account_number string
  
  Account number
- account_type string
  
  Type of the account
- bank_code string
  
  Bank code
- bank_name string
  
  Bank name
- branch_code string
  
  Branch code
- created_at string
  
  Creation date of the bank account
- iban string
  
  IBAN
- primary boolean
  
  The primary bank account is the one used for settlements
- status string
  
  Status in the verification process
- swift string
  
  SWIFT code
business_owners []object

Business owners information.
company_name string

Company name
company_registration_number string

Company registration number
country string

Merchant country isocode (for internal usage only)
doing_business_as object

Doing Business As information
Show attributes
Close

Attributes
- address object
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  Address line 1
  
  address_line2 string
  
  Address line 2
  
  city string
  
  City
  
  country string
  
  Country ISO 3166-1 code
  
  post_code string
  
  Postal code
  
  region_id number
  
  Country region ID
  
  region_name string
  
  Country region name
- business_name string
  
  Doing business as name
- company_registration_number string
  
  Doing business as company registration number
- email string
  
  Doing business as email
- vat_id string
  
  Doing business as VAT ID
- website string
  
  Doing business as website
extdev boolean

True if the merchant is extdev
legal_type object

Id of the legal type of the merchant profile
Show attributes
Close

Attributes
- description string
  
  Legal type short description
- full_description string
  
  Legal type description
- id number
  
  Unique id
- sole_trader boolean
  
  Sole trader legal type if true
locale string

Merchant locale (for internal usage only)
merchant_category_code string

Merchant category code
merchant_code string

Unique identifying code of the merchant profile
mobile_phone string

Mobile phone number
nature_and_purpose string

Nature and purpose of the business
payout_zone_migrated boolean

True if the payout zone of this merchant is migrated
permanent_certificate_access_code string

Permanent certificate access code (Portugal)
settings object

Merchant settings (like "payout_type", "payout_period")
Show attributes
Close

Attributes
- daily_payout_email boolean
  
  Whether merchant will receive daily payout emails
- gross_settlement boolean
  
  Whether merchant has gross settlement enabled
- monthly_payout_email boolean
  
  Whether merchant will receive monthly payout emails
- moto_payment string
  
  Options: UNAVAILABLE ENFORCED ON OFF
  
  Whether merchant can make MOTO payments
- payout_instrument string
  
  Payout Instrument
- payout_on_demand boolean
  
  Whether merchant will receive payouts on demand
- payout_on_demand_available boolean
  
  Whether merchant can edit payouts on demand
- payout_period string
  
  Payout frequency
- payout_type string
  
  Payout type
- printers_enabled boolean
  
  Whether to show printers in mobile app
- stone_merchant_code string
  
  Stone merchant code
- tax_enabled boolean
  
  Whether to show tax in receipts (saved per transaction)
vat_id string

Vat ID
vat_rates object

Merchant VAT rates
Show attributes
Close

Attributes
- country string
  
  Country ISO code
- description string
  
  Description
- id number
  
  Internal ID
- ordering number
  
  Ordering
- rate number
  
  Rate
website string

Website

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/merchant-profile  
 curl https://api.sumup.com/v0.1/me/merchant-profile 

Retrieve a merchant profile response
 {
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "company": null,
    "country": null,
    "country_details": {
      "currency": null,
      "en_name": null,
      "iso_code": null,
      "native_name": null
    },
    "first_name": null,
    "landline": null,
    "last_name": null,
    "post_code": null,
    "region_code": null,
    "region_id": null,
    "region_name": null,
    "state_id": null,
    "timeoffset_details": {
      "dst": null,
      "offset": null,
      "post_code": null
    }
  },
  "bank_accounts": [
    {
      "account_category": null,
      "account_holder_name": null,
      "account_number": null,
      "account_type": null,
      "bank_code": null,
      "bank_name": null,
      "branch_code": null,
      "created_at": null,
      "iban": null,
      "primary": null,
      "status": null,
      "swift": null
    }
  ],
  "business_owners": [
    {
      "date_of_birth": null,
      "first_name": null,
      "landline": null,
      "last_name": null,
      "mobile_phone": null,
      "ownership": null
    }
  ],
  "company_name": null,
  "company_registration_number": null,
  "country": null,
  "doing_business_as": {
    "address": {
      "address_line1": null,
      "address_line2": null,
      "city": null,
      "country": null,
      "post_code": null,
      "region_id": null,
      "region_name": null
    },
    "business_name": null,
    "company_registration_number": null,
    "email": null,
    "vat_id": null,
    "website": null
  },
  "extdev": null,
  "legal_type": {
    "description": null,
    "full_description": null,
    "id": null,
    "sole_trader": null
  },
  "locale": null,
  "merchant_category_code": null,
  "merchant_code": null,
  "mobile_phone": null,
  "nature_and_purpose": null,
  "payout_zone_migrated": null,
  "permanent_certificate_access_code": null,
  "settings": {
    "daily_payout_email": null,
    "gross_settlement": null,
    "monthly_payout_email": null,
    "moto_payment": null,
    "payout_instrument": null,
    "payout_on_demand": null,
    "payout_on_demand_available": null,
    "payout_period": null,
    "payout_type": null,
    "printers_enabled": null,
    "stone_merchant_code": null,
    "tax_enabled": null
  },
  "vat_id": null,
  "vat_rates": {
    "country": null,
    "description": null,
    "id": null,
    "ordering": null,
    "rate": null
  },
  "website": null
} 

Merchant

List bank accounts

Retrives bank accounts of the merchant.

Scopes: user.payout-settings user.profile user.profile_readonly

Query Parameters

primary boolean

Response 200

[]object

Show attributes

account_category string

Account category - business or personal
account_holder_name string
account_number string

Account number
account_type string

Type of the account
bank_code string

Bank code
bank_name string

Bank name
branch_code string

Branch code
created_at string

Creation date of the bank account
iban string

IBAN
primary boolean

The primary bank account is the one used for settlements
status string

Status in the verification process
swift string

SWIFT code

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/merchant-profile/bank-accounts  
 curl https://api.sumup.com/v0.1/me/merchant-profile/bank-accounts 

List bank accounts response
 [
  {
    "account_category": null,
    "account_holder_name": null,
    "account_number": null,
    "account_type": null,
    "bank_code": null,
    "bank_name": null,
    "branch_code": null,
    "created_at": null,
    "iban": null,
    "primary": null,
    "status": null,
    "swift": null
  }
] 

Merchant

Retrieve DBA

Retrieves Doing Business As profile.

Scopes: user.profile user.profile_readonly

Response 200

address object
Show attributes
Close

Attributes
- address_line1 string
  
  Address line 1
- address_line2 string
  
  Address line 2
- city string
  
  City
- country string
  
  Country ISO 3166-1 code
- post_code string
  
  Postal code
- region_id number
  
  Country region ID
- region_name string
  
  Country region name
business_name string

Doing business as name
company_registration_number string

Doing business as company registration number
email string

Doing business as email
vat_id string

Doing business as VAT ID
website string

Doing business as website

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/merchant-profile/doing-business-as  
 curl https://api.sumup.com/v0.1/me/merchant-profile/doing-business-as 

Retrieve DBA response
 {
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "post_code": null,
    "region_id": null,
    "region_name": null
  },
  "business_name": null,
  "company_registration_number": null,
  "email": null,
  "vat_id": null,
  "website": null
} 

Merchant

Get settings

Retrieves merchant settings.

Scopes: user.payout-settings

Response 200

daily_payout_email boolean

Whether merchant will receive daily payout emails
gross_settlement boolean

Whether merchant has gross settlement enabled
monthly_payout_email boolean

Whether merchant will receive monthly payout emails
moto_payment string

Options: UNAVAILABLE ENFORCED ON OFF

Whether merchant can make MOTO payments
payout_instrument string

Payout Instrument
payout_on_demand boolean

Whether merchant will receive payouts on demand
payout_on_demand_available boolean

Whether merchant can edit payouts on demand
payout_period string

Payout frequency
payout_type string

Payout type
printers_enabled boolean

Whether to show printers in mobile app
stone_merchant_code string

Stone merchant code
tax_enabled boolean

Whether to show tax in receipts (saved per transaction)

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
error_message string

Short description of the error.
status_code string

HTTP status code for the error.

 get 
 /v0.1/me/merchant-profile/settings  
 curl https://api.sumup.com/v0.1/me/merchant-profile/settings 

Get settings response
 {
  "daily_payout_email": null,
  "gross_settlement": null,
  "monthly_payout_email": null,
  "moto_payment": null,
  "payout_instrument": null,
  "payout_on_demand": null,
  "payout_on_demand_available": null,
  "payout_period": null,
  "payout_type": null,
  "printers_enabled": null,
  "stone_merchant_code": null,
  "tax_enabled": null
} 

Merchant

Retrieve a personal profile

Retrieves personal profile data.

Scopes: user.profile user.profile_readonly

Response 200

address object

Details of the registered address.
Show attributes
Close

Attributes
- address_line1 string
  
  Address line 1
- address_line2 string
  
  Address line 2
- city string
  
  City
- company string
  
  undefined
- country string
  
  Country ISO 3166-1 code
- country_details object
  
  Country Details
  
  Show attributes
  
  Close
  
  Attributes
  
  currency string
  
  Currency ISO 4217 code
  
  en_name string
  
  Country EN name
  
  iso_code string
  
  Country ISO code
  
  native_name string
  
  Country native name
- first_name string
  
  undefined
- landline string
  
  Landline number
- last_name string
  
  undefined
- post_code string
  
  Postal code
- region_code string
  
  Region code
- region_id number
  
  Country region id
- region_name string
  
  Region name
- state_id string
  
  undefined
- timeoffset_details object
  
  TimeOffset Details
  
  Show attributes
  
  Close
  
  Attributes
  
  dst boolean
  
  Daylight Saving Time
  
  offset number
  
  UTC offset
  
  post_code string
  
  Postal code
complete boolean
date_of_birth string

Date of birth
first_name string

First name of the user
last_name string

Last name of the user
mobile_phone string

Mobile phone number

error_code string

Platform code for the error.
message string

Short description of the error.

 get 
 /v0.1/me/personal-profile  
 curl https://api.sumup.com/v0.1/me/personal-profile 

Retrieve a personal profile response
 {
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "company": null,
    "country": null,
    "country_details": {
      "currency": null,
      "en_name": null,
      "iso_code": null,
      "native_name": null
    },
    "first_name": null,
    "landline": null,
    "last_name": null,
    "post_code": null,
    "region_code": null,
    "region_id": null,
    "region_name": null,
    "state_id": null,
    "timeoffset_details": {
      "dst": null,
      "offset": null,
      "post_code": null
    }
  },
  "complete": null,
  "date_of_birth": null,
  "first_name": null,
  "last_name": null,
  "mobile_phone": null
} 

Subaccounts

Endpoints for managing merchant sub-accounts (operators).

The object

Attributes

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Subaccounts

List operators.
Deprecated

Returns list of operators for currently authorized user's merchant.

Scopes:

Query Parameters

query string
include_primary boolean

Response 200

[]object

Show attributes

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

 get 
 /v0.1/me/accounts  
 curl https://api.sumup.com/v0.1/me/accounts 

[
  {
    "account_type": "",
    "created_at": "",
    "disabled": false,
    "id": 0,
    "nickname": "Operator 1",
    "permissions": {
      "admin": false,
      "create_moto_payments": false,
      "create_referral": false,
      "full_transaction_history_view": false,
      "refund_transactions": false
    },
    "updated_at": "",
    "username": "[email protected]"
  }
]

Subaccounts

Create operator.
Deprecated

Creates new operator for currently authorized users' merchant.

Scopes:

Body Parameters

nickname string

Example: "Operator 1"
password string required

Example: "correct horse batter staple"
permissions object
Show attributes
Close

Attributes
- create_moto_payments boolean
- create_referral boolean
- full_transaction_history_view boolean
- refund_transactions boolean
username string required

Example: "[email protected]"

Response 200

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

error_code string required

Example: "NOT_FOUND"
message string required

Example: "Resource not found."

 post 
 /v0.1/me/accounts  
 curl https://api.sumup.com/v0.1/me/accounts 

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Subaccounts

Get operator
Deprecated

Returns specific operator.

Scopes:

Path Parameters

operator_id integer required

Response 200

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

 get 
 /v0.1/me/accounts/{operator_id}  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_id} 

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Subaccounts

Update operator.
Deprecated

Updates operator. If the operator was disabled and their password is updated they will be unblocked.

Scopes:

Path Parameters

operator_id integer required

Body Parameters

disabled boolean
nickname string

Example: "Operator 1"
password string

Example: "correct horse batter staple"
permissions object
Show attributes
Close

Attributes
- create_moto_payments boolean
- create_referral boolean
- full_transaction_history_view boolean
- refund_transactions boolean
username string

Response 200

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

error_code string required

Example: "NOT_FOUND"
message string required

Example: "Resource not found."

 put 
 /v0.1/me/accounts/{operator_id}  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_id} 

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Subaccounts

Disable operator.
Deprecated

Scopes:

Path Parameters

operator_id integer required

Response 200

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

 delete 
 /v0.1/me/accounts/{operator_id}  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_id} 

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Subaccounts

Disable operator.
Deprecated

Scopes:

Path Parameters

operator_id integer required

Response 200

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

 post 
 /v0.1/me/accounts/{operator_id}/disable  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_id}/disable 

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Subaccounts

Change operators password.
Deprecated

Changes operators password, if the operator was disabled they will be unblocked.

Scopes:

Path Parameters

operator_id integer required

Body Parameters

password string

Example: "correct horse batter staple"

Response 200

account_type string required

Options: operator normal
created_at string required
disabled boolean required
id integer required
nickname string

Example: "Operator 1"
permissions object required
Show attributes
Close

Attributes
- admin boolean required
- create_moto_payments boolean required
- create_referral boolean required
- full_transaction_history_view boolean required
- refund_transactions boolean required
updated_at string required
username string required

Example: "[email protected]"

error_code string required

Example: "NOT_FOUND"
message string required

Example: "Resource not found."

 put 
 /v0.1/me/accounts/{operator_id}/reset  
 curl https://api.sumup.com/v0.1/me/accounts/{operator_id}/reset 

{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Payouts

The Payouts model will allow you to track funds you’ve received from SumUp. You can receive a detailed payouts list with information like dates, fees, references and statuses, using the List payouts endpoint.

The Financial Payouts object

Attributes

[]object

Show attributes

amount number
currency string
date string
fee number
id integer
reference string
status string

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

The Financial Payouts object
 [
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
] 

Payouts

List payouts

Lists ordered payouts for the merchant profile.

Scopes: user.profile user.profile_readonly

Query Parameters

start_date string required
end_date string required
format string
limit integer
order string

Response 200

[]object

Show attributes

amount number
currency string
date string
fee number
id integer
reference string
status string

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

error_code string

Platform code for the error.
message string

Short description of the error.

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

List payouts response
 [
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
] 

Transactions

Retrieve details for a specific transaction by it’s id or any other required query parameter, or list all transactions related to the merchant account.

Transactions

Refund a transaction

Refunds an identified transaction either in full or partially.

Scopes: payments

Path Parameters

txn_id string required

Body Parameters

amount number

Amount to be refunded. Eligible amount can't exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.

Response 204

error_code string

Platform code for the error.
message string

Short description of the error.

error_code string

Platform code for the error.
message string

Short description of the error.

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

{}

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
foreign_transaction_id
client_transaction_id

Scopes: transactions.history

Query Parameters

id string
internal_id string
transaction_code string

Response 200

amount number

Total amount of the transaction.

Example: 10.1
currency string

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

Example: "EUR"
id string

Unique ID of the transaction.

Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
installments_count integer

Current number of the installment for deferred payments.
payment_type string

Options: ECOM RECURRING BOLETO

Payment type used for the transaction.
status string

Options: SUCCESSFUL CANCELLED FAILED PENDING

Current status of the transaction.
timestamp string

Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

Example: "2020-02-29T10:56:56.876Z"
transaction_code string

Transaction code returned by the acquirer/processing entity after processing the transaction.

Example: "TEENSK4W2K"
auth_code string

Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

Example: "053201"
entry_mode string

Options: CUSTOMER_ENTRY BOLETO

Entry mode of the payment details.
internal_id integer

Internal unique ID of the transaction on the SumUp platform.

Example: 1763892018
merchant_code string

Unique code of the registered merchant to whom the payment is made.

Example: "MH4H92C7"
tip_amount number

Amount of the tip (out of the total transaction amount).

Example: 3
vat_amount number

Amount of the applicable VAT (out of the total transaction amount).

Example: 6
payout_plan string

Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

Payout plan of the registered user at the time when the transaction was made.
payouts_received integer

Number of payouts that are made to the registered user specified in the user property.
payouts_total integer

Total number of payouts to the registered user specified in the user property.
product_summary string

Short description of the payment. The value is taken from the description property of the related checkout resource.
card object

Details of the payment card.
Show attributes
Close

Attributes
- last_4_digits string
  
  Last 4 digits of the payment card number.
  
  Example: "3456"
- type string
  
  Options: AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card.
events []object

List of events related to the transaction.
Show attributes
Close

Attributes
- amount number
  
  Amount of the event.
- deducted_amount number
  
  Amount deducted for the event.
- deducted_fee_amount number
  
  Amount of the fee deducted for the event.
- fee_amount number
  
  Amount of the fee related to the event.
- id integer
  
  Unique ID of the transaction event.
- installment_number integer
  
  Consecutive number of the installment.
- status string
  
  Status of the transaction event.
- timestamp string
  
  Date and time of the transaction event.
- transaction_id string
  
  Unique ID of the transaction.
- type string
  
  Type of the transaction event.
horizontal_accuracy number

Indication of the precision of the geographical position received from the payment terminal.
lat number

Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
links []object

List of hyperlinks for accessing related resources.
Show attributes
Close

Attributes
local_time string

Local date and time of the creation of the transaction.
location object

Details of the payment location as received from the payment terminal.
Show attributes
Close

Attributes
- horizontal_accuracy number
  
  Indication of the precision of the geographical position received from the payment terminal.
- lat number
  
  Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
- lon number
  
  Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
lon number

Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
payout_type string

Options: BANK_ACCOUNT BALANCE PREPAID_CARD

Payout type for the transaction.
products []object

List of products from the merchant's catalogue for which the transaction serves as a payment.
Show attributes
Close

Attributes
- name string
  
  Name of the product from the merchant's catalog.
- price number
  
  Price of the product without VAT.
- price_with_vat number
  
  Price of a single product item with VAT.
- quantity number
  
  Number of product items for the purchase.
- single_vat_amount number
  
  Amount of the VAT for a single product item (calculated as the product of price and vat_rate, i.e. single_vat_amount = price * vat_rate).
- total_price number
  
  Total price of the product items without VAT (calculated as the product of price and quantity, i.e. total_price = price * quantity).
- total_with_vat number
  
  Total price of the product items including VAT (calculated as the product of price_with_vat and quantity, i.e. total_with_vat = price_with_vat * quantity).
- vat_amount number
  
  Total VAT amount for the purchase (calculated as the product of single_vat_amount and quantity, i.e. vat_amount = single_vat_amount * quantity).
- vat_rate number
  
  VAT rate applicable to the product.
simple_payment_type string

Options: MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

Simple name of the payment type.
simple_status string

Options: SUCCESSFUL PAID_OUT CANCEL_FAILED CANCELLED CHARGEBACK FAILED REFUND_FAILED REFUNDED NON_COLLECTION

Status generated from the processing status and the latest transaction state.
tax_enabled boolean

Indicates whether tax deduction is enabled for the transaction.
transaction_events []object

List of transaction events related to the transaction.
Show attributes
Close

Attributes
- amount number
  
  Amount of the event.
- date string
  
  Date when the transaction event occurred.
- due_date string
  
  Date when the transaction event is due to occur.
- event_type string
  
  Type of the transaction event.
- id integer
  
  Unique ID of the transaction event.
- installment_number integer
  
  Consequtive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.
- status string
  
  Status of the transaction event.
- timestamp string
  
  Date and time of the transaction event.
username string

Email address of the registered user (merchant) to whom the payment is made.
vat_rates []object

List of VAT rates applicable to the transaction.
Show attributes
Close

Attributes
verification_method string

Options:

SumUp REST API

Authorization

Request authorization from users

Query Parameters

Response 200

Generate a token

Body Parameters

Response 200

Response 400

Checkouts

The Checkout object

Attributes

List checkouts

Query Parameters

Response 200

Response 401

Create a checkout

Body Parameters

Response 201

Response 400

Response 401

Response 403

Response 409

Retrieve a checkout

Path Parameters

Response 200

Response 401

Response 404

Process a checkout

Path Parameters

Body Parameters

Response 200

Response 400

Response 401

Response 404

Response 409

Deactivate a checkout

Path Parameters

Response 200

Response 401

Response 404

Response 409

Get available payment methods

Path Parameters

Query Parameters

Response 200

Response 400

Response 401

Customers

The Customer object

Attributes

Create a customer

Body Parameters

Response 201

Response 401

Response 403

Response 409

Retrieve a customer

Path Parameters

Response 200

Response 401

Response 403

Response 404

Update a customer

Path Parameters

Body Parameters

Response 200

Response 401

Response 403

Response 404

List payment instruments

Path Parameters

Response 200

Response 401

Response 403

Response 404

Deactivate a payment instrument

Path Parameters

Response 204

Response 401

List operators.
Deprecated

Create operator.
Deprecated

Get operator
Deprecated

Update operator.
Deprecated

Disable operator.
Deprecated

Disable operator.
Deprecated

Change operators password.
Deprecated