SumUp REST API

SumUp’s REST API operates with JSON HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard HTTP response codes.

You can experiment and work on your integration in a sandbox that doesn't affect your regular data and doesn't process real transactions. To create a sandbox merchant account visit the dashboard. To use the sandbox when interacting with SumUp APIs create an API key and use it for authentication.

Server URL
 https://api.sumup.com 

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

checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
amount number

Amount of the payment.

Example: 10.1
currency string

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

Example: "EUR"
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

Unique identifying code of the merchant profile.
description string

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

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
status string

Options: PENDING FAILED PAID

Current status of the checkout.
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"
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"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
mandate object

Created mandate
Show attributes
Close

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

List of transactions related to the payment.
Show attributes
Close

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

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

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

checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
amount number

Amount of the payment.

Example: 10.1
currency string

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

Example: "EUR"
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

Unique identifying code of the merchant profile.
description string

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

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
status string

Options: PENDING FAILED PAID

Current status of the checkout.
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"
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"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
mandate object

Created mandate
Show attributes
Close

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

List of transactions related to the payment.
Show attributes
Close

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

Name of the merchant

Example: "Sample Merchant"
redirect_url string

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

Example: "https://mysite.com/completed_purchase"
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"

message string

Short description of the error.
error_code string

Platform code for the error.

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

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

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

checkout_reference string required

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
amount number required

Amount of the payment.
currency string required

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

Example: "EUR"
merchant_code string required

Unique identifying code of the merchant profile.
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

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

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

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

Options: CHECKOUT SETUP_RECURRING_PAYMENT

Purpose of the checkout.
id string

Unique ID of the checkout resource.
status string

Options: PENDING FAILED PAID

Current status of the checkout.
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"
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"
transactions []object

List of transactions related to the payment.
Show attributes
Close

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

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

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

Response 201

checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
amount number

Amount of the payment.

Example: 10.1
currency string

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

Example: "EUR"
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

Unique identifying code of the merchant profile.
description string

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

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
status string

Options: PENDING FAILED PAID

Current status of the checkout.
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"
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"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
mandate object

Created mandate
Show attributes
Close

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

List of transactions related to the payment.
Show attributes
Close

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

message string

Short description of the error.
error_code string

Platform code for 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.

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

message string

Short description of the error.
error_code string

Platform code for the error.

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

Standard response body for a successfully created checkout

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

Response body for a successfully created 3DS checkout

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

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

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

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

checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
amount number

Amount of the payment.

Example: 10.1
currency string

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

Example: "EUR"
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

Unique identifying code of the merchant profile.
description string

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

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
status string

Options: PENDING FAILED PAID

Current status of the checkout.
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"
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"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
mandate object

Created mandate
Show attributes
Close

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

List of transactions related to the payment.
Show attributes
Close

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

Name of the merchant

Example: "Sample Merchant"
redirect_url string

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

Example: "https://mysite.com/completed_purchase"
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"

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.

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

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

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

payment_type string required

Options: card boleto ideal blik bancontact

Describes the payment method used to attempt processing
installments integer

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

Mandate is passed when a card is to be tokenized
Show attributes
Close

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

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

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

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

Required when token is provided. Unique ID of the customer.
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

Response 200

checkout_reference string

Unique ID of the payment checkout specified by the client application when creating the checkout resource.
amount number

Amount of the payment.

Example: 10.1
currency string

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

Example: "EUR"
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

Unique identifying code of the merchant profile.
description string

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

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

Unique ID of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
status string

Options: PENDING FAILED PAID

Current status of the checkout.
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"
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"
customer_id string

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

Example: "831ff8d4cd5958ab5670"
mandate object

Created mandate
Show attributes
Close

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

List of transactions related to the payment.
Show attributes
Close

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

Name of the merchant

Example: "Sample Merchant"
redirect_url string

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

Example: "https://mysite.com/completed_purchase"
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"

Response 202

next_step object

Required action processing 3D Secure payments.
Show attributes
Close

Attributes
- url string
  
  Where the end user is redirected.
  
  Example: "https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A"
- method string
  
  Method used to complete the redirect.
  
  Example: "POST"
- redirect_url string
  
  Refers to a url where the end user is redirected once the payment processing completes.
  
  Example: "https://mysite.com/completed_purchase"
- mechanism []string
  
  Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either.
  
  Show attributes
  
  Close
  
  Attributes
- payload object
  
  Contains parameters essential for form redirection. Number of object keys and their content can vary.
  
  Show attributes
  
  Close
  
  Attributes
  
  PaReq
  
  Example: "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw=="
  
  MD
  
  Example: "b1a536c0-29b9-11eb-adc1-0242ac120002"
  
  TermUrl
  
  Example: "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment"

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

Platform code for the error.

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

Successfully processed checkout with a card

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

Successfully processed checkout with a token

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

Successfully processed checkout with Boleto

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

Successfully processed checkout with iDeal

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

Successfully processed checkout with Bancontact

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

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

checkout_reference string

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

Unique ID of the checkout resource.
amount number

Amount of the payment.
currency string

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

Example: "EUR"
pay_to_email string

pay_to_email is deprecated, use merchant_code instead.

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

Unique identifying code of the merchant profile.
description string

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

Options: SETUP_RECURRING_PAYMENT CHECKOUT

Purpose of the checkout creation initially
status string

Options: EXPIRED

Current status of the checkout.
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"
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

Merchant name
merchant_country string

The merchant's country
transactions []object

List of transactions related to the payment.
Show attributes
Close

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

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

Platform code for the error.

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

Response body for a successfully deactivated checkout

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

Checkouts

Get available payment methods

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

Scopes: payments

Path Parameters

merchant_code string required

Example: M1234

Query Parameters

amount number

Example: 9.99
currency string

Example: EUR

Response 200

available_payment_methods []object
Show attributes
Close

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

title string

Short title of the error.
details string

Details of the error.
status number

The status code.
failed_constraints []object
Show attributes
Close

Attributes
- message string
- reference string

message string

Short description of the error.
error_code string

Platform code for the error.

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

Available payment methods

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

Customers

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

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

The Customer object

Attributes

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

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

Customers

Create a customer

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

Scopes: payment_instruments

Body Parameters

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

Response 201

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

message string

Short description of the error.
error_code string

Platform code for the error.

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

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

Customers

Retrieve a customer

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

Scopes: payment_instruments

Path Parameters

customer_id string required

Response 200

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

message string

Short description of the error.
error_code string

Platform code for the error.

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

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

Customers

Update a customer

Updates an identified saved customer resource's personal details.

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

Scopes: payment_instruments

Path Parameters

customer_id string required

Body Parameters

personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

Response 200

customer_id string required

Unique ID of the customer.

Example: "831ff8d4cd5958ab5670"
personal_details object

Personal details for the customer.
Show attributes
Close

Attributes
- first_name string
  
  First name of the customer.
  
  Example: "John"
- last_name string
  
  Last name of the customer.
  
  Example: "Doe"
- email string
  
  Email address of the customer.
  
  Example: "[email protected]"
- phone string
  
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_date string
  
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_id string
  
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- address object
  
  Profile's personal address information.
  
  Show attributes
  
  Close
  
  Attributes
  
  city string
  
  City name from the address.
  
  Example: "Berlin"
  
  country string
  
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  
  line_1 string
  
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  
  line_2 string
  
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  
  postal_code string
  
  Postal code from the address.
  
  Example: "10115"
  
  state string
  
  State name or abbreviation from the address.
  
  Example: "Berlin"

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

message string

Short description of the error.
error_code string

Platform code for the error.

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

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

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

token string

Unique token identifying the saved payment card for a customer.
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.
type string

Options: card

Type of the payment instrument.
card object

Details of the payment card.
Show attributes
Close

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

Created mandate
Show attributes
Close

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

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

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

message string

Short description of the error.
error_code string

Platform code for 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
 [
  {
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "active": true,
    "type": "card",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MDASYTPD"
    },
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00"
  }
] 

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

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

message string

Short description of the error.
error_code string

