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 characte[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
Example: "code"
client_id string
Example: "fOcmczrYtYMJ7Li5GjMLLcUeC9dN"
redirect_uri string
Example: "https://sample-app.example.com/callback"
scope string
Example: "payments"
state string
Example: "2cFCsY36y95lFHk4"

Response 200

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

NoBody
{}

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_coderefresh_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

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

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
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.
mandate object
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: PENDINGFAILEDPAID
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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": null,
  "date": "2020-02-29T10:56:56+00:00",
  "description": null,
  "id": null,
  "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.
Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
currency string
customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced 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.
Example: "Purchase"
id string
Unique ID of the checkout resource.
Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object
merchant_code string
Unique identifying code of the merchant profile.
Example: "MH4H92C7"
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.
Example: "[email protected]"
return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
status string
Options: PENDINGFAILEDPAID
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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

[
  {
    "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": 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
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: ACALAPAMBACEDFESGOMAMTMSMGPAPBPRPEPIRJRNRSRORRSCSPSETO
  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: CHECKOUTSETUP_RECURRING_PAYMENT
Purpose of the checkout.
redirect_url string
Required for 3DS checkouts. Refers to a URL where the end user is redirected once the payment processing completes.
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: PENDINGFAILEDPAID
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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
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.
mandate object
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: PENDINGFAILEDPAID
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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

{
  "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"
}

{
  "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"
}

{
  "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.
Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
currency string
customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced 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.
Example: "Purchase"
id string
Unique ID of the checkout resource.
Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object
merchant_code string
Unique identifying code of the merchant profile.
Example: "MH4H92C7"
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.
Example: "[email protected]"
return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
status string
Options: PENDINGFAILEDPAID
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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}

{
  "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": 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
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
payment_type string required
Options: cardboletoidealsofortbancontact
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.
Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
currency string
customer_id string
Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced 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.
Example: "Purchase"
id string
Unique ID of the checkout resource.
Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
mandate object
merchant_code string
Unique identifying code of the merchant profile.
Example: "MH4H92C7"
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.
Example: "[email protected]"
return_url string
URL to which the SumUp platform sends the processing status of the payment checkout.
status string
Options: PENDINGFAILEDPAID
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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}

CheckoutSuccessBancontact
{
  "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"
  }
}

{
  "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
    }
  ]
}

{
  "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"
}

CheckoutSuccessSofort
{
  "next_step": {
    "full": "https://r3.girogate.de/ti/sofortueberweisungmixed?tx=624786308&rs=MyFOScJ7I3iAmU4Wmalwb1bObT1st1b1&cs=364d0864ffa3602eb757b18326ffeb8be0c9c6e2ab7dcfebc1e2b0f6491eaae9",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "364d0864ffa3602eb757b18326ffeb8be0c9c6e2ab7dcfebc1e2b0f6491eaae9",
      "rs": "MyFOScJ7I3iAmU4Wmalwb1bObT1st1b1",
      "tx": "624786308"
    },
    "url": "https://r3.girogate.de/ti/sofortueberweisungmixed"
  }
}

{
  "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
    }
  ]
}

CheckoutSuccessiDeal
{
  "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
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_PAYMENTCHECKOUT
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
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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_ENTRYBOLETO
  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}