Platform code for the error.

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

{}

Transactions

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

Transactions

Refund a transaction

Refunds an identified transaction either in full or partially.

Scopes: payments

Path Parameters

txn_id string required

Body Parameters

amount number

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

Response 204

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.

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

{}

Transactions

Retrieve a transaction

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

id
internal_id
transaction_code
foreign_transaction_id
client_transaction_id

Scopes: transactions.history

Path Parameters

merchant_code string required

Example: MC0X0ABC

Query Parameters

id string
internal_id string
transaction_code string

Response 200

id string

Unique ID of the transaction.

Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
transaction_code string

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

Example: "TEENSK4W2K"
amount number

Total amount of the transaction.

Example: 10.1
currency string

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

Example: "EUR"
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"
status string

Options: SUCCESSFUL CANCELLED FAILED PENDING

Current status of the transaction.
payment_type string

Options: ECOM RECURRING BOLETO

Payment type used for the transaction.
installments_count integer

Current number of the installment for deferred payments.
merchant_code string

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

Example: "MH4H92C7"
vat_amount number

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

Example: 6
tip_amount number

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

Example: 3
entry_mode string

Options: CUSTOMER_ENTRY BOLETO

Entry mode of the payment details.
auth_code string

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

Example: "053201"
internal_id integer

Internal unique ID of the transaction on the SumUp platform.

Example: 1763892018
product_summary string

Short description of the payment. The value is taken from the description property of the related checkout resource.
payouts_total integer

Total number of payouts to the registered user specified in the user property.
payouts_received integer

Number of payouts that are made to the registered user specified in the user property.
payout_plan string

Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

Payout plan of the registered user at the time when the transaction was made.
username string

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

Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
lon number

Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
horizontal_accuracy number

Indication of the precision of the geographical position received from the payment terminal.
simple_payment_type string

Options: MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

Simple name of the payment type.
verification_method string

Options: none signature offline pin online pin offline pin + signature confirmation code verified

Verification method used for the transaction.
card object

Details of the payment card.
Show attributes
Close

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

Local date and time of the creation of the transaction.
payout_type string

Options: BANK_ACCOUNT BALANCE PREPAID_CARD

Payout type for the transaction.
products []object

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

Attributes
- name string
  
  Name of the product from the merchant's catalog.
- price number
  
  Price of the product without VAT.
- vat_rate number
  
  VAT rate applicable to the product.
- 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).
- price_with_vat number
  
  Price of a single product item with VAT.
- 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).
- quantity number
  
  Number of product items for the purchase.
- 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_rates []object

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

Attributes
transaction_events []object

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

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

Options: SUCCESSFUL PAID_OUT CANCEL_FAILED CANCELLED CHARGEBACK FAILED REFUND_FAILED REFUNDED NON_COLLECTION

Status generated from the processing status and the latest transaction state.
links []object

List of hyperlinks for accessing related resources.
Show attributes
Close

Attributes
events []object

List of events related to the transaction.
Show attributes
Close

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

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

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

Indicates whether tax deduction is enabled for the transaction.

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.

 get 
 /v2.1/merchants/{merchant_code}/transactions  
 curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions 

Retrieve a transaction response
 {
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": null,
  "payment_type": null,
  "installments_count": null,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": null,
  "auth_code": "053201",
  "internal_id": 1763892018,
  "product_summary": null,
  "payouts_total": null,
  "payouts_received": null,
  "payout_plan": null,
  "username": null,
  "lat": null,
  "lon": null,
  "horizontal_accuracy": null,
  "simple_payment_type": null,
  "verification_method": null,
  "card": {
    "last_4_digits": "3456",
    "type": null
  },
  "local_time": null,
  "payout_type": null,
  "products": [
    {
      "name": null,
      "price": null,
      "vat_rate": null,
      "single_vat_amount": null,
      "price_with_vat": null,
      "vat_amount": null,
      "quantity": null,
      "total_price": null,
      "total_with_vat": null
    }
  ],
  "vat_rates": [
    null
  ],
  "transaction_events": [
    {
      "id": null,
      "event_type": null,
      "status": null,
      "amount": null,
      "due_date": null,
      "date": null,
      "installment_number": null,
      "timestamp": null
    }
  ],
  "simple_status": null,
  "links": [
    null
  ],
  "events": [
    {
      "id": null,
      "transaction_id": null,
      "type": null,
      "status": null,
      "amount": null,
      "timestamp": null,
      "fee_amount": null,
      "installment_number": null,
      "deducted_amount": null,
      "deducted_fee_amount": null
    }
  ],
  "location": {
    "lat": null,
    "lon": null,
    "horizontal_accuracy": null
  },
  "tax_enabled": null
} 

Transactions

List transactions

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

Scopes: transactions.history

Path Parameters

merchant_code string required

Example: MC0X0ABC

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
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- 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"
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- installments_count integer
  
  Current number of the installment for deferred payments.
- product_summary string
  
  Short description of the payment. The value is taken from the description property of the related checkout resource.
- payouts_total integer
  
  Total number of payouts to the registered user specified in the user property.
- payouts_received integer
  
  Number of payouts that are made to the registered user specified in the user property.
- payout_plan string
  
  Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT
  
  Payout plan of the registered user at the time when the transaction was made.
- transaction_id string
  
  Unique ID of the transaction.
- client_transaction_id string
  
  Client-specific ID of the transaction.
- user string
  
  Email address of the registered user (merchant) to whom the payment is made.
- type string
  
  Options: PAYMENT REFUND CHARGE_BACK
  
  Type of the transaction for the registered user specified in the user property.
- card_type string
  
  Options: VISA AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card used for the transaction.
links []object
Show attributes
Close

Attributes
- rel string
  
  Specifies the relation to the current resource.
- href string
  
  URL for accessing the related resource.
- type string
  
  Specifies the media type of the related resource.

message string

Short description of the error.
error_code string

Platform code for the error.

 get 
 /v2.1/merchants/{merchant_code}/transactions/history  
 curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions/history 

List transactions response
 {
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null
    }
  ],
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ]
} 

Transactions

Retrieve a transaction
Deprecated

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

id string

Unique ID of the transaction.

Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
transaction_code string

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

Example: "TEENSK4W2K"
amount number

Total amount of the transaction.

Example: 10.1
currency string

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

Example: "EUR"
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"
status string

Options: SUCCESSFUL CANCELLED FAILED PENDING

Current status of the transaction.
payment_type string

Options: ECOM RECURRING BOLETO

Payment type used for the transaction.
installments_count integer

Current number of the installment for deferred payments.
merchant_code string

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

Example: "MH4H92C7"
vat_amount number

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

Example: 6
tip_amount number

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

Example: 3
entry_mode string

Options: CUSTOMER_ENTRY BOLETO

Entry mode of the payment details.
auth_code string

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

Example: "053201"
internal_id integer

Internal unique ID of the transaction on the SumUp platform.

Example: 1763892018
product_summary string

Short description of the payment. The value is taken from the description property of the related checkout resource.
payouts_total integer

Total number of payouts to the registered user specified in the user property.
payouts_received integer

Number of payouts that are made to the registered user specified in the user property.
payout_plan string

Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

Payout plan of the registered user at the time when the transaction was made.
username string

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

Latitude value from the coordinates of the payment location (as received from the payment terminal reader).
lon number

Longitude value from the coordinates of the payment location (as received from the payment terminal reader).
horizontal_accuracy number

Indication of the precision of the geographical position received from the payment terminal.
simple_payment_type string

Options: MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

Simple name of the payment type.
verification_method string

Options: none signature offline pin online pin offline pin + signature confirmation code verified

Verification method used for the transaction.
card object

Details of the payment card.
Show attributes
Close

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

Local date and time of the creation of the transaction.
payout_type string

Options: BANK_ACCOUNT BALANCE PREPAID_CARD

Payout type for the transaction.
products []object

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

Attributes
- name string
  
  Name of the product from the merchant's catalog.
- price number
  
  Price of the product without VAT.
- vat_rate number
  
  VAT rate applicable to the product.
- 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).
- price_with_vat number
  
  Price of a single product item with VAT.
- 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).
- quantity number
  
  Number of product items for the purchase.
- 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_rates []object

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

Attributes
transaction_events []object

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

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

Options: SUCCESSFUL PAID_OUT CANCEL_FAILED CANCELLED CHARGEBACK FAILED REFUND_FAILED REFUNDED NON_COLLECTION

Status generated from the processing status and the latest transaction state.
links []object

List of hyperlinks for accessing related resources.
Show attributes
Close

Attributes
events []object

List of events related to the transaction.
Show attributes
Close

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

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

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

Indicates whether tax deduction is enabled for the transaction.

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.

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

Retrieve a transaction response
 {
  "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
  "transaction_code": "TEENSK4W2K",
  "amount": 10.1,
  "currency": "EUR",
  "timestamp": "2020-02-29T10:56:56.876Z",
  "status": null,
  "payment_type": null,
  "installments_count": null,
  "merchant_code": "MH4H92C7",
  "vat_amount": 6,
  "tip_amount": 3,
  "entry_mode": null,
  "auth_code": "053201",
  "internal_id": 1763892018,
  "product_summary": null,
  "payouts_total": null,
  "payouts_received": null,
  "payout_plan": null,
  "username": null,
  "lat": null,
  "lon": null,
  "horizontal_accuracy": null,
  "simple_payment_type": null,
  "verification_method": null,
  "card": {
    "last_4_digits": "3456",
    "type": null
  },
  "local_time": null,
  "payout_type": null,
  "products": [
    {
      "name": null,
      "price": null,
      "vat_rate": null,
      "single_vat_amount": null,
      "price_with_vat": null,
      "vat_amount": null,
      "quantity": null,
      "total_price": null,
      "total_with_vat": null
    }
  ],
  "vat_rates": [
    null
  ],
  "transaction_events": [
    {
      "id": null,
      "event_type": null,
      "status": null,
      "amount": null,
      "due_date": null,
      "date": null,
      "installment_number": null,
      "timestamp": null
    }
  ],
  "simple_status": null,
  "links": [
    null
  ],
  "events": [
    {
      "id": null,
      "transaction_id": null,
      "type": null,
      "status": null,
      "amount": null,
      "timestamp": null,
      "fee_amount": null,
      "installment_number": null,
      "deducted_amount": null,
      "deducted_fee_amount": null
    }
  ],
  "location": {
    "lat": null,
    "lon": null,
    "horizontal_accuracy": null
  },
  "tax_enabled": null
} 

Transactions

List transactions
Deprecated

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
- id string
  
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_code string
  
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amount number
  
  Total amount of the transaction.
  
  Example: 10.1
- currency string
  
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- 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"
- status string
  
  Options: SUCCESSFUL CANCELLED FAILED PENDING
  
  Current status of the transaction.
- payment_type string
  
  Options: ECOM RECURRING BOLETO
  
  Payment type used for the transaction.
- installments_count integer
  
  Current number of the installment for deferred payments.
- product_summary string
  
  Short description of the payment. The value is taken from the description property of the related checkout resource.
- payouts_total integer
  
  Total number of payouts to the registered user specified in the user property.
- payouts_received integer
  
  Number of payouts that are made to the registered user specified in the user property.
- payout_plan string
  
  Options: SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT
  
  Payout plan of the registered user at the time when the transaction was made.
- transaction_id string
  
  Unique ID of the transaction.
- client_transaction_id string
  
  Client-specific ID of the transaction.
- user string
  
  Email address of the registered user (merchant) to whom the payment is made.
- type string
  
  Options: PAYMENT REFUND CHARGE_BACK
  
  Type of the transaction for the registered user specified in the user property.
- card_type string
  
  Options: VISA AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA_ELECTRON VISA_VPAY UNKNOWN
  
  Issuing card network of the payment card used for the transaction.
links []object
Show attributes
Close

Attributes
- rel string
  
  Specifies the relation to the current resource.
- href string
  
  URL for accessing the related resource.
- type string
  
  Specifies the media type of the related resource.

message string

Short description of the error.
error_code string

Platform code for the error.

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

List transactions response
 {
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null
    }
  ],
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ]
} 

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Attributes

account object

Profile information.
Show attributes
Close

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

Account's personal profile.
Show attributes
Close

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

Account's merchant profile
Show attributes
Close

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

Mobile app settings
Show attributes
Close

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

User permissions
Show attributes
Close

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

Merchant comes from payleven BR migration

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

Merchant

Retrieve a profile

Returns user profile information.

Scopes: user.profile user.profile_readonly

Query Parameters

include[] []string

Response 200

account object

Profile information.
Show attributes
Close

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

Account's personal profile.
Show attributes
Close

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

Account's merchant profile
Show attributes
Close

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

Mobile app settings
Show attributes
Close

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

User permissions
Show attributes
Close

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

Merchant comes from payleven BR migration

message string

Short description of the error.
error_code string

Platform code for the error.

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

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

Merchant

Retrieve a personal profile

Retrieves personal profile data.

Scopes: user.profile user.profile_readonly

Response 200

first_name string

First name of the user
last_name string

Last name of the user
date_of_birth string

Date of birth
mobile_phone string

Mobile phone number
address object

Details of the registered address.
Show attributes
Close

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

message string

Short description of the error.
error_code string

Platform code for the error.

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

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

Merchant

Retrieve a merchant profile

Retrieves merchant profile data.

Scopes: user.profile user.profile_readonly

Response 200

merchant_code string

Unique identifying code of the merchant profile
company_name string

Company name
website string

Website
legal_type object

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

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

Merchant category code
mobile_phone string

Mobile phone number
company_registration_number string

Company registration number
vat_id string

Vat ID
permanent_certificate_access_code string

Permanent certificate access code (Portugal)
nature_and_purpose string

Nature and purpose of the business
address object

Details of the registered address.
Show attributes
Close

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

Business owners information.
doing_business_as object

Doing Business As information
Show attributes
Close

Attributes
- business_name string
  
  Doing business as name
- company_registration_number string
  
  Doing business as company registration number
- vat_id string
  
  Doing business as VAT ID
- website string
  
  Doing business as website
- email string
  
  Doing business as email
- 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
  
  region_id number
  
  Country region ID
  
  region_name string
  
  Country region name
  
  post_code string
  
  Postal code
settings object

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

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

Merchant VAT rates
Show attributes
Close

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

Merchant locale (for internal usage only)
bank_accounts []object
Show attributes
Close

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

True if the merchant is extdev
payout_zone_migrated boolean

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

Merchant country code formatted according to ISO3166-1 alpha-2 (for internal usage only)

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

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

Merchant

Get settings

Retrieves merchant settings.

Scopes: user.payout-settings

Response 200

tax_enabled boolean

Whether to show tax in receipts (saved per transaction)
payout_type string

Payout type
payout_period string

Payout frequency
payout_on_demand_available boolean

Whether merchant can edit payouts on demand
payout_on_demand boolean

Whether merchant will receive payouts on demand
printers_enabled boolean

Whether to show printers in mobile app
payout_instrument string

Payout Instrument
moto_payment string

Options: UNAVAILABLE ENFORCED ON OFF

Whether merchant can make MOTO payments
stone_merchant_code string

Stone merchant code
daily_payout_email boolean

Whether merchant will receive daily payout emails
monthly_payout_email boolean

Whether merchant will receive monthly payout emails
gross_settlement boolean

Whether merchant has gross settlement enabled

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for 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
 {
  "tax_enabled": null,
  "payout_type": null,
  "payout_period": null,
  "payout_on_demand_available": null,
  "payout_on_demand": null,
  "printers_enabled": null,
  "payout_instrument": null,
  "moto_payment": null,
  "stone_merchant_code": null,
  "daily_payout_email": null,
  "monthly_payout_email": null,
  "gross_settlement": null
} 

Merchant

Retrieve DBA

Retrieves Doing Business As profile.

Scopes: user.profile user.profile_readonly

Response 200

business_name string