{
  "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

Query Parameters

amount number
currency string

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

success
{
  "available_payment_methods": [
    {
      "id": "apple_pay"
    },
    {
      "id": "sofort"
    }
  ]
}

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

{
  "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

Response 201

customer_id string required
Unique ID of the customer.
Example: "831ff8d4cd5958ab5670"
personal_details 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/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

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

Response 200

customer_id string required
Unique ID of the customer.
Example: "831ff8d4cd5958ab5670"
personal_details 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.

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: AMEXCUPDINERSDISCOVERELOELVHIPERCARDJCBMAESTROMASTERCARDVISAVISA_ELECTRONVISA_VPAYUNKNOWN
  Issuing card network of the payment card.
created_at string
Creation date of payment instrument. Response format expressed according to ISO8601 code.
mandate object
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

Create a payment instrument

Creates and activates a new payment instrument resource by saving a payment card for an identified customer. Implement to improve customer experience by skipping the step of entering payment instrument details.

The token created via this endpoint can not be used for recurring payments by merchants operating within the EU. For more information visit our recurring payments guide.

Scopes: payment_instruments

Path Parameters

customer_id string required

Body Parameters

active boolean required
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 required
token string required
Unique token identifying the saved payment card for a customer.
type string required
Options: card
Type of the payment instrument.

Response 201

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: AMEXCUPDINERSDISCOVERELOELVHIPERCARDJCBMAESTROMASTERCARDVISAVISA_ELECTRONVISA_VPAYUNKNOWN
  Issuing card network of the payment card.
created_at string
Creation date of payment instrument. Response format expressed according to ISO8601 code.
mandate object
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.

error_code string
Platform code for the error.
message string
Short description of the error.

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

Create a payment instrument 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}

NoBody
{}

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Attributes

account object
app_settings object
is_migrated_payleven_br boolean
Merchant comes from payleven BR migration
merchant_profile object
operators []object
permissions object
personal_profile object

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": {
      "adyen_company": null,
      "adyen_merchant_code": null,
      "adyen_password": null,
      "adyen_user": null,
      "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
  },
  "operators": [
    {
      "username": 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.profileuser.profile_readonly

Query Parameters

include[] []string

Response 200

account object
app_settings object
is_migrated_payleven_br boolean
Merchant comes from payleven BR migration
merchant_profile object
operators []object
permissions object
personal_profile object

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": {
      "adyen_company": null,
      "adyen_merchant_code": null,
      "adyen_password": null,
      "adyen_user": null,
      "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
  },
  "operators": [
    {
      "username": 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.profileuser.profile_readonly

Response 200

address object
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
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
extdev boolean
True if the merchant is extdev
legal_type object
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
vat_id string
Vat ID
vat_rates object
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": {
    "adyen_company": null,
    "adyen_merchant_code": null,
    "adyen_password": null,
    "adyen_user": null,
    "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-settingsuser.profileuser.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.profileuser.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

adyen_company string
Adyen company
adyen_merchant_code string
Adyen merchant code
adyen_password string
Adyen password
adyen_user string
Adyen username
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: UNAVAILABLEENFORCEDONOFF
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
{
  "adyen_company": null,
  "adyen_merchant_code": null,
  "adyen_password": null,
  "adyen_user": null,
  "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.profileuser.profile_readonly

Response 200

address object
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

Manage subaccounts.

The Sub-Account object

Attributes

created_at string required
Creation date of the operator
Example: "2022-12-11T13:46:00Z"
disabled boolean required
True if the subaccount is disabled.
id number required
ID of the sub-account
Example: 123
permissions object required
updated_at string required
Example: "2022-12-12T14:46:00Z"
username string required
Username of the operator
Example: "[email protected]"

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Subaccounts

List subaccounts

Scopes: user.subaccounts

Response 200

[]object

Show attributes

created_at string required
Creation date of the operator
Example: "2022-12-11T13:46:00Z"
disabled boolean required
True if the subaccount is disabled.
id number required
ID of the sub-account
Example: 123
permissions object required
updated_at string required
Example: "2022-12-12T14:46:00Z"
username string required
Username of the operator
Example: "[email protected]"

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/accounts
curl https://api.sumup.com/v0.1/me/accounts

[
  {
    "created_at": "2022-12-11T13:46:00Z",
    "disabled": false,
    "id": 123,
    "permissions": {
      "create_moto_payments": null,
      "create_referral": null,
      "full_transaction_history_view": null,
      "refund_transactions": null
    },
    "updated_at": "2022-12-12T14:46:00Z",
    "username": "[email protected]"
  }
]

Subaccounts

Create a subaccount

Scopes: user.subaccounts

Body Parameters

password string
Password
username string
Username of the new sub-account. Must be a valid email address.

Response 200

created_at string required
Creation date of the operator
Example: "2022-12-11T13:46:00Z"
disabled boolean required
True if the subaccount is disabled.
id number required
ID of the sub-account
Example: 123
permissions object required
updated_at string required
Example: "2022-12-12T14:46:00Z"
username string required
Username of the operator
Example: "[email protected]"

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.

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

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Subaccounts

Update a subaccount

Scopes: user.subaccounts

Path Parameters

operator_code string required

Body Parameters

password string
Password
username string
Username of the new sub-account. Must be a valid email address.

Response 200

created_at string required
Creation date of the operator
Example: "2022-12-11T13:46:00Z"
disabled boolean required
True if the subaccount is disabled.
id number required
ID of the sub-account
Example: 123
permissions object required
updated_at string required
Example: "2022-12-12T14:46:00Z"
username string required
Username of the operator
Example: "[email protected]"

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/me/accounts/{operator_code}
curl https://api.sumup.com/v0.1/me/accounts/{operator_code}

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "username": "[email protected]"
}

Subaccounts

Deactivate a subaccount

Scopes: user.subaccounts

Path Parameters

operator_code string required

Response 200

created_at string required
Creation date of the operator
Example: "2022-12-11T13:46:00Z"
disabled boolean required
True if the subaccount is disabled.
id number required
ID of the sub-account
Example: 123
permissions object required
updated_at string required
Example: "2022-12-12T14:46:00Z"
username string required
Username of the operator
Example: "[email protected]"

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/me/accounts/{operator_code}
curl https://api.sumup.com/v0.1/me/accounts/{operator_code}

{
  "created_at": "2022-12-11T13:46:00Z",
  "disabled": false,
  "id": 123,
  "permissions": {
    "create_moto_payments": null,
    "create_referral": null,
    "full_transaction_history_view": null,
    "refund_transactions": null
  },
  "updated_at": "2022-12-12T14:46:00Z",
  "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.

For a less detailed payouts list use List transactions.'

The Financial Payouts object

Attributes

[]object

Show attributes

amount number
currency string
date string
fee number
id integer
reference string
status string
Options: SUCCESSFULFAILED
transaction_code string
type string
Options: PAYOUTCHARGE_BACK_DEDUCTIONREFUND_DEDUCTIONDD_RETURN_DEDUCTIONBALANCE_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.profileuser.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: SUCCESSFULFAILED
transaction_code string
type string
Options: PAYOUTCHARGE_BACK_DEDUCTIONREFUND_DEDUCTIONDD_RETURN_DEDUCTIONBALANCE_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

List financial transactions

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

Scopes: user.profileuser.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
external_reference string
id string
timestamp string
transaction_code string
type string
Options: SALEREFUNDCHARGE_BACKDD_RETURNDD_RETURN_REVERSAL

error_code string
Platform code for the error.
message string
Short description of the error.

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

List financial transactions response
[
  {
    "amount": null,
    "currency": null,
    "external_reference": null,
    "id": null,
    "timestamp": null,
    "transaction_code": null,
    "type": null
  }
]

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}

NoBody
{}

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
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: ECOMRECURRINGBOLETO
Payment type used for the transaction.
status string
Options: SUCCESSFULCANCELLEDFAILEDPENDING
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_ENTRYBOLETO
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_PAYMENTTRUE_INSTALLMENTACCELERATED_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
events []object
List of events related to the transaction.
Show attributes
Close
Attributes
- amount number
- 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
- installment_number integer
  Consecutive number of the installment.
- status string
- timestamp string
- transaction_id string
- type string
horizontal_accuracy number
lat number
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
- lat number
- lon number
lon number
payout_type string
Options: BANK_ACCOUNTBALANCEPREPAID_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: MOTOCASHCC_SIGNATUREELVCC_CUSTOMER_ENTEREDMANUAL_ENTRYEMV
Simple name of the payment type.
simple_status string
Options: SUCCESSFULPAID_OUTCANCEL_FAILEDCANCELLEDCHARGEBACKFAILEDREFUND_FAILEDREFUNDEDNON_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
- date string
  Date when the transaction event occurred.
- due_date string
  Date when the transaction event is due to occur.
- event_type string
- id integer
- installment_number integer
  Consequtive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.
- status string
- timestamp string
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: nonesignatureoffline pinonline pinoffline pin + signatureconfirmation code verified
Verification method used for the transaction.

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/me/transactions
curl https://api.sumup.com/v0.1/me/transactions

Retrieve a transaction response
{
  "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,
  "payout_plan": null,
  "payouts_received": null,
  "payouts_total": null,
  "product_summary": null,
  "card": {
    "cvv": "123",
    "expiry_month": null,
    "expiry_year": "2023",
    "last_4_digits": "3456",
    "name": "FIRSTNAME LASTNAME",
    "number": "1234567890123456",
    "type": null,
    "zip_code": "12345"
  },
  "events": [
    {
      "amount": null,
      "deducted_amount": null,
      "deducted_fee_amount": null,
      "fee_amount": null,
      "id": null,
      "installment_number": null,
      "status": null,
      "timestamp": null,
      "transaction_id": null,
      "type": null
    }
  ],
  "horizontal_accuracy": null,
  "lat": null,
  "links": [
    null
  ],
  "local_time": null,
  "location": {
    "horizontal_accuracy": null,
    "lat": null,
    "lon": null
  },
  "lon": null,
  "payout_type": null,
  "products": [
    {
      "name": null,
      "price": null,
      "price_with_vat": null,
      "quantity": null,
      "single_vat_amount": null,
      "total_price": null,
      "total_with_vat": null,
      "vat_amount": null,
      "vat_rate": null
    }
  ],
  "simple_payment_type": null,
  "simple_status": null,
  "tax_enabled": null,
  "transaction_events": [
    {
      "amount": null,
      "date": null,
      "due_date": null,
      "event_type": null,
      "id": null,
      "installment_number": null,
      "status": null,
      "timestamp": null
    }
  ],
  "username": null,
  "vat_rates": [
    null
  ],
  "verification_method": null
}

Transactions

List transactions

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

Scopes: transactions.history

Query Parameters

transaction_code string
order string
limit integer
users []string
statuses []string
payment_types []string
types []string
changes_since string
newest_time string
newest_ref string
oldest_time string
oldest_ref string

Response 200

items []object
Show attributes
Close
Attributes
- amount number
  Total amount of the transaction.
  Example: 10.1
- currency string
- 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: ECOMRECURRINGBOLETO
  Payment type used for the transaction.
- status string
  Options: SUCCESSFULCANCELLEDFAILEDPENDING
  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"
- payout_plan string
  Options: SINGLE_PAYMENTTRUE_INSTALLMENTACCELERATED_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_type string
  Options: VISAAMEXCUPDINERSDISCOVERELOELVHIPERCARDJCBMAESTROMASTERCARDVISA_ELECTRONVISA_VPAYUNKNOWN
  Issuing card network of the payment card used for the transaction.
- transaction_id string
- type string
  Options: PAYMENTREFUNDCHARGE_BACK
  Type of the transaction for the registered user specified in the user property.
- user string
  Email address of the registered user (merchant) to whom the payment is made.
links []object
Show attributes
Close
Attributes
- href string
  URL for accessing the related resource.
- rel string
  Specifies the relation to the current resource.
- type string
  Specifies the media type of the related resource.

error_code string
Platform code for the error.
message string
Short description of the error.

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

List transactions response
{
  "items": [
    {
      "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",
      "payout_plan": null,
      "payouts_received": null,
      "payouts_total": null,
      "product_summary": null,
      "card_type": null,
      "transaction_id": null,
      "type": null,
      "user": null
    }
  ],
  "links": [
    {
      "href": null,
      "rel": null,
      "type": null
    }
  ]
}

API Keys

API Keys allow your application to gain programmatic access to SumUp. API Keys allow application to do authorized requests within the SumUp ecosystem. API Keys are scopes to single account and thus can't be used for endpoints where user presence is needed (for such endpoints it is necessary to use OAuth2).

The API Key object

Attributes

created_at string required
Example: "2023-01-20T15:16:17Z"
id string required
Unique identifier of the API Key.
Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
name string required
User-assigned name of the API Key.
Example: "My API Key"
plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
preview string required
Last 8 characters of the API key.
Example: "p6cL1vyZ"
scopes []string required
type string required
Options: publicsecret
Example: "secret"
updated_at string required
Example: "2023-01-20T15:16:17Z"

The API Key object
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}

API Keys

List API keys

Returns paginated list of API keys.

Scopes: api_keys

Path Parameters

merchant_code string required

Query Parameters

offset integer
limit integer

Response 200

items []object required
Show attributes
Close
Attributes
- created_at string required
  Example: "2023-01-20T15:16:17Z"
- id string required
  Unique identifier of the API Key.
  Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
- name string required
  User-assigned name of the API Key.
  Example: "My API Key"
- plaintext string
  The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
  Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
- preview string required
  Last 8 characters of the API key.
  Example: "p6cL1vyZ"
- scopes []string required
- type string required
  Options: publicsecret
  Example: "secret"
- updated_at string required
  Example: "2023-01-20T15:16:17Z"
total_count integer required

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

List API keys response
{
  "items": [
    {
      "created_at": "2023-03-24T10:10:10Z",
      "id": "sup_pk_1tpmgizNLHMkx1DdKd2hdzorZAaf6AcZ9",
      "name": "",
      "preview": "Aaf6AcZ9",
      "scopes": [],
      "type": "public",
      "updated_at": "2023-03-24T10:10:10Z"
    },
    {
      "created_at": "2023-03-25T09:10:10Z",
      "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
      "name": "Test Key",
      "preview": "TGhqew1b",
      "scopes": [
        "transactions.history",
        "user.app-settings",
        "user.profile_readonly",
        "user.profile",
        "user.subaccounts",
        "user.payout-settings",
        "products",
        "payments",
        "payment_instruments",
        "terminals.read",
        "terminals.write"
      ],
      "type": "secret",
      "updated_at": "2023-03-25T09:10:10Z"
    }
  ],
  "total_count": 2
}

API Keys

Create an API key

Creates a new API key for the user.

Scopes: api_keys:write

Path Parameters

merchant_code string required

Body Parameters

name string required
Example: "New Key Name"
scopes []string required

Response 201

created_at string required
Example: "2023-01-20T15:16:17Z"
id string required
Unique identifier of the API Key.
Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
name string required
User-assigned name of the API Key.
Example: "My API Key"
plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
preview string required
Last 8 characters of the API key.
Example: "p6cL1vyZ"
scopes []string required
type string required
Options: publicsecret
Example: "secret"
updated_at string required
Example: "2023-01-20T15:16:17Z"

post 
/v0.1/merchants/{merchant_code}/api-keys
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys

Create an API key response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}

API Keys

Retrieve an API Key

Gets an API key.

Scopes: api_keys

Path Parameters

merchant_code string required
key_id string required

Response 200

created_at string required
Example: "2023-01-20T15:16:17Z"
id string required
Unique identifier of the API Key.
Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
name string required
User-assigned name of the API Key.
Example: "My API Key"
plaintext string
The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.
Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
preview string required
Last 8 characters of the API key.
Example: "p6cL1vyZ"
scopes []string required
type string required
Options: publicsecret
Example: "secret"
updated_at string required
Example: "2023-01-20T15:16:17Z"

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

Retrieve an API Key response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}