Doing business as name
company_registration_number string

Doing business as company registration number
vat_id string

Doing business as VAT ID
website string

Doing business as website
email string

Doing business as email
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
- region_id number
  
  Country region ID
- region_name string
  
  Country region name
- post_code string
  
  Postal code

message string

Short description of the error.
error_code string

Platform code for 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
 {
  "business_name": null,
  "company_registration_number": null,
  "vat_id": null,
  "website": null,
  "email": null,
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "region_id": null,
    "region_name": null,
    "post_code": null
  }
} 

Merchant

List bank accounts

Retrieves bank accounts of the merchant.

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

Path Parameters

merchant_code string required

Example: MC0X0ABC

Query Parameters

primary boolean

Response 200

[]object

Show attributes

bank_code string

Bank code
branch_code string

Branch code
swift string

SWIFT code
account_number string

Account number
iban string

IBAN
account_type string

Type of the account
account_category string

Account category - business or personal
account_holder_name string
status string

Status in the verification process
primary boolean

The primary bank account is the one used for payouts
created_at string

Creation date of the bank account
bank_name string

Bank name

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for the error.
status_code string

HTTP status code for the error.

 get 
 /v1.1/merchants/{merchant_code}/bank-accounts  
 curl https://api.sumup.com/v1.1/merchants/{merchant_code}/bank-accounts 

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

Merchant

List bank accounts
Deprecated

Retrieves bank accounts of the merchant.

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

Query Parameters

primary boolean

Response 200

[]object

Show attributes

bank_code string

Bank code
branch_code string

Branch code
swift string

SWIFT code
account_number string

Account number
iban string

IBAN
account_type string

Type of the account
account_category string

Account category - business or personal
account_holder_name string
status string

Status in the verification process
primary boolean

The primary bank account is the one used for payouts
created_at string

Creation date of the bank account
bank_name string

Bank name

message string

Short description of the error.
error_code string

Platform code for the error.

error_message string

Short description of the error.
error_code string

Platform code for 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
 [
  {
    "bank_code": null,
    "branch_code": null,
    "swift": null,
    "account_number": null,
    "iban": null,
    "account_type": null,
    "account_category": null,
    "account_holder_name": null,
    "status": null,
    "primary": null,
    "created_at": null,
    "bank_name": null
  }
] 

Payouts

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

The Financial Payouts object

Attributes

[]object

Show attributes

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

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

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

Payouts

List payouts

Lists ordered payouts for the merchant profile.

Scopes: user.profile user.profile_readonly

Path Parameters

merchant_code string required

Example: MC0X0ABC

Query Parameters

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

Response 200

[]object

Show attributes

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

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

message string

Short description of the error.
error_code string

Platform code for the error.

 get 
 /v1.0/merchants/{merchant_code}/payouts  
 curl https://api.sumup.com/v1.0/merchants/{merchant_code}/payouts 

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

Payouts

List payouts
Deprecated

Lists ordered payouts for the merchant profile.

Scopes: user.profile user.profile_readonly

Query Parameters

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

Response 200

[]object

Show attributes

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

Options: SUCCESSFUL FAILED
transaction_code string
type string

Options: PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION

message string

Short description of the error.
error_code string

Platform code for 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
  }
] 

Receipts

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

The Receipt object

Attributes

transaction_data object

Transaction information.
Show attributes
Close

Attributes
- transaction_code string
  
  Transaction code.
- amount string
  
  Transaction amount.
- vat_amount string
  
  Transaction VAT amount.
- tip_amount string
  
  Tip amount (included in transaction amount).
- currency string
  
  Transaction currency.
- timestamp string
  
  Time created at.
- status string
  
  Transaction processing status.
- payment_type string
  
  Transaction type.
- entry_mode string
  
  Transaction entry mode.
- verification_method string
  
  Cardholder verification method.
- card object
  
  Show attributes
  
  Close
  
  Attributes
  
  last_4_digits string
  
  Card last 4 digits.
  
  type string
  
  Card Scheme.
- installments_count integer
  
  Number of installments.
- products []object
  
  Products
  
  Show attributes
  
  Close
  
  Attributes
  
  name string
  
  Product name.
  
  description string
  
  Product description.
  
  price number
  
  Product price.
  
  quantity integer
  
  Product quantity.
  
  total_price number
  
  Quantity x product price.
- vat_rates []object
  
  Vat rates.
  
  Show attributes
  
  Close
  
  Attributes
  
  gross number
  
  Gross
  
  net number
  
  Net
  
  rate number
  
  Rate
  
  vat number
  
  Vat
- events []object
  
  Events
  
  Show attributes
  
  Close
  
  Attributes
  
  id integer
  
  Unique ID of the transaction event.
  
  transaction_id string
  
  Unique ID of the transaction.
  
  type string
  
  Type of the transaction event.
  
  status string
  
  Status of the transaction event.
  
  amount number
  
  Amount of the event.
  
  timestamp string
  
  Date and time of the transaction event.
  
  receipt_no string
- receipt_no string
  
  Receipt number
merchant_data object

Receipt merchant data
Show attributes
Close

Attributes
- merchant_profile object
  
  Show attributes
  
  Close
  
  Attributes
  
  merchant_code string
  
  business_name string
  
  email string
  
  address object
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  city string
  
  country string
  
  country_en_name string
  
  country_native_name string
  
  post_code string
  
  landline string
- locale string
emv_data object
Show attributes
Close

Attributes
acquirer_data object
Show attributes
Close

Attributes
- tid string
- authorization_code string
- return_code string
- local_time string

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

Receipts

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Path Parameters

id string required

Query Parameters

mid string required
tx_event_id integer

Response 200

transaction_data object

Transaction information.
Show attributes
Close

Attributes
- transaction_code string
  
  Transaction code.
- amount string
  
  Transaction amount.
- vat_amount string
  
  Transaction VAT amount.
- tip_amount string
  
  Tip amount (included in transaction amount).
- currency string
  
  Transaction currency.
- timestamp string
  
  Time created at.
- status string
  
  Transaction processing status.
- payment_type string
  
  Transaction type.
- entry_mode string
  
  Transaction entry mode.
- verification_method string
  
  Cardholder verification method.
- card object
  
  Show attributes
  
  Close
  
  Attributes
  
  last_4_digits string
  
  Card last 4 digits.
  
  type string
  
  Card Scheme.
- installments_count integer
  
  Number of installments.
- products []object
  
  Products
  
  Show attributes
  
  Close
  
  Attributes
  
  name string
  
  Product name.
  
  description string
  
  Product description.
  
  price number
  
  Product price.
  
  quantity integer
  
  Product quantity.
  
  total_price number
  
  Quantity x product price.
- vat_rates []object
  
  Vat rates.
  
  Show attributes
  
  Close
  
  Attributes
  
  gross number
  
  Gross
  
  net number
  
  Net
  
  rate number
  
  Rate
  
  vat number
  
  Vat
- events []object
  
  Events
  
  Show attributes
  
  Close
  
  Attributes
  
  id integer
  
  Unique ID of the transaction event.
  
  transaction_id string
  
  Unique ID of the transaction.
  
  type string
  
  Type of the transaction event.
  
  status string
  
  Status of the transaction event.
  
  amount number
  
  Amount of the event.
  
  timestamp string
  
  Date and time of the transaction event.
  
  receipt_no string
- receipt_no string
  
  Receipt number
merchant_data object

Receipt merchant data
Show attributes
Close

Attributes
- merchant_profile object
  
  Show attributes
  
  Close
  
  Attributes
  
  merchant_code string
  
  business_name string
  
  email string
  
  address object
  
  Show attributes
  
  Close
  
  Attributes
  
  address_line1 string
  
  city string
  
  country string
  
  country_en_name string
  
  country_native_name string
  
  post_code string
  
  landline string
- locale string
emv_data object
Show attributes
Close

Attributes
acquirer_data object
Show attributes
Close

Attributes
- tid string
- authorization_code string
- return_code string
- local_time string

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.

 get 
 /v1.1/receipts/{id}  
 curl https://api.sumup.com/v1.1/receipts/{id} 

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

Readers
Preview feature

A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.

The Reader object

A physical card reader device that can accept in-person payments.

Attributes

id string required

Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
name string required

Custom human-readable, user-defined name for easier identification of the reader.

Example: "Frontdesk"
status string required
The status of the reader object gives information about the current state of the reader.
Possible values:
- unknown - The reader status is unknown.
- processing - The reader is created and waits for the physical device to confirm the pairing.
- paired - The reader is paired with a merchant account and can be used with SumUp APIs.
- expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated
Example: "paired"
device object required

Information about the underlying physical device.
Show attributes
Close

Attributes
- identifier string required
  
  A unique identifier of the physical device (e.g. serial number).
  
  Example: "U1DT3NA00-CN"
- model string required
  
  Options: solo virtual-solo
  
  Identifier of the model of the device.
  
  Example: "solo"
meta object

Set of user-defined key-value pairs attached to the object.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the reader was created.

Example: "2023-01-18T15:16:17Z"
updated_at string required

The timestamp of when the reader was last updated.

Example: "2023-01-20T15:16:17Z"

The Reader object
 {
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "meta": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
} 

Readers

List Readers

List all readers of the merchant.

Scopes: readers.read

Path Parameters

merchant_code string required

Example: MC0X0ABC

Response 200

items []object required
Show attributes
Close

Attributes
- id string required
  
  Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.
  
  Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
- name string required
  
  Custom human-readable, user-defined name for easier identification of the reader.
  
  Example: "Frontdesk"
- status string required
  
  The status of the reader object gives information about the current state of the reader.
  Possible values:
  unknown - The reader status is unknown.
  processing - The reader is created and waits for the physical device to confirm the pairing.
  paired - The reader is paired with a merchant account and can be used with SumUp APIs.
  expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated
  
  Example: "paired"
- device object required
  
  Information about the underlying physical device.
  
  Show attributes
  
  Close
  
  Attributes
  
  identifier string required
  
  A unique identifier of the physical device (e.g. serial number).
  
  Example: "U1DT3NA00-CN"
  
  model string required
  
  Options: solo virtual-solo
  
  Identifier of the model of the device.
  
  Example: "solo"
- meta object
  
  Set of user-defined key-value pairs attached to the object.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
- created_at string required
  
  The timestamp of when the reader was created.
  
  Example: "2023-01-18T15:16:17Z"
- updated_at string required
  
  The timestamp of when the reader was last updated.
  
  Example: "2023-01-20T15:16:17Z"

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

List Readers response
 {
  "items": [
    {
      "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
      "name": "Frontdesk",
      "status": "paired",
      "device": {
        "identifier": "U1DT3NA00-CN",
        "model": "solo"
      },
      "meta": {},
      "created_at": "2023-01-18T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
} 

Readers

Create a Reader

Create a new Reader for the merchant account.

Scopes: readers.write

Path Parameters

merchant_code string required

Example: MC0X0ABC

Body Parameters

pairing_code string required

The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing.

Example: "4WLFDSBF"
name string

Custom human-readable, user-defined name for easier identification of the reader.

Example: "Frontdesk"
meta object

Set of user-defined key-value pairs attached to the object.
Show attributes
Close

Attributes
Example: {}

Response 201

id string required

Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
name string required

Custom human-readable, user-defined name for easier identification of the reader.

Example: "Frontdesk"
status string required
The status of the reader object gives information about the current state of the reader.
Possible values:
- unknown - The reader status is unknown.
- processing - The reader is created and waits for the physical device to confirm the pairing.
- paired - The reader is paired with a merchant account and can be used with SumUp APIs.
- expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated
Example: "paired"
device object required

Information about the underlying physical device.
Show attributes
Close

Attributes
- identifier string required
  
  A unique identifier of the physical device (e.g. serial number).
  
  Example: "U1DT3NA00-CN"
- model string required
  
  Options: solo virtual-solo
  
  Identifier of the model of the device.
  
  Example: "solo"
meta object

Set of user-defined key-value pairs attached to the object.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the reader was created.

Example: "2023-01-18T15:16:17Z"
updated_at string required

The timestamp of when the reader was last updated.

Example: "2023-01-20T15:16:17Z"

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

{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "processing",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "created_at": "2023-05-09T14:50:20.214Z",
  "updated_at": "2023-05-09T14:52:58.714Z"
}

Readers

Retrieve a Reader

Retrieve a Reader.

Scopes: readers.read

Path Parameters

merchant_code string required

Example: MC0X0ABC
id string required

Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Response 200

id string required

Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device.

Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
name string required

Custom human-readable, user-defined name for easier identification of the reader.

Example: "Frontdesk"
status string required
The status of the reader object gives information about the current state of the reader.
Possible values:
- unknown - The reader status is unknown.
- processing - The reader is created and waits for the physical device to confirm the pairing.
- paired - The reader is paired with a merchant account and can be used with SumUp APIs.
- expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated
Example: "paired"
device object required

Information about the underlying physical device.
Show attributes
Close

Attributes
- identifier string required
  
  A unique identifier of the physical device (e.g. serial number).
  
  Example: "U1DT3NA00-CN"
- model string required
  
  Options: solo virtual-solo
  
  Identifier of the model of the device.
  
  Example: "solo"
meta object

Set of user-defined key-value pairs attached to the object.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the reader was created.

Example: "2023-01-18T15:16:17Z"
updated_at string required

The timestamp of when the reader was last updated.

Example: "2023-01-20T15:16:17Z"

 get 
 /v0.1/merchants/{merchant_code}/readers/{id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} 

Retrieve a Reader response
 {
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "meta": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
} 

Readers

Update a Reader

Update a Reader.

Scopes: readers.write

Path Parameters

merchant_code string required

Example: MC0X0ABC
id string required

Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Body Parameters

name string

Custom human-readable, user-defined name for easier identification of the reader.

Example: "Frontdesk"
meta object

Set of user-defined key-value pairs attached to the object.
Show attributes
Close

Attributes
Example: {}

 patch 
 /v0.1/merchants/{merchant_code}/readers/{id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} 

Readers

Delete a reader

Delete a reader.

Scopes: readers.write

Path Parameters

merchant_code string required

Example: MC0X0ABC
id string required

Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

 delete 
 /v0.1/merchants/{merchant_code}/readers/{id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} 

Readers

Create a Reader Checkout

Create a Checkout for a Reader.

This process is asynchronous and the actual transaction may take some time to be stared on the device.

There are some caveats when using this endpoint:

The target device must be online, otherwise checkout won't be accepted
After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.

Note: If the target device is a Solo, it must be in version 3.3.24.3 or higher.

Scopes: readers.write

Path Parameters

merchant_code string required

Example: MC0X0ABC
id string required

Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Body Parameters

description string

Description of the checkout to be shown in the Merchant Sales
card_type string

Options: credit debit

The card type of the card used for the transaction. Is is required only for some countries (e.g: Brazil).

Example: "credit"
installments integer

Number of installments for the transaction. It may vary according to the merchant country. For example, in Brazil, the maximum number of installments is 12.

Example: 1
return_url string

Webhook URL to which the payment result will be sent. It must be a HTTPS url.

Example: "https://www.example.com"
total_amount object required

Amount of the transaction. The amount is represented as an integer value altogether with the currency and the minor unit. For example, EUR 1.00 is represented as value 100 with minor unit of 2.
Show attributes
Close

Attributes
- value integer required
  
  Total amount of the transaction. It must be a positive integer.
  
  Example: 1000
- currency string required
  
  Currency ISO 4217 code
  
  Example: "EUR"
- minor_unit integer required
  
  The minor units of the currency. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.
  
  Example: 2
tip_rates []number

List of tipping rates to be displayed to the cardholder. The rates are in percentage and should be between 0.01 and 0.99. The list should be sorted in ascending order.
Show attributes
Close

Attributes
affiliate object

Affiliate metadata for the transaction. It is an optional field that allow for integrators to track the source of the transaction.
Show attributes
Close

Attributes
- app_id string required
  
  Application ID of the affiliate. It is a unique identifier for the application and should be set by the integrator in the Affiliate Keys page.
  
  Example: "com.example.app"
- key string required
  
  Key of the affiliate. It is a unique identifier for the key and should be generated by the integrator in the Affiliate Keys page.
  
  Example: "123e4567-e89b-12d3-a456-426614174000"
- foreign_transaction_id string required
  
  Foreign transaction ID of the affiliate. It is a unique identifier for the transaction. It can be used later to fetch the transaction details via the Transactions API.
  
  Example: "123456"
- tags object
  
  Additional metadata for the transaction. It is key-value object that can be associated with the transaction.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}

Response 201

data object
Show attributes
Close

Attributes
- client_transaction_id string
  
  The client transaction ID is a unique identifier for the transaction that is generated for the client. It can be used later to fetch the transaction details via the Transactions API.
  
  Example: "123e4567-e89b-12d3-a456-426614174000"

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Bad Request"

errors object
Show attributes
Close

Attributes

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Internal Server Error"

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Bad Gateway"

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Gateway Timeout"

 post 
 /v0.1/merchants/{merchant_code}/readers/{id}/checkout  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}/checkout 