API Keys

Update an API key

Updates an API key.

Scopes: api_keys:write

Path Parameters

merchant_code string required
key_id string required

Body Parameters

name string required
New name for the API key.
Example: "My API Key"
scopes []string required

put 
/v0.1/merchants/{merchant_code}/api-keys/{key_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}

API Keys

Revoke an API key

Revokes an API key.

Scopes: api_keys:write

Path Parameters

merchant_code string required
key_id string required

delete 
/v0.1/merchants/{merchant_code}/api-keys/{key_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}

Receipts

The Receipts model obtains receipt-like details for specific transactions.

The Receipt object

Attributes

acquirer_data object
Show attributes
Close
Attributes
- authorization_code string
- local_time string
- return_code string
- tid string
emv_data object
Show attributes
Close
Attributes
merchant_data object
transaction_data object

The Receipt object
{
  "acquirer_data": {
    "authorization_code": null,
    "local_time": null,
    "return_code": null,
    "tid": null
  },
  "emv_data": {},
  "merchant_data": {
    "locale": null,
    "merchant_profile": {
      "address": {
        "address_line1": null,
        "city": null,
        "country": null,
        "country_en_name": null,
        "country_native_name": null,
        "landline": null,
        "post_code": null
      },
      "business_name": null,
      "email": null,
      "merchant_code": null
    }
  },
  "transaction_data": {
    "amount": null,
    "card": {
      "last_4_digits": null,
      "type": null
    },
    "currency": null,
    "entry_mode": null,
    "events": [
      {
        "amount": null,
        "id": null,
        "receipt_no": null,
        "status": null,
        "timestamp": null,
        "transaction_id": null,
        "type": null
      }
    ],
    "installments_count": null,
    "payment_type": null,
    "products": [
      {
        "description": null,
        "name": null,
        "price": null,
        "quantity": null,
        "total_price": null
      }
    ],
    "receipt_no": null,
    "status": null,
    "timestamp": null,
    "tip_amount": null,
    "transaction_code": null,
    "vat_amount": null,
    "vat_rates": [
      {
        "gross": null,
        "net": null,
        "rate": null,
        "vat": null
      }
    ],
    "verification_method": null
  }
}