Create a Reader Checkout response
 {
  "data": {
    "client_transaction_id": "123e4567-e89b-12d3-a456-426614174000"
  }
} 

Readers

Create a Reader Terminate action

Create a Terminate action for a Reader.

It stops the current transaction on the target device.

This process is asynchronous and the actual termination may take some time to be performed on the device.

There are some caveats when using this endpoint:

The target device must be online, otherwise terminate won't be accepted
The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.
There is no confirmation of the termination.

If a transaction is successfully terminated and return_url was provided on Checkout, the transaction status will be sent as failed to the provided URL.

Note: If the target device is a Solo, it must be in version 3.3.28.0 or higher.

Scopes: readers.write

Path Parameters

merchant_code string required

Example: MC0X0ABC
id string required

Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

errors object
Show attributes
Close

Attributes

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Internal Server Error"

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Bad Gateway"

errors object
Show attributes
Close

Attributes
- detail string
  
  Example: "Gateway Timeout"

 post 
 /v0.1/merchants/{merchant_code}/readers/{id}/terminate  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id}/terminate 

Subaccounts

Endpoints for managing merchant sub-accounts (operators).

The object

Attributes

id integer required
username string required

Example: "[email protected]"
nickname string

Example: "Operator 1"
disabled boolean required
created_at string required

The timestamp of when the operator was created.
updated_at string required

The timestamp of when the operator was last updated.
permissions object required

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
- create_referral boolean
  
  Create referral
account_type string required

Options: operator normal

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

Subaccounts

List operators
Deprecated

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

Query Parameters

query string
include_primary boolean

Response 200

[]object

Show attributes

id integer required
username string required

Example: "[email protected]"
nickname string

Example: "Operator 1"
disabled boolean required
created_at string required

The timestamp of when the operator was created.
updated_at string required

The timestamp of when the operator was last updated.
permissions object required

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
- create_referral boolean
  
  Create referral
account_type string required

Options: operator normal

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

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

Subaccounts

Create an operator
Deprecated

Creates new operator for currently authorized users' merchant.

Body Parameters

username string required

Example: "[email protected]"
password string required

Example: "correct horse batter staple"
nickname string

Example: "Operator 1"
permissions object
Show attributes
Close

Attributes
- create_moto_payments boolean
- create_referral boolean
- full_transaction_history_view boolean
- refund_transactions boolean

Response 200

id integer required
username string required

Example: "[email protected]"
nickname string

Example: "Operator 1"
disabled boolean required
created_at string required

The timestamp of when the operator was created.
updated_at string required

The timestamp of when the operator was last updated.
permissions object required

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
- create_referral boolean
  
  Create referral
account_type string required

Options: operator normal

error_code string required

Example: "NOT_FOUND"
message string required

Example: "Resource not found."

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

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

Subaccounts

Retrieve an operator
Deprecated

Returns specific operator.

Path Parameters

operator_id integer required

Response 200

id integer required
username string required

Example: "[email protected]"
nickname string

Example: "Operator 1"
disabled boolean required
created_at string required

The timestamp of when the operator was created.
updated_at string required

The timestamp of when the operator was last updated.
permissions object required

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
- create_referral boolean
  
  Create referral
account_type string required

Options: operator normal

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

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

Subaccounts

Update an operator
Deprecated

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

Path Parameters

operator_id integer required

Body Parameters

password string

Example: "correct horse batter staple"
username string
disabled boolean
nickname string

Example: "Operator 1"
permissions object
Show attributes
Close

Attributes
- create_moto_payments boolean
- create_referral boolean
- full_transaction_history_view boolean
- refund_transactions boolean

Response 200

id integer required
username string required

Example: "[email protected]"
nickname string

Example: "Operator 1"
disabled boolean required
created_at string required

The timestamp of when the operator was created.
updated_at string required

The timestamp of when the operator was last updated.
permissions object required

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
- create_referral boolean
  
  Create referral
account_type string required

Options: operator normal

error_code string required

Example: "NOT_FOUND"
message string required

Example: "Resource not found."

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

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

Subaccounts

Disable an operator
Deprecated

Path Parameters

operator_id integer required

Response 200

id integer required
username string required

Example: "[email protected]"
nickname string

Example: "Operator 1"
disabled boolean required
created_at string required

The timestamp of when the operator was created.
updated_at string required

The timestamp of when the operator was last updated.
permissions object required

User permissions
Show attributes
Close

Attributes
- create_moto_payments boolean
  
  Create MOTO payments
- full_transaction_history_view boolean
  
  Can view full merchant transaction history
- refund_transactions boolean
  
  Refund transactions
- create_referral boolean
  
  Create referral
account_type string required

Options: operator normal

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

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

Memberships
Preview feature

Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.

The Membership object

A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.

Attributes

id string required

ID of the membership.

Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
resource_id string required

ID of the resource the membership is in.

Example: "M2DDT39A"
type string required

Options: merchant

Type of the resource the membership is in.

Example: "merchant"
roles []string required

User's roles.
Show attributes
Close

Attributes
permissions []string required

User's permissions.
Show attributes
Close

Attributes
created_at string required

The timestamp of when the membership was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the membership was last updated.

Example: "2023-01-20T15:16:17Z"
invite object

Pending invitation for membership.
Show attributes
Close

Invite
- email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
- expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
status string required

The status of the membership.
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}
resource object required

Information about the resource the membership is in.
Show attributes
Close

Resource
- id string required
  
  ID of the resource the membership is in.
  
  Example: "M2DDT39A"
- type string required
  
  Options: merchant
  
  Example: "merchant"
- name string required
  
  Display name of the resource.
  
  Example: "Acme Corp"
- logo string
  
  Logo fo the resource.
  
  Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
- created_at string required
  
  The timestamp of when the membership resource was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_at string required
  
  The timestamp of when the membership resource was last updated.
  
  Example: "2023-01-20T15:16:17Z"
- attributes object required
  
  Object attributes that modifiable only by SumUp applications.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}