Receipts

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Scopes:

Path Parameters

id string required

Query Parameters

mid string required
tx_event_id integer

Response 200

acquirer_data object
Show attributes
Close
Attributes
- authorization_code string
- local_time string
- return_code string
- tid string
emv_data object
Show attributes
Close
Attributes
merchant_data object
transaction_data object

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 
/v1.1/receipts/{id}
curl https://api.sumup.com/v1.1/receipts/{id}

Retrieve receipt details response
{
  "acquirer_data": {
    "authorization_code": null,
    "local_time": null,
    "return_code": null,
    "tid": null
  },
  "emv_data": {},
  "merchant_data": {
    "locale": null,
    "merchant_profile": {
      "address": {
        "address_line1": null,
        "city": null,
        "country": null,
        "country_en_name": null,
        "country_native_name": null,
        "landline": null,
        "post_code": null
      },
      "business_name": null,
      "email": null,
      "merchant_code": null
    }
  },
  "transaction_data": {
    "amount": null,
    "card": {
      "last_4_digits": null,
      "type": null
    },
    "currency": null,
    "entry_mode": null,
    "events": [
      {
        "amount": null,
        "id": null,
        "receipt_no": null,
        "status": null,
        "timestamp": null,
        "transaction_id": null,
        "type": null
      }
    ],
    "installments_count": null,
    "payment_type": null,
    "products": [
      {
        "description": null,
        "name": null,
        "price": null,
        "quantity": null,
        "total_price": null
      }
    ],
    "receipt_no": null,
    "status": null,
    "timestamp": null,
    "tip_amount": null,
    "transaction_code": null,
    "vat_amount": null,
    "vat_rates": [
      {
        "gross": null,
        "net": null,
        "rate": null,
        "vat": null
      }
    ],
    "verification_method": null
  }
}

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

Create a payment instrument

Path Parameters

Body Parameters

Response 201