{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "resource_id": "M2DDT39A",
  "type": "merchant",
  "roles": [
    "role_admin"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z",
  "invite": {
    "email": "[email protected]",
    "expires_at": "2023-01-20T15:16:17Z"
  },
  "status": "",
  "metadata": {},
  "attributes": {},
  "resource": {
    "id": "M2DDT39A",
    "type": "merchant",
    "name": "Acme Corp",
    "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
    "created_at": "2023-01-20T15:16:17Z",
    "updated_at": "2023-01-20T15:16:17Z",
    "attributes": {}
  }
}

Memberships

List memberships

List memberships of the current user.

Query Parameters

offset integer
0
limit integer

Example: 10
kind string
resource.attributes.sandbox boolean

Response 200

items []object required
Show attributes
Close

Attributes
- id string required
  
  ID of the membership.
  
  Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- resource_id string required
  
  ID of the resource the membership is in.
  
  Example: "M2DDT39A"
- type string required
  
  Options: merchant
  
  Type of the resource the membership is in.
  
  Example: "merchant"
- roles []string required
  
  User's roles.
  
  Show attributes
  
  Close
  
  Attributes
- permissions []string required
  
  User's permissions.
  
  Show attributes
  
  Close
  
  Attributes
- created_at string required
  
  The timestamp of when the membership was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_at string required
  
  The timestamp of when the membership was last updated.
  
  Example: "2023-01-20T15:16:17Z"
- invite object
  
  Pending invitation for membership.
  
  Show attributes
  
  Close
  
  Invite
  
  email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
  
  expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
- status string required
  
  The status of the membership.
- metadata object
  
  Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
- attributes object
  
  Object attributes that modifiable only by SumUp applications.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
- resource object required
  
  Information about the resource the membership is in.
  
  Show attributes
  
  Close
  
  Resource
  
  id string required
  
  ID of the resource the membership is in.
  
  Example: "M2DDT39A"
  
  type string required
  
  Options: merchant
  
  Example: "merchant"
  
  name string required
  
  Display name of the resource.
  
  Example: "Acme Corp"
  
  logo string
  
  Logo fo the resource.
  
  Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
  
  created_at string required
  
  The timestamp of when the membership resource was created.
  
  Example: "2023-01-20T15:16:17Z"
  
  updated_at string required
  
  The timestamp of when the membership resource was last updated.
  
  Example: "2023-01-20T15:16:17Z"
  
  attributes object required
  
  Object attributes that modifiable only by SumUp applications.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
total_count integer required

Example: 3

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

{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "resource_id": "M2DDT39A",
      "type": "merchant",
      "roles": [
        "role_admin"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z",
      "invite": {
        "email": "[email protected]",
        "expires_at": "2023-01-20T15:16:17Z"
      },
      "status": "",
      "metadata": {},
      "attributes": {},
      "resource": {
        "id": "M2DDT39A",
        "type": "merchant",
        "name": "Acme Corp",
        "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
        "created_at": "2023-01-20T15:16:17Z",
        "updated_at": "2023-01-20T15:16:17Z",
        "attributes": {}
      }
    }
  ],
  "total_count": 3
}

Members
Preview feature

Endpoints to manage account members. Members are users that have membership within merchant accounts.

The Member object

A member is user within specific resource identified by resource id, resource type, and associated roles.

Attributes

id string required

ID of the member.

Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
roles []string required

User's roles.
Show attributes
Close

Attributes
permissions []string required

User's permissions.
Show attributes
Close

Attributes
created_at string required

The timestamp of when the member was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the member was last updated.

Example: "2023-01-20T15:16:17Z"
user object

Information about the user associated with the membership.
Show attributes
Close

Attributes
- id string required
  
  Identifier for the End-User (also called Subject).
  
  Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
- email string required
  
  End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
  
  Example: "[email protected]"
- mfa_on_login_enabled boolean required
  
  True if the user has enabled MFA on login.
  
  Example: true
- virtual_user boolean required
  
  True if the user is a virtual user (operator).
- service_account_user boolean required
  
  True if the user is a service account.
- disabled_at string
  
  Time when the user has been disabled. Applies only to virtual users (virtual_user: true).
- nickname string
  
  User's preferred name. Used for display purposes only.
  
  Example: "Test User"
- picture string
  
  URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
  
  Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
- classic object
  
  Classic identifiers of the user.
  
  Show attributes
  
  Close
  
  Attributes
  
  user_id integer required
invite object

Pending invitation for membership.
Show attributes
Close

Invite
- email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
- expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
status string required

The status of the membership.
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}

{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "[email protected]",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}

Members

List members

Lists merchant members.

Path Parameters

merchant_code string required

Example: MC0X0ABC

Query Parameters

offset integer
0
limit integer

Example: 10
scroll boolean

Example: true
email string

Example: user
status string
roles []string

Example: role_employeerole_accountant

Response 200

items []object required
Show attributes
Close

Attributes
- id string required
  
  ID of the member.
  
  Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- roles []string required
  
  User's roles.
  
  Show attributes
  
  Close
  
  Attributes
- permissions []string required
  
  User's permissions.
  
  Show attributes
  
  Close
  
  Attributes
- created_at string required
  
  The timestamp of when the member was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_at string required
  
  The timestamp of when the member was last updated.
  
  Example: "2023-01-20T15:16:17Z"
- user object
  
  Information about the user associated with the membership.
  
  Show attributes
  
  Close
  
  Attributes
  
  id string required
  
  Identifier for the End-User (also called Subject).
  
  Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
  
  email string required
  
  End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
  
  Example: "[email protected]"
  
  mfa_on_login_enabled boolean required
  
  True if the user has enabled MFA on login.
  
  Example: true
  
  virtual_user boolean required
  
  True if the user is a virtual user (operator).
  
  service_account_user boolean required
  
  True if the user is a service account.
  
  disabled_at string
  
  Time when the user has been disabled. Applies only to virtual users (virtual_user: true).
  
  nickname string
  
  User's preferred name. Used for display purposes only.
  
  Example: "Test User"
  
  picture string
  
  URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
  
  Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
  
  classic object
  
  Classic identifiers of the user.
  
  Show attributes
  
  Close
  
  Attributes
  
  user_id integer required
- invite object
  
  Pending invitation for membership.
  
  Show attributes
  
  Close
  
  Invite
  
  email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
  
  expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
- status string required
  
  The status of the membership.
- metadata object
  
  Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
- attributes object
  
  Object attributes that modifiable only by SumUp applications.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
total_count integer

Example: 3

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

{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "roles": [
        "role_admin",
        "role_owner"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-02-20T15:16:17Z",
      "user": {
        "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
        "email": "[email protected]",
        "mfa_on_login_enabled": true,
        "virtual_user": false,
        "service_account_user": false
      },
      "status": "accepted"
    }
  ],
  "total_count": 3
}

Members

Create a member

Create a merchant member.

Path Parameters

merchant_code string required

Example: MC0X0ABC

Body Parameters

is_managed_user boolean

True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname.
is_service_account boolean

True if the user is a service account. It can later be used to create OAuth2 clients.
email string required

Email address of the member to add.
password string

Password of the member to add. Only used if is_managed_user is true. In the case of service accounts, the password is not used and can not be defined by the caller.
nickname string

Nickname of the member to add. Only used if is_managed_user is true. Used for display purposes only.

Example: "Test User"
roles []string required

List of roles to assign to the new member. In the case of service accounts, the roles are predefined.
Show attributes
Close

Attributes
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}

Response 201

id string required

ID of the member.

Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
roles []string required

User's roles.
Show attributes
Close

Attributes
permissions []string required

User's permissions.
Show attributes
Close

Attributes
created_at string required

The timestamp of when the member was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the member was last updated.

Example: "2023-01-20T15:16:17Z"
user object

Information about the user associated with the membership.
Show attributes
Close

Attributes
- id string required
  
  Identifier for the End-User (also called Subject).
  
  Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
- email string required
  
  End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
  
  Example: "[email protected]"
- mfa_on_login_enabled boolean required
  
  True if the user has enabled MFA on login.
  
  Example: true
- virtual_user boolean required
  
  True if the user is a virtual user (operator).
- service_account_user boolean required
  
  True if the user is a service account.
- disabled_at string
  
  Time when the user has been disabled. Applies only to virtual users (virtual_user: true).
- nickname string
  
  User's preferred name. Used for display purposes only.
  
  Example: "Test User"
- picture string
  
  URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
  
  Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
- classic object
  
  Classic identifiers of the user.
  
  Show attributes
  
  Close
  
  Attributes
  
  user_id integer required
invite object

Pending invitation for membership.
Show attributes
Close

Invite
- email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
- expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
status string required

The status of the membership.
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}

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

{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "[email protected]",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}

Members

Retrieve a member

Retrieve a merchant member.

Path Parameters

merchant_code string required

Example: MC0X0ABC
member_id string required

Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Response 200

id string required

ID of the member.

Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
roles []string required

User's roles.
Show attributes
Close

Attributes
permissions []string required

User's permissions.
Show attributes
Close

Attributes
created_at string required

The timestamp of when the member was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the member was last updated.

Example: "2023-01-20T15:16:17Z"
user object

Information about the user associated with the membership.
Show attributes
Close

Attributes
- id string required
  
  Identifier for the End-User (also called Subject).
  
  Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
- email string required
  
  End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
  
  Example: "[email protected]"
- mfa_on_login_enabled boolean required
  
  True if the user has enabled MFA on login.
  
  Example: true
- virtual_user boolean required
  
  True if the user is a virtual user (operator).
- service_account_user boolean required
  
  True if the user is a service account.
- disabled_at string
  
  Time when the user has been disabled. Applies only to virtual users (virtual_user: true).
- nickname string
  
  User's preferred name. Used for display purposes only.
  
  Example: "Test User"
- picture string
  
  URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
  
  Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
- classic object
  
  Classic identifiers of the user.
  
  Show attributes
  
  Close
  
  Attributes
  
  user_id integer required
invite object

Pending invitation for membership.
Show attributes
Close

Invite
- email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
- expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
status string required

The status of the membership.
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}

 get 
 /v0.1/merchants/{merchant_code}/members/{member_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} 

{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "[email protected]",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}

Members

Update a member

Update the merchant member.

Path Parameters

merchant_code string required

Example: MC0X0ABC
member_id string required

Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Body Parameters

roles []string
Show attributes
Close

Attributes
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}
user object

Allows you to update user data of managed users.
Show attributes
Close

Attributes
- nickname string
  
  User's preferred name. Used for display purposes only.
  
  Example: "Test User"
- password string
  
  Password of the member to add. Only used if is_managed_user is true.

Response 200

id string required

ID of the member.

Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
roles []string required

User's roles.
Show attributes
Close

Attributes
permissions []string required

User's permissions.
Show attributes
Close

Attributes
created_at string required

The timestamp of when the member was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the member was last updated.

Example: "2023-01-20T15:16:17Z"
user object

Information about the user associated with the membership.
Show attributes
Close

Attributes
- id string required
  
  Identifier for the End-User (also called Subject).
  
  Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
- email string required
  
  End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
  
  Example: "[email protected]"
- mfa_on_login_enabled boolean required
  
  True if the user has enabled MFA on login.
  
  Example: true
- virtual_user boolean required
  
  True if the user is a virtual user (operator).
- service_account_user boolean required
  
  True if the user is a service account.
- disabled_at string
  
  Time when the user has been disabled. Applies only to virtual users (virtual_user: true).
- nickname string
  
  User's preferred name. Used for display purposes only.
  
  Example: "Test User"
- picture string
  
  URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
  
  Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
- classic object
  
  Classic identifiers of the user.
  
  Show attributes
  
  Close
  
  Attributes
  
  user_id integer required
invite object

Pending invitation for membership.
Show attributes
Close

Invite
- email string required
  
  Email address of the invited user.
  
  Example: "[email protected]"
- expires_at string required
  
  Example: "2023-01-20T15:16:17Z"
status string required

The status of the membership.
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
attributes object

Object attributes that modifiable only by SumUp applications.
Show attributes
Close

Attributes
Example: {}

 put 
 /v0.1/merchants/{merchant_code}/members/{member_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} 

{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "[email protected]",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}

Members

Delete a member

Deletes a merchant member.

Path Parameters

merchant_code string required

Example: MC0X0ABC
member_id string required

Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

 delete 
 /v0.1/merchants/{merchant_code}/members/{member_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} 

Roles
Preview feature

Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.

The Role object

A custom role that can be used to assign set of permissions to members.

Attributes

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string required

List of permission granted by this role.
Show attributes
Close

Attributes
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

The Role object
 {
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [
    "members_list",
    "members_read",
    "members_view",
    "members_write",
    "members_delete"
  ],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
} 

Roles

List roles

List merchant's custom roles.

Path Parameters

merchant_code string required

Example: MC0X0ABC

Response 200

items []object required
Show attributes
Close

Attributes
- id string required
  
  Unique identifier of the role.
  
  Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- name string required
  
  User-defined name of the role.
  
  Example: "Senior Shop Manager II"
- description string
  
  User-defined description of the role.
  
  Example: "Manges the shop and the employees."
- permissions []string required
  
  List of permission granted by this role.
  
  Show attributes
  
  Close
  
  Attributes
- is_predefined boolean required
  
  True if the role is provided by SumUp.
  
  Example: true
- metadata object
  
  Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
  
  Show attributes
  
  Close
  
  Attributes
  
  Example: {}
- created_at string required
  
  The timestamp of when the role was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_at string required
  
  The timestamp of when the role was last updated.
  
  Example: "2023-01-20T15:16:17Z"

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

List roles response
 {
  "items": [
    {
      "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "name": "Senior Shop Manager II",
      "description": "Manges the shop and the employees.",
      "permissions": [
        "members_list",
        "members_read",
        "members_view",
        "members_write",
        "members_delete"
      ],
      "is_predefined": true,
      "metadata": {},
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
} 

Roles

Create a role

Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.

Path Parameters

merchant_code string required

Example: MC0X0ABC

Body Parameters

name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
permissions []string required

User's permissions.
Show attributes
Close

Attributes
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
description string

User-defined description of the role.

Example: "Manges the shop and the employees."

Response 201

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string required

List of permission granted by this role.
Show attributes
Close

Attributes
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

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

Create a role response
 {
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [
    "members_list",
    "members_read",
    "members_view",
    "members_write",
    "members_delete"
  ],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
} 

Roles

Retrieve a role

Retrieve a custom role by ID.

Path Parameters

merchant_code string required

Example: MC0X0ABC
role_id string required

Example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Response 200

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string required

List of permission granted by this role.
Show attributes
Close

Attributes
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

 get 
 /v0.1/merchants/{merchant_code}/roles/{role_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} 

Retrieve a role response
 {
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [
    "members_list",
    "members_read",
    "members_view",
    "members_write",
    "members_delete"
  ],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
} 

Roles

Update a role

Update a custom role.

Path Parameters

merchant_code string required

Example: MC0X0ABC
role_id string required

Example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Body Parameters

name string

User-defined name of the role.

Example: "Senior Shop Manager II"
permissions []string

User's permissions.
Show attributes
Close

Attributes
description string

User-defined description of the role.

Example: "Manges the shop and the employees."

Response 200

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string required

List of permission granted by this role.
Show attributes
Close

Attributes
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.
Show attributes
Close

Attributes
Example: {}
created_at string required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

 patch 
 /v0.1/merchants/{merchant_code}/roles/{role_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} 

Update a role response
 {
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [
    "members_list",
    "members_read",
    "members_view",
    "members_write",
    "members_delete"
  ],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
} 

Roles

Delete a role

Delete a custom role.

Path Parameters

merchant_code string required

Example: MC0X0ABC
role_id string required

Example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

 delete 
 /v0.1/merchants/{merchant_code}/roles/{role_id}  
 curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} 

SumUp REST API

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 202

Response 400

Response 401

Response 404

Response 409

Deactivate a checkout

Path Parameters

Response 200

Response 401

Response 404

Response 409

Get available payment methods

Path Parameters

Query Parameters

Response 200

Response 400

Response 401

Customers

The Customer object

Attributes

Create a customer

Body Parameters

Response 201

Response 401

Response 403

Response 409

Retrieve a customer

Path Parameters

Response 200

Response 401

Response 403

Response 404

Update a customer

Path Parameters

Body Parameters

Response 200

Response 401

Response 403

Response 404

List payment instruments

Path Parameters

Response 200

Response 401

Response 403

Response 404

Deactivate a payment instrument

Path Parameters

Response 204

Response 401

Response 403

Response 404

Transactions

Refund a transaction

Path Parameters

Body Parameters

Response 204

Retrieve a transaction
Deprecated

List transactions
Deprecated

List bank accounts
Deprecated

List payouts
Deprecated