SumUp REST API

SumUp’s REST API operates with application/json HTTP requests and response. The request bodies are sent through resource-oriented URLs and use the standard HTTP response codes. For testing our APIs make sure you have a SumUp Profile (you can create one here). To activate your SumUp Profile follow these steps.

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

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

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

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

Server URL
https://api.sumup.com

Authorization

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

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

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

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

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

Read more about authorization in our Authorization guide.

Authorization

Request authorization from users

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

Query Parameters

  • response_type  string
  • client_id  string
  • redirect_uri  string
  • scope  string
  • state  string

Response 200

get  /authorize
curl https://api.sumup.com/authorize
Response
{}
Authorization

Generate a token

Generate a token or a refresh token

Body Parameters

  • client_id  string  required

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

    Example: "fOcmczrYtYMJ7Li5GjMLLcUeC9dN"
  • client_secret  string  required

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

    Example: "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c"
  • code  string  required

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

    Example: "be366ce9fccd0c337d1da29b31d06dd1135ab95401562883"
  • grant_type  string  required
    Options:  authorization_code refresh_token

    The grant type used for obtaining an access token.

    Example: "refresh_token"
  • refresh_token  string

    A required parameter when generating a refresh token.

    Example: "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"

Response 200

  • access_token  string

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

    Example: "ec410d10ad7f06d3c2598473c9cd61189abcc016900a9938068542bcf9754073"
  • expires_in  integer

    The validity of the access token in seconds.

    Example: 3600
  • refresh_token  string

    The refresh token provided in the request call

    Example: "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af"
  • scope  string

    List of authorization scopes granted to your access token.

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

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

    Example: "Bearer"
post  /token
curl https://api.sumup.com/token
Response
Successfully created access token
{
  "access_token": "565e2d19cef68203170ddadb952141326d14e03f4ccbd46daa079c26c910a864",
  "expires_in": 3600,
  "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
  "token_type": "Bearer"
}
Successfully created access token with the refresh token
{
  "access_token": "ec410d10ad7f06d3c2598473c9cd61189abcc016900a9938068542bcf9754073",
  "expires_in": 3600,
  "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
  "scope": "payments user.app-settings transactions.history user.profile_readonly",
  "token_type": "Bearer"
}

Checkouts

Accept payments from your end users by adding the Checkouts model to your platform. SumUp supports standard and single payment 3DS checkout flows.

The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a checkout and then processing the checkout.

The Checkout object

Details of the payment checkout.

Attributes

  • amount  number

    Amount of the payment.

    Example: 10.1
  • checkout_reference  string

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

  • currency  string

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

    Example: "EUR"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

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

    Created mandate

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Merchant code which has the mandate

    • status  string

      Mandate status

    • type  string

      Indicates the mandate type

    Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • pay_to_email  string

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

  • return_url  string

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

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

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

List checkouts

Lists created checkout resources according to the applied checkout_reference.

Scopes: payments

Query Parameters

  • checkout_reference  string

Response 200

 []object
 Show attributes
 Close
Attributes
  • amount  number

    Amount of the payment.

    Example: 10.1
  • checkout_reference  string

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

  • currency  string

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

    Example: "EUR"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

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

    Created mandate

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Merchant code which has the mandate

    • status  string

      Mandate status

    • type  string

      Indicates the mandate type

    Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • pay_to_email  string

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

  • return_url  string

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

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

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

    Name of the merchant

    Example: "Sample Merchant"
  • payment_instrument  object

    Object containing token information for the specified payment instrument

     Show attributes
     Close
    Attributes
    • token  string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  • redirect_url  string

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

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

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

    Example: "TEENSK4W2K"
  • transaction_id  string

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

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

Create a checkout

Creates a new payment checkout resource. The unique checkout_reference created by this request, is used for further manipulation of the checkout.

For 3DS checkouts, add the redirect_url parameter to your request body schema.

Follow by processing a checkout to charge the provided payment instrument.

Scopes: payments

Body Parameters

  • amount  number  required

    Amount of the payment.

  • checkout_reference  string  required

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

  • currency  string  required

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

    Example: "EUR"
  • customer_id  string

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

  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

  • merchant_code  string  required

    Unique identifying code of the merchant profile.

  • pay_to_email  string

    Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

  • payment_type  string

    Alternative payment method name

    Example: "boleto"
  • personal_details  object

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

     Show attributes
     Close
    Attributes
    • address  object

      Payer's address information

       Show attributes
       Close
      Attributes
      • city  string

        Payer's city

        Example: "Rio de Janeiro"
      • country  string

        Payer's country

        Example: "BR"
      • line_1  string

        Field for address details

      • postal_code  string

        Payer's postal code. Must be eight digits long, however an optional dash could be applied after the 5th digit (more information about the format available here). Both options are accepted as correct.

        Example: "20000-000"
      • state  string
        Options:  AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO

        Payer's state code

        Example: "RJ"
    • email  string

      Payer's email address

      Example: "[email protected]"
    • first_name  string

      Payer's first name

      Example: "John"
    • last_name  string

      Payer's last name

      Example: "Doe"
    • tax_id  string

      Payer's tax identification number (CPF)

      Example: "423.378.593-47"
  • purpose  string
    Options:  CHECKOUT SETUP_RECURRING_PAYMENT

    Purpose of the checkout.

  • redirect_url  string

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

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

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

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

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

Response 201

  • amount  number

    Amount of the payment.

    Example: 10.1
  • checkout_reference  string

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

  • currency  string

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

    Example: "EUR"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

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

    Created mandate

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Merchant code which has the mandate

    • status  string

      Mandate status

    • type  string

      Indicates the mandate type

    Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • pay_to_email  string

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

  • return_url  string

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

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

    Example: "2020-02-29T10:56:56+00:00"
post  /v0.1/checkouts
curl https://api.sumup.com/v0.1/checkouts
Response
Standard response body for a successfully created checkout
{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "pay_to_email": "[email protected]",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}
Response body for a successfully created 3DS checkout
{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "pay_to_email": "[email protected]",
  "redirect_url": "https://mysite.com/completed_purchase",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}
Response body for APMs, including Blik, iDeal, ...
{
  "amount": 10.1,
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "currency": "EUR",
  "date": "2021-06-29T11:08:36.000+00:00",
  "description": "My Checkout",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "merchant_code": "MCNPLE22",
  "merchant_country": "DE",
  "merchant_name": "My company",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "redirect_url": "https://sumup.com",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "012345",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 0,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ]
}
Checkouts

Retrieve a checkout

Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.

Scopes: payments

Path Parameters

  • id  string  required

Response 200

  • amount  number

    Amount of the payment.

    Example: 10.1
  • checkout_reference  string

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

  • currency  string

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

    Example: "EUR"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

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

    Created mandate

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Merchant code which has the mandate

    • status  string

      Mandate status

    • type  string

      Indicates the mandate type

    Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • pay_to_email  string

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

  • return_url  string

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

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

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

    Name of the merchant

    Example: "Sample Merchant"
  • payment_instrument  object

    Object containing token information for the specified payment instrument

     Show attributes
     Close
    Attributes
    • token  string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  • redirect_url  string

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

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

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

    Example: "TEENSK4W2K"
  • transaction_id  string

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

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

Process a checkout

Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the Create a checkout endpoint.

Follow this request with Retrieve a checkout to confirm its status.

Path Parameters

  • id  string  required

Body Parameters

  • card  object

    Required when payment type is card. Details of the payment card.

     Show attributes
     Close
    Attributes
    • cvv  string  required

      Three or four-digit card verification value (security code) of the payment card.

      Example: "123"
    • expiry_month  string  required
      Options:  01 02 03 04 05 06 07 08 09 10 11 12

      Month from the expiration time of the payment card. Accepted format is MM.

    • expiry_year  string  required

      Year from the expiration time of the payment card. Accepted formats are YY and YYYY.

      Example: "2023"
    • last_4_digits  string  required

      Last 4 digits of the payment card number.

      Example: "3456"
    • name  string  required

      Name of the cardholder as it appears on the payment card.

      Example: "FIRSTNAME LASTNAME"
    • number  string  required

      Number of the payment card (without spaces).

      Example: "1234567890123456"
    • type  string  required
      Options:  AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN

      Issuing card network of the payment card.

    • zip_code  string

      Required five-digit ZIP code. Applicable only to merchant users in the USA.

      Example: "12345"
  • customer_id  string

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

  • installments  integer

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

  • mandate  object

    Mandate is passed when a card is to be tokenised

     Show attributes
     Close
    Attributes
    • type  string  required
      Options:  recurrent

      Indicates the mandate type

    • user_agent  string  required

      Operating system and web client used by the end-user

    • user_ip  string

      IP address of the end user. Supports IPv4 and IPv6

    Example: {"type":"recurrent","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36","user_ip":"172.217.169.174"}
  • payment_type  string  required
    Options:  card boleto ideal blik bancontact
  • token  string

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

Response 200

  • amount  number

    Amount of the payment.

    Example: 10.1
  • checkout_reference  string

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

  • currency  string

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

    Example: "EUR"
  • customer_id  string

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

    Example: "831ff8d4cd5958ab5670"
  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

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

    Created mandate

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Merchant code which has the mandate

    • status  string

      Mandate status

    • type  string

      Indicates the mandate type

    Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
  • merchant_code  string

    Unique identifying code of the merchant profile.

  • pay_to_email  string

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

  • return_url  string

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

  • status  string
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

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

    Name of the merchant

    Example: "Sample Merchant"
  • payment_instrument  object

    Object containing token information for the specified payment instrument

     Show attributes
     Close
    Attributes
    • token  string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  • redirect_url  string

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

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

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

    Example: "TEENSK4W2K"
  • transaction_id  string

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

    Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
put  /v0.1/checkouts/{id}
curl https://api.sumup.com/v0.1/checkouts/{id}
Response
Successfully processed checkout with Bancontact
{
  "next_step": {
    "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
      "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB",
      "tx": "624788471"
    },
    "url": "https://r3.girogate.de/ti/simbcmc"
  }
}
Successfully processed checkout with Boleto
{
  "amount": 10.1,
  "boleto": {
    "barcode": "34191090081790614310603072340007886840000000200",
    "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto"
  },
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "BRL",
  "date": "2021-07-06T12:34:02.000+00:00",
  "description": "Boleto checkout",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample shop",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "redirect_url": "https://website.com",
  "status": "PENDING",
  "transactions": [
    {
      "amount": 10.1,
      "currency": "BRL",
      "entry_mode": "BOLETO",
      "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C9",
      "payment_type": "BOLETO",
      "status": "PENDING",
      "timestamp": "2021-07-06T12:34:16.460+00:00",
      "tip_amount": 3,
      "transaction_code": "TEN3E696NP",
      "vat_amount": 6
    }
  ]
}
Successfully processed checkout with a card
{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "mandate": {
    "merchant_code": "MDASYTPD",
    "status": "active",
    "type": "recurrent"
  },
  "merchant_code": "MH4H92C7",
  "pay_to_email": "[email protected]",
  "return_url": "http://example.com",
  "status": "PENDING",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "053201",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ],
  "valid_until": "2020-02-29T10:56:56+00:00"
}
Successfully processed checkout with a token
{
  "amount": 10.1,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "customer_id": "831ff8d4cd5958ab5670",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Purchase with token",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample Merchant",
  "pay_to_email": "[email protected]",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "redirect_url": "https://mysite.com/completed_purchase",
  "status": "PENDING",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "transactions": [
    {
      "amount": 10.1,
      "auth_code": "053201",
      "currency": "EUR",
      "entry_mode": "CUSTOMER_ENTRY",
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "installments_count": 1,
      "internal_id": 1763892018,
      "merchant_code": "MH4H92C7",
      "payment_type": "ECOM",
      "status": "SUCCESSFUL",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "tip_amount": 3,
      "transaction_code": "TEENSK4W2K",
      "vat_amount": 6
    }
  ]
}
Successfully processed checkout with iDeal
{
  "next_step": {
    "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
    "mechanism": [
      "browser"
    ],
    "method": "GET",
    "payload": {
      "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
      "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz",
      "tx": "961473700"
    },
    "url": "https://r3.girogate.de/ti/simideal"
  }
}
Checkouts

Deactivate a checkout

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

Scopes: payments

Path Parameters

  • id  string  required

Response 200

  • amount  number

    Amount of the payment.

  • checkout_reference  string

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

  • currency  string

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

    Example: "EUR"
  • date  string

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

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

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

  • id  string

    Unique ID of the checkout resource.

  • merchant_code  string

    Unique identifying code of the merchant profile.

  • merchant_country  string

    The merchant's country

  • merchant_name  string

    Merchant name

  • pay_to_email  string

    Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

  • purpose  string
    Options:  SETUP_RECURRING_PAYMENT CHECKOUT

    Purpose of the checkout creation initially

  • status  string
    Options:  EXPIRED

    Current status of the checkout.

  • transactions  []object

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • auth_code  string

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

      Example: "053201"
    • entry_mode  string
      Options:  CUSTOMER_ENTRY BOLETO

      Entry mode of the payment details.

    • internal_id  integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
    • merchant_code  string

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

      Example: "MH4H92C7"
    • tip_amount  number

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

      Example: 3
    • vat_amount  number

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

      Example: 6
  • valid_until  string

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

    Example: "2020-02-29T10:56:56+00:00"
delete  /v0.1/checkouts/{id}
curl https://api.sumup.com/v0.1/checkouts/{id}
Response
Response body for a successfully deactivated checkout
{
  "amount": 2,
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "currency": "EUR",
  "date": "2020-02-29T10:56:56+00:00",
  "description": "Deletion example",
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
  "merchant_code": "MH4H92C7",
  "merchant_name": "Sample Merchant",
  "pay_to_email": "[email protected]",
  "purpose": "CHECKOUT",
  "status": "EXPIRED",
  "transactions": [],
  "valid_until": "2020-02-29T10:56:56+00:00"
}
Checkouts

Get available payment methods

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

Scopes: payments

Path Parameters

  • merchant_code  string  required
    Example: M1234

Query Parameters

  • amount  number
    Example: 9.99
  • currency  string
    Example: EUR

Response 200

  • available_payment_methods  []object
     Show attributes
     Close
    Attributes
    • id  string  required

      The ID of the payment method.

      Example: "qr_code_pix"
get  /v0.1/merchants/{merchant_code}/payment-methods
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/payment-methods
Response
Available payment methods
{
  "available_payment_methods": [
    {
      "id": "apple_pay"
    },
    {
      "id": "blik"
    }
  ]
}

Customers

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

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

The Customer object

Attributes

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string  required

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
    • birthdate  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • email  string

      Email address of the customer.

      Example: "[email protected]"
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • phone  string

      Phone number of the customer.

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

Create a customer

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

Scopes: payment_instruments

Body Parameters

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string  required

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
    • birthdate  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • email  string

      Email address of the customer.

      Example: "[email protected]"
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"

Response 201

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string  required

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
    • birthdate  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • email  string

      Email address of the customer.

      Example: "[email protected]"
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
post  /v0.1/customers
curl https://api.sumup.com/v0.1/customers
Create a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}
Customers

Retrieve a customer

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

Scopes: payment_instruments

Path Parameters

  • customer_id  string  required

Response 200

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string  required

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
    • birthdate  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • email  string

      Email address of the customer.

      Example: "[email protected]"
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
get  /v0.1/customers/{customer_id}
curl https://api.sumup.com/v0.1/customers/{customer_id}
Retrieve a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}
Customers

Update a customer

Updates an identified saved customer resource's personal details.

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

Scopes: payment_instruments

Path Parameters

  • customer_id  string  required

Body Parameters

  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string  required

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
    • birthdate  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • email  string

      Email address of the customer.

      Example: "[email protected]"
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"

Response 200

  • customer_id  string  required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details  object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • address  object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city  string

        City name from the address.

        Example: "Berlin"
      • country  string  required

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line1  string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line2  string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code  string

        Postal code from the address.

        Example: "10115"
      • state  string

        State name or abbreviation from the address.

        Example: "Berlin"
    • birthdate  string

      Date of birth of the customer.

      Example: "1993-12-31"
    • email  string

      Email address of the customer.

      Example: "[email protected]"
    • first_name  string

      First name of the customer.

      Example: "John"
    • last_name  string

      Last name of the customer.

      Example: "Doe"
    • phone  string

      Phone number of the customer.

      Example: "+491635559723"
put  /v0.1/customers/{customer_id}
curl https://api.sumup.com/v0.1/customers/{customer_id}
Update a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Sample street",
      "line2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    },
    "birthdate": "1993-12-31",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+491635559723"
  }
}
Customers

List payment instruments

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

Scopes: payment_instruments

Path Parameters

  • customer_id  string  required

Response 200

 []object
 Show attributes
 Close
Attributes
  • active  boolean

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

  • card  object

    Details of the payment card.

     Show attributes
     Close
    Attributes
    • last_4_digits  string

      Last 4 digits of the payment card number.

      Example: "3456"
    • type  string
      Options:  AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN

      Issuing card network of the payment card.

  • created_at  string

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

  • mandate  object

    Created mandate

     Show attributes
     Close
    Attributes
    • merchant_code  string

      Merchant code which has the mandate

    • status  string

      Mandate status

    • type  string

      Indicates the mandate type

    Example: {"merchant_code":"MDASYTPD","status":"active","type":"recurrent"}
  • token  string

    Unique token identifying the saved payment card for a customer.

  • type  string
    Options:  card

    Type of the payment instrument.

get  /v0.1/customers/{customer_id}/payment-instruments
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments
List payment instruments response
[
  {
    "active": true,
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00",
    "mandate": {
      "merchant_code": "MDASYTPD",
      "status": "active",
      "type": "recurrent"
    },
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "type": "card"
  }
]
Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Scopes: payment_instruments

Path Parameters

  • customer_id  string  required
  • token  string  required

Response 204

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

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Attributes

  • account  object

    Profile information.

     Show attributes
     Close
    Attributes
    • type  string
      Options:  normal operator

      The role of the user.

    • username  string

      Username of the user profile.

  • app_settings  object

    Mobile app settings

     Show attributes
     Close
    Attributes
    • advanced_mode  string

      Advanced mode.

    • barcode_scanner  string

      Barcode scanner.

    • cash_payment  string

      Cash payment.

    • checkout_preference  string

      Checkout preference

    • expected_max_transaction_amount  number

      Expected max transaction amount.

    • include_vat  boolean

      Include vat.

    • manual_entry  string

      Manual entry.

    • manual_entry_tutorial  boolean

      Manual entry tutorial.

    • mobile_payment  string

      Mobile payment.

    • mobile_payment_tutorial  boolean

      Mobile payment tutorial.

    • reader_payment  string

      Reader payment.

    • referral  string

      Referral.

    • tax_enabled  boolean

      Tax enabled.

    • terminal_mode_tutorial  boolean

      Terminal mode tutorial.

    • tip_rates  []number

      Tip rates.

       Show attributes
       Close
      Attributes
    • tipping  string

      Tipping.

  • is_migrated_payleven_br  boolean

    Merchant comes from payleven BR migration

  • merchant_profile  object

    Account's merchant profile

     Show attributes
     Close
    Attributes
    • address  object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1  string

        Address line 1

      • address_line2  string

        Address line 2

      • city  string

        City

      • company  string

        undefined

      • country  string

        Country ISO 3166-1 code

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • en_name  string

          Country EN name

        • iso_code  string

          Country ISO code

        • native_name  string

          Country native name

      • first_name  string

        undefined

      • landline  string

        Landline number

      • last_name  string

        undefined

      • post_code  string

        Postal code

      • region_code  string

        Region code

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • state_id  string

        undefined

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • dst  boolean

          Daylight Saving Time

        • offset  number

          UTC offset

        • post_code  string

          Postal code

    • bank_accounts  []object
       Show attributes
       Close
      Attributes
      • account_category  string

        Account category - business or personal

      • account_holder_name  string
      • account_number  string

        Account number

      • account_type  string

        Type of the account

      • bank_code  string

        Bank code

      • bank_name  string

        Bank name

      • branch_code  string

        Branch code

      • created_at  string

        Creation date of the bank account

      • iban  string

        IBAN

      • primary  boolean

        The primary bank account is the one used for settlements

      • status  string

        Status in the verification process

      • swift  string

        SWIFT code

    • business_owners  []object

      Business owners information.

    • company_name  string

      Company name

    • company_registration_number  string

      Company registration number

    • country  string

      Merchant country isocode (for internal usage only)

    • doing_business_as  object

      Doing Business As information

       Show attributes
       Close
      Attributes
      • address  object
         Show attributes
         Close
        Attributes
        • address_line1  string

          Address line 1

        • address_line2  string

          Address line 2

        • city  string

          City

        • country  string

          Country ISO 3166-1 code

        • post_code  string

          Postal code

        • region_id  number

          Country region ID

        • region_name  string

          Country region name

      • business_name  string

        Doing business as name

      • company_registration_number  string

        Doing business as company registration number

      • email  string

        Doing business as email

      • vat_id  string

        Doing business as VAT ID

      • website  string

        Doing business as website

    • extdev  boolean

      True if the merchant is extdev

    • legal_type  object

      Id of the legal type of the merchant profile

       Show attributes
       Close
      Attributes
      • description  string

        Legal type short description

      • full_description  string

        Legal type description

      • id  number

        Unique id

      • sole_trader  boolean

        Sole trader legal type if true

    • locale  string

      Merchant locale (for internal usage only)

    • merchant_category_code  string

      Merchant category code

    • merchant_code  string

      Unique identifying code of the merchant profile

    • mobile_phone  string

      Mobile phone number

    • nature_and_purpose  string

      Nature and purpose of the business

    • payout_zone_migrated  boolean

      True if the payout zone of this merchant is migrated

    • permanent_certificate_access_code  string

      Permanent certificate access code (Portugal)

    • settings  object

      Merchant settings (like "payout_type", "payout_period")

       Show attributes
       Close
      Attributes
      • daily_payout_email  boolean

        Whether merchant will receive daily payout emails

      • gross_settlement  boolean

        Whether merchant has gross settlement enabled

      • monthly_payout_email  boolean

        Whether merchant will receive monthly payout emails

      • moto_payment  string
        Options:  UNAVAILABLE ENFORCED ON OFF

        Whether merchant can make MOTO payments

      • payout_instrument  string

        Payout Instrument

      • payout_on_demand  boolean

        Whether merchant will receive payouts on demand

      • payout_on_demand_available  boolean

        Whether merchant can edit payouts on demand

      • payout_period  string

        Payout frequency

      • payout_type  string

        Payout type

      • printers_enabled  boolean

        Whether to show printers in mobile app

      • stone_merchant_code  string

        Stone merchant code

      • tax_enabled  boolean

        Whether to show tax in receipts (saved per transaction)

    • vat_id  string

      Vat ID

    • vat_rates  object

      Merchant VAT rates

       Show attributes
       Close
      Attributes
      • country  string

        Country ISO code

      • description  string

        Description

      • id  number

        Internal ID

      • ordering  number

        Ordering

      • rate  number

        Rate

    • website  string

      Website

  • permissions  object

    User permissions

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean

      Create MOTO payments

    • create_referral  boolean

      Create referral

    • full_transaction_history_view  boolean

      Can view full merchant transaction history

    • refund_transactions  boolean

      Refund transactions

  • personal_profile  object

    Account's personal profile.

     Show attributes
     Close
    Attributes
    • address  object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1  string

        Address line 1

      • address_line2  string

        Address line 2

      • city  string

        City

      • company  string

        undefined

      • country  string

        Country ISO 3166-1 code

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • en_name  string

          Country EN name

        • iso_code  string

          Country ISO code

        • native_name  string

          Country native name

      • first_name  string

        undefined

      • landline  string

        Landline number

      • last_name  string

        undefined

      • post_code  string

        Postal code

      • region_code  string

        Region code

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • state_id  string

        undefined

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • dst  boolean

          Daylight Saving Time

        • offset  number

          UTC offset

        • post_code  string

          Postal code

    • complete  boolean
    • date_of_birth  string

      Date of birth

    • first_name  string

      First name of the user

    • last_name  string

      Last name of the user

    • mobile_phone  string

      Mobile phone number

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

Retrieve a profile

Returns user profile information.

Scopes: user.profile user.profile_readonly

Query Parameters

  • include[]  []string

Response 200

  • account  object

    Profile information.

     Show attributes
     Close
    Attributes
    • type  string
      Options:  normal operator

      The role of the user.

    • username  string

      Username of the user profile.

  • app_settings  object

    Mobile app settings

     Show attributes
     Close
    Attributes
    • advanced_mode  string

      Advanced mode.

    • barcode_scanner  string

      Barcode scanner.

    • cash_payment  string

      Cash payment.

    • checkout_preference  string

      Checkout preference

    • expected_max_transaction_amount  number

      Expected max transaction amount.

    • include_vat  boolean

      Include vat.

    • manual_entry  string

      Manual entry.

    • manual_entry_tutorial  boolean

      Manual entry tutorial.

    • mobile_payment  string

      Mobile payment.

    • mobile_payment_tutorial  boolean

      Mobile payment tutorial.

    • reader_payment  string

      Reader payment.

    • referral  string

      Referral.

    • tax_enabled  boolean

      Tax enabled.

    • terminal_mode_tutorial  boolean

      Terminal mode tutorial.

    • tip_rates  []number

      Tip rates.

       Show attributes
       Close
      Attributes
    • tipping  string

      Tipping.

  • is_migrated_payleven_br  boolean

    Merchant comes from payleven BR migration

  • merchant_profile  object

    Account's merchant profile

     Show attributes
     Close
    Attributes
    • address  object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1  string

        Address line 1

      • address_line2  string

        Address line 2

      • city  string

        City

      • company  string

        undefined

      • country  string

        Country ISO 3166-1 code

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • en_name  string

          Country EN name

        • iso_code  string

          Country ISO code

        • native_name  string

          Country native name

      • first_name  string

        undefined

      • landline  string

        Landline number

      • last_name  string

        undefined

      • post_code  string

        Postal code

      • region_code  string

        Region code

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • state_id  string

        undefined

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • dst  boolean

          Daylight Saving Time

        • offset  number

          UTC offset

        • post_code  string

          Postal code

    • bank_accounts  []object
       Show attributes
       Close
      Attributes
      • account_category  string

        Account category - business or personal

      • account_holder_name  string
      • account_number  string

        Account number

      • account_type  string

        Type of the account

      • bank_code  string

        Bank code

      • bank_name  string

        Bank name

      • branch_code  string

        Branch code

      • created_at  string

        Creation date of the bank account

      • iban  string

        IBAN

      • primary  boolean

        The primary bank account is the one used for settlements

      • status  string

        Status in the verification process

      • swift  string

        SWIFT code

    • business_owners  []object

      Business owners information.

    • company_name  string

      Company name

    • company_registration_number  string

      Company registration number

    • country  string

      Merchant country isocode (for internal usage only)

    • doing_business_as  object

      Doing Business As information

       Show attributes
       Close
      Attributes
      • address  object
         Show attributes
         Close
        Attributes
        • address_line1  string

          Address line 1

        • address_line2  string

          Address line 2

        • city  string

          City

        • country  string

          Country ISO 3166-1 code

        • post_code  string

          Postal code

        • region_id  number

          Country region ID

        • region_name  string

          Country region name

      • business_name  string

        Doing business as name

      • company_registration_number  string

        Doing business as company registration number

      • email  string

        Doing business as email

      • vat_id  string

        Doing business as VAT ID

      • website  string

        Doing business as website

    • extdev  boolean

      True if the merchant is extdev

    • legal_type  object

      Id of the legal type of the merchant profile

       Show attributes
       Close
      Attributes
      • description  string

        Legal type short description

      • full_description  string

        Legal type description

      • id  number

        Unique id

      • sole_trader  boolean

        Sole trader legal type if true

    • locale  string

      Merchant locale (for internal usage only)

    • merchant_category_code  string

      Merchant category code

    • merchant_code  string

      Unique identifying code of the merchant profile

    • mobile_phone  string

      Mobile phone number

    • nature_and_purpose  string

      Nature and purpose of the business

    • payout_zone_migrated  boolean

      True if the payout zone of this merchant is migrated

    • permanent_certificate_access_code  string

      Permanent certificate access code (Portugal)

    • settings  object

      Merchant settings (like "payout_type", "payout_period")

       Show attributes
       Close
      Attributes
      • daily_payout_email  boolean

        Whether merchant will receive daily payout emails

      • gross_settlement  boolean

        Whether merchant has gross settlement enabled

      • monthly_payout_email  boolean

        Whether merchant will receive monthly payout emails

      • moto_payment  string
        Options:  UNAVAILABLE ENFORCED ON OFF

        Whether merchant can make MOTO payments

      • payout_instrument  string

        Payout Instrument

      • payout_on_demand  boolean

        Whether merchant will receive payouts on demand

      • payout_on_demand_available  boolean

        Whether merchant can edit payouts on demand

      • payout_period  string

        Payout frequency

      • payout_type  string

        Payout type

      • printers_enabled  boolean

        Whether to show printers in mobile app

      • stone_merchant_code  string

        Stone merchant code

      • tax_enabled  boolean

        Whether to show tax in receipts (saved per transaction)

    • vat_id  string

      Vat ID

    • vat_rates  object

      Merchant VAT rates

       Show attributes
       Close
      Attributes
      • country  string

        Country ISO code

      • description  string

        Description

      • id  number

        Internal ID

      • ordering  number

        Ordering

      • rate  number

        Rate

    • website  string

      Website

  • permissions  object

    User permissions

     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean

      Create MOTO payments

    • create_referral  boolean

      Create referral

    • full_transaction_history_view  boolean

      Can view full merchant transaction history

    • refund_transactions  boolean

      Refund transactions

  • personal_profile  object

    Account's personal profile.

     Show attributes
     Close
    Attributes
    • address  object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1  string

        Address line 1

      • address_line2  string

        Address line 2

      • city  string

        City

      • company  string

        undefined

      • country  string

        Country ISO 3166-1 code

      • country_details  object

        Country Details

         Show attributes
         Close
        Attributes
        • currency  string

          Currency ISO 4217 code

        • en_name  string

          Country EN name

        • iso_code  string

          Country ISO code

        • native_name  string

          Country native name

      • first_name  string

        undefined

      • landline  string

        Landline number

      • last_name  string

        undefined

      • post_code  string

        Postal code

      • region_code  string

        Region code

      • region_id  number

        Country region id

      • region_name  string

        Region name

      • state_id  string

        undefined

      • timeoffset_details  object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • dst  boolean

          Daylight Saving Time

        • offset  number

          UTC offset

        • post_code  string

          Postal code

    • complete  boolean
    • date_of_birth  string

      Date of birth

    • first_name  string

      First name of the user

    • last_name  string

      Last name of the user

    • mobile_phone  string

      Mobile phone number

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

Retrieve a merchant profile

Retrieves merchant profile data.

Scopes: user.profile user.profile_readonly

Response 200

  • address  object

    Details of the registered address.

     Show attributes
     Close
    Attributes
    • address_line1  string

      Address line 1

    • address_line2  string

      Address line 2

    • city  string

      City

    • company  string

      undefined

    • country  string

      Country ISO 3166-1 code

    • country_details  object

      Country Details

       Show attributes
       Close
      Attributes
      • currency  string

        Currency ISO 4217 code

      • en_name  string

        Country EN name

      • iso_code  string

        Country ISO code

      • native_name  string

        Country native name

    • first_name  string

      undefined

    • landline  string

      Landline number

    • last_name  string

      undefined

    • post_code  string

      Postal code

    • region_code  string

      Region code

    • region_id  number

      Country region id

    • region_name  string

      Region name

    • state_id  string

      undefined

    • timeoffset_details  object

      TimeOffset Details

       Show attributes
       Close
      Attributes
      • dst  boolean

        Daylight Saving Time

      • offset  number

        UTC offset

      • post_code  string

        Postal code

  • bank_accounts  []object
     Show attributes
     Close
    Attributes
    • account_category  string

      Account category - business or personal

    • account_holder_name  string
    • account_number  string

      Account number

    • account_type  string

      Type of the account

    • bank_code  string

      Bank code

    • bank_name  string

      Bank name

    • branch_code  string

      Branch code

    • created_at  string

      Creation date of the bank account

    • iban  string

      IBAN

    • primary  boolean

      The primary bank account is the one used for settlements

    • status  string

      Status in the verification process

    • swift  string

      SWIFT code

  • business_owners  []object

    Business owners information.

  • company_name  string

    Company name

  • company_registration_number  string

    Company registration number

  • country  string

    Merchant country isocode (for internal usage only)

  • doing_business_as  object

    Doing Business As information

     Show attributes
     Close
    Attributes
    • address  object
       Show attributes
       Close
      Attributes
      • address_line1  string

        Address line 1

      • address_line2  string

        Address line 2

      • city  string

        City

      • country  string

        Country ISO 3166-1 code

      • post_code  string

        Postal code

      • region_id  number

        Country region ID

      • region_name  string

        Country region name

    • business_name  string

      Doing business as name

    • company_registration_number  string

      Doing business as company registration number

    • email  string

      Doing business as email

    • vat_id  string

      Doing business as VAT ID

    • website  string

      Doing business as website

  • extdev  boolean

    True if the merchant is extdev

  • legal_type  object

    Id of the legal type of the merchant profile

     Show attributes
     Close
    Attributes
    • description  string

      Legal type short description

    • full_description  string

      Legal type description

    • id  number

      Unique id

    • sole_trader  boolean

      Sole trader legal type if true

  • locale  string

    Merchant locale (for internal usage only)

  • merchant_category_code  string

    Merchant category code

  • merchant_code  string

    Unique identifying code of the merchant profile

  • mobile_phone  string

    Mobile phone number

  • nature_and_purpose  string

    Nature and purpose of the business

  • payout_zone_migrated  boolean

    True if the payout zone of this merchant is migrated

  • permanent_certificate_access_code  string

    Permanent certificate access code (Portugal)

  • settings  object

    Merchant settings (like "payout_type", "payout_period")

     Show attributes
     Close
    Attributes
    • daily_payout_email  boolean

      Whether merchant will receive daily payout emails

    • gross_settlement  boolean

      Whether merchant has gross settlement enabled

    • monthly_payout_email  boolean

      Whether merchant will receive monthly payout emails

    • moto_payment  string
      Options:  UNAVAILABLE ENFORCED ON OFF

      Whether merchant can make MOTO payments

    • payout_instrument  string

      Payout Instrument

    • payout_on_demand  boolean

      Whether merchant will receive payouts on demand

    • payout_on_demand_available  boolean

      Whether merchant can edit payouts on demand

    • payout_period  string

      Payout frequency

    • payout_type  string

      Payout type

    • printers_enabled  boolean

      Whether to show printers in mobile app

    • stone_merchant_code  string

      Stone merchant code

    • tax_enabled  boolean

      Whether to show tax in receipts (saved per transaction)

  • vat_id  string

    Vat ID

  • vat_rates  object

    Merchant VAT rates

     Show attributes
     Close
    Attributes
    • country  string

      Country ISO code

    • description  string

      Description

    • id  number

      Internal ID

    • ordering  number

      Ordering

    • rate  number

      Rate

  • website  string

    Website

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

List bank accounts

Retrives bank accounts of the merchant.

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

Query Parameters

  • primary  boolean

Response 200

 []object
 Show attributes
 Close
Attributes
  • account_category  string

    Account category - business or personal

  • account_holder_name  string
  • account_number  string

    Account number

  • account_type  string

    Type of the account

  • bank_code  string

    Bank code

  • bank_name  string

    Bank name

  • branch_code  string

    Branch code

  • created_at  string

    Creation date of the bank account

  • iban  string

    IBAN

  • primary  boolean

    The primary bank account is the one used for settlements

  • status  string

    Status in the verification process

  • swift  string

    SWIFT code

get  /v0.1/me/merchant-profile/bank-accounts
curl https://api.sumup.com/v0.1/me/merchant-profile/bank-accounts
List bank accounts response
[
  {
    "account_category": null,
    "account_holder_name": null,
    "account_number": null,
    "account_type": null,
    "bank_code": null,
    "bank_name": null,
    "branch_code": null,
    "created_at": null,
    "iban": null,
    "primary": null,
    "status": null,
    "swift": null
  }
]
Merchant

Retrieve DBA

Retrieves Doing Business As profile.

Scopes: user.profile user.profile_readonly

Response 200

  • address  object
     Show attributes
     Close
    Attributes
    • address_line1  string

      Address line 1

    • address_line2  string

      Address line 2

    • city  string

      City

    • country  string

      Country ISO 3166-1 code

    • post_code  string

      Postal code

    • region_id  number

      Country region ID

    • region_name  string

      Country region name

  • business_name  string

    Doing business as name

  • company_registration_number  string

    Doing business as company registration number

  • email  string

    Doing business as email

  • vat_id  string

    Doing business as VAT ID

  • website  string

    Doing business as website

get  /v0.1/me/merchant-profile/doing-business-as
curl https://api.sumup.com/v0.1/me/merchant-profile/doing-business-as
Retrieve DBA response
{
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "post_code": null,
    "region_id": null,
    "region_name": null
  },
  "business_name": null,
  "company_registration_number": null,
  "email": null,
  "vat_id": null,
  "website": null
}
Merchant

Get settings

Retrieves merchant settings.

Scopes: user.payout-settings

Response 200

  • daily_payout_email  boolean

    Whether merchant will receive daily payout emails

  • gross_settlement  boolean

    Whether merchant has gross settlement enabled

  • monthly_payout_email  boolean

    Whether merchant will receive monthly payout emails

  • moto_payment  string
    Options:  UNAVAILABLE ENFORCED ON OFF

    Whether merchant can make MOTO payments

  • payout_instrument  string

    Payout Instrument

  • payout_on_demand  boolean

    Whether merchant will receive payouts on demand

  • payout_on_demand_available  boolean

    Whether merchant can edit payouts on demand

  • payout_period  string

    Payout frequency

  • payout_type  string

    Payout type

  • printers_enabled  boolean

    Whether to show printers in mobile app

  • stone_merchant_code  string

    Stone merchant code

  • tax_enabled  boolean

    Whether to show tax in receipts (saved per transaction)

get  /v0.1/me/merchant-profile/settings
curl https://api.sumup.com/v0.1/me/merchant-profile/settings
Get settings response
{
  "daily_payout_email": null,
  "gross_settlement": null,
  "monthly_payout_email": null,
  "moto_payment": null,
  "payout_instrument": null,
  "payout_on_demand": null,
  "payout_on_demand_available": null,
  "payout_period": null,
  "payout_type": null,
  "printers_enabled": null,
  "stone_merchant_code": null,
  "tax_enabled": null
}
Merchant

Retrieve a personal profile

Retrieves personal profile data.

Scopes: user.profile user.profile_readonly

Response 200

  • address  object

    Details of the registered address.

     Show attributes
     Close
    Attributes
    • address_line1  string

      Address line 1

    • address_line2  string

      Address line 2

    • city  string

      City

    • company  string

      undefined

    • country  string

      Country ISO 3166-1 code

    • country_details  object

      Country Details

       Show attributes
       Close
      Attributes
      • currency  string

        Currency ISO 4217 code

      • en_name  string

        Country EN name

      • iso_code  string

        Country ISO code

      • native_name  string

        Country native name

    • first_name  string

      undefined

    • landline  string

      Landline number

    • last_name  string

      undefined

    • post_code  string

      Postal code

    • region_code  string

      Region code

    • region_id  number

      Country region id

    • region_name  string

      Region name

    • state_id  string

      undefined

    • timeoffset_details  object

      TimeOffset Details

       Show attributes
       Close
      Attributes
      • dst  boolean

        Daylight Saving Time

      • offset  number

        UTC offset

      • post_code  string

        Postal code

  • complete  boolean
  • date_of_birth  string

    Date of birth

  • first_name  string

    First name of the user

  • last_name  string

    Last name of the user

  • mobile_phone  string

    Mobile phone number

get  /v0.1/me/personal-profile
curl https://api.sumup.com/v0.1/me/personal-profile
Retrieve a personal profile response
{
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "company": null,
    "country": null,
    "country_details": {
      "currency": null,
      "en_name": null,
      "iso_code": null,
      "native_name": null
    },
    "first_name": null,
    "landline": null,
    "last_name": null,
    "post_code": null,
    "region_code": null,
    "region_id": null,
    "region_name": null,
    "state_id": null,
    "timeoffset_details": {
      "dst": null,
      "offset": null,
      "post_code": null
    }
  },
  "complete": null,
  "date_of_birth": null,
  "first_name": null,
  "last_name": null,
  "mobile_phone": null
}

Subaccounts

Endpoints for managing merchant sub-accounts (operators).

The object

Attributes

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
The object
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}
Subaccounts

List operators.
Deprecated

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

Scopes:

Query Parameters

  • query  string
  • include_primary  boolean

Response 200

 []object
 Show attributes
 Close
Attributes
  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
get  /v0.1/me/accounts
curl https://api.sumup.com/v0.1/me/accounts
List operators. response
[
  {
    "account_type": "",
    "created_at": "",
    "disabled": false,
    "id": 0,
    "nickname": "Operator 1",
    "permissions": {
      "admin": false,
      "create_moto_payments": false,
      "create_referral": false,
      "full_transaction_history_view": false,
      "refund_transactions": false
    },
    "updated_at": "",
    "username": "[email protected]"
  }
]
Subaccounts

Create operator.
Deprecated

Creates new operator for currently authorized users' merchant.

Scopes:

Body Parameters

  • nickname  string
    Example: "Operator 1"
  • password  string  required
    Example: "correct horse batter staple"
  • permissions  object
     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean
    • create_referral  boolean
    • full_transaction_history_view  boolean
    • refund_transactions  boolean
  • username  string  required
    Example: "[email protected]"

Response 200

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
post  /v0.1/me/accounts
curl https://api.sumup.com/v0.1/me/accounts
Create operator. response
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}
Subaccounts

Get operator
Deprecated

Returns specific operator.

Scopes:

Path Parameters

  • operator_id  integer  required

Response 200

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
get  /v0.1/me/accounts/{operator_id}
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}
Get operator response
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}
Subaccounts

Update operator.
Deprecated

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

Scopes:

Path Parameters

  • operator_id  integer  required

Body Parameters

  • disabled  boolean
  • nickname  string
    Example: "Operator 1"
  • password  string
    Example: "correct horse batter staple"
  • permissions  object
     Show attributes
     Close
    Attributes
    • create_moto_payments  boolean
    • create_referral  boolean
    • full_transaction_history_view  boolean
    • refund_transactions  boolean
  • username  string

Response 200

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
put  /v0.1/me/accounts/{operator_id}
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}
Update operator. response
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}
Subaccounts

Disable operator.
Deprecated

Scopes:

Path Parameters

  • operator_id  integer  required

Response 200

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
delete  /v0.1/me/accounts/{operator_id}
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}
Disable operator. response
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}
Subaccounts

Disable operator.
Deprecated

Scopes:

Path Parameters

  • operator_id  integer  required

Response 200

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
post  /v0.1/me/accounts/{operator_id}/disable
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}/disable
Disable operator. response
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}
Subaccounts

Change operators password.
Deprecated

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

Scopes:

Path Parameters

  • operator_id  integer  required

Body Parameters

  • password  string
    Example: "correct horse batter staple"

Response 200

  • account_type  string  required
    Options:  operator normal
  • created_at  string  required
  • disabled  boolean  required
  • id  integer  required
  • nickname  string
    Example: "Operator 1"
  • permissions  object  required
     Show attributes
     Close
    Attributes
    • admin  boolean  required
    • create_moto_payments  boolean  required
    • create_referral  boolean  required
    • full_transaction_history_view  boolean  required
    • refund_transactions  boolean  required
  • updated_at  string  required
  • username  string  required
    Example: "[email protected]"
put  /v0.1/me/accounts/{operator_id}/reset
curl https://api.sumup.com/v0.1/me/accounts/{operator_id}/reset
Change operators password. response
{
  "account_type": "",
  "created_at": "",
  "disabled": false,
  "id": 0,
  "nickname": "Operator 1",
  "permissions": {
    "admin": false,
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false
  },
  "updated_at": "",
  "username": "[email protected]"
}

Payouts

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

The Financial Payouts object

Attributes

 []object
 Show attributes
 Close
Attributes
  • amount  number
  • currency  string
  • date  string
  • fee  number
  • id  integer
  • reference  string
  • status  string
    Options:  SUCCESSFUL FAILED
  • transaction_code  string
  • type  string
    Options:  PAYOUT CHARGE_BACK_DEDUCTION REFUND_DEDUCTION DD_RETURN_DEDUCTION BALANCE_DEDUCTION
The Financial Payouts object
[
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]
Payouts

List payouts

Lists ordered payouts for the merchant profile.

Scopes: user.profile user.profile_readonly

Query Parameters

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

Response 200

 []object
 Show attributes
 Close
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
get  /v0.1/me/financials/payouts
curl https://api.sumup.com/v0.1/me/financials/payouts
List payouts response
[
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]

Transactions

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

Transactions

Refund a transaction

Refunds an identified transaction either in full or partially.

Scopes: payments

Path Parameters

  • txn_id  string  required

Body Parameters

  • amount  number

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

Response 204

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

Retrieve a transaction

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

  • id
  • internal_id
  • transaction_code
  • foreign_transaction_id
  • client_transaction_id
Scopes: transactions.history

Query Parameters

  • id  string
  • internal_id  string
  • transaction_code  string

Response 200

  • amount  number

    Total amount of the transaction.

    Example: 10.1
  • currency  string

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

    Example: "EUR"
  • id  string

    Unique ID of the transaction.

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

    Current number of the installment for deferred payments.

  • payment_type  string
    Options:  ECOM RECURRING BOLETO

    Payment type used for the transaction.

  • status  string
    Options:  SUCCESSFUL CANCELLED FAILED PENDING

    Current status of the transaction.

  • timestamp  string

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

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

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

    Example: "TEENSK4W2K"
  • auth_code  string

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

    Example: "053201"
  • entry_mode  string
    Options:  CUSTOMER_ENTRY BOLETO

    Entry mode of the payment details.

  • internal_id  integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • merchant_code  string

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

    Example: "MH4H92C7"
  • tip_amount  number

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

    Example: 3
  • vat_amount  number

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

    Example: 6
  • payout_plan  string
    Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

  • payouts_received  integer

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

  • payouts_total  integer

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

  • product_summary  string

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

  • card  object

    Details of the payment card.

     Show attributes
     Close
    Attributes
    • last_4_digits  string

      Last 4 digits of the payment card number.

      Example: "3456"
    • type  string
      Options:  AMEX CUP DINERS DISCOVER ELO ELV HIPERCARD JCB MAESTRO MASTERCARD VISA VISA_ELECTRON VISA_VPAY UNKNOWN

      Issuing card network of the payment card.

  • events  []object

    List of events related to the transaction.

     Show attributes
     Close
    Attributes
    • amount  number

      Amount of the event.

    • deducted_amount  number

      Amount deducted for the event.

    • deducted_fee_amount  number

      Amount of the fee deducted for the event.

    • fee_amount  number

      Amount of the fee related to the event.

    • id  integer

      Unique ID of the transaction event.

    • installment_number  integer

      Consecutive number of the installment.

    • status  string

      Status of the transaction event.

    • timestamp  string

      Date and time of the transaction event.

    • transaction_id  string

      Unique ID of the transaction.

    • type  string

      Type of the transaction event.

  • horizontal_accuracy  number

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

  • lat  number

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

  • links  []object

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Attributes
  • local_time  string

    Local date and time of the creation of the transaction.

  • location  object

    Details of the payment location as received from the payment terminal.

     Show attributes
     Close
    Attributes
    • horizontal_accuracy  number

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

    • lat  number

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

    • lon  number

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

  • lon  number

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

  • payout_type  string
    Options:  BANK_ACCOUNT BALANCE PREPAID_CARD

    Payout type for the transaction.

  • products  []object

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

     Show attributes
     Close
    Attributes
    • name  string

      Name of the product from the merchant's catalog.

    • price  number

      Price of the product without VAT.

    • price_with_vat  number

      Price of a single product item with VAT.

    • quantity  number

      Number of product items for the purchase.

    • single_vat_amount  number

      Amount of the VAT for a single product item (calculated as the product of price and vat_rate, i.e. single_vat_amount = price * vat_rate).

    • total_price  number

      Total price of the product items without VAT (calculated as the product of price and quantity, i.e. total_price = price * quantity).

    • total_with_vat  number

      Total price of the product items including VAT (calculated as the product of price_with_vat and quantity, i.e. total_with_vat = price_with_vat * quantity).

    • vat_amount  number

      Total VAT amount for the purchase (calculated as the product of single_vat_amount and quantity, i.e. vat_amount = single_vat_amount * quantity).

    • vat_rate  number

      VAT rate applicable to the product.

  • simple_payment_type  string
    Options:  MOTO CASH CC_SIGNATURE ELV CC_CUSTOMER_ENTERED MANUAL_ENTRY EMV

    Simple name of the payment type.

  • simple_status  string
    Options:  SUCCESSFUL PAID_OUT CANCEL_FAILED CANCELLED CHARGEBACK FAILED REFUND_FAILED REFUNDED NON_COLLECTION

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

  • tax_enabled  boolean

    Indicates whether tax deduction is enabled for the transaction.

  • transaction_events  []object

    List of transaction events related to the transaction.

     Show attributes
     Close
    Attributes
    • amount  number

      Amount of the event.

    • date  string

      Date when the transaction event occurred.

    • due_date  string

      Date when the transaction event is due to occur.

    • event_type  string

      Type of the transaction event.

    • id  integer

      Unique ID of the transaction event.

    • installment_number  integer

      Consequtive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT.

    • status  string

      Status of the transaction event.

    • timestamp  string

      Date and time of the transaction event.

  • username  string

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

  • vat_rates  []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
  • verification_method  string
    Options:  none signature offline pin online pin offline pin + signature confirmation code verified

    Verification method used for the transaction.

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

List transactions

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

Scopes: transactions.history

Query Parameters

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

Response 200

  • items  []object
     Show attributes
     Close
    Attributes
    • amount  number

      Total amount of the transaction.

      Example: 10.1
    • currency  string

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

      Example: "EUR"
    • id  string

      Unique ID of the transaction.

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

      Current number of the installment for deferred payments.

    • payment_type  string
      Options:  ECOM RECURRING BOLETO

      Payment type used for the transaction.

    • status  string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • timestamp  string

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

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

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

      Example: "TEENSK4W2K"
    • payout_plan  string
      Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

    • payouts_received  integer

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

    • payouts_total  integer

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

    • product_summary  string

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

    • card_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.

    • client_transaction_id  string

      Client-specific ID of the transaction.

    • transaction_id  string

      Unique ID of the transaction.

    • type  string
      Options:  PAYMENT REFUND CHARGE_BACK

      Type of the transaction for the registered user specified in the user property.

    • user  string

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

  • links  []object
     Show attributes
     Close
    Attributes
    • href  string

      URL for accessing the related resource.

    • rel  string

      Specifies the relation to the current resource.

    • type  string

      Specifies the media type of the related resource.

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

API Keys

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

The API Key object

Attributes

  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    Unique identifier of the API Key.

    Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
  • name  string  required

    User-assigned name of the API Key.

    Example: "My API Key"
  • plaintext  string

    The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

    Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
  • preview  string  required

    Last 8 characters of the API key.

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

List API keys

Returns paginated list of API keys.

Scopes: api_keys

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Query Parameters

  • offset  integer
    0
  • limit  integer
    Example: 10

Response 200

  • items  []object  required
     Show attributes
     Close
    Attributes
    • created_at  string  required
      Example: "2023-01-20T15:16:17Z"
    • id  string  required

      Unique identifier of the API Key.

      Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
    • name  string  required

      User-assigned name of the API Key.

      Example: "My API Key"
    • plaintext  string

      The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

      Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
    • preview  string  required

      Last 8 characters of the API key.

      Example: "p6cL1vyZ"
    • scopes  []string  required
    • type  string  required
      Options:  public secret
      Example: "secret"
    • updated_at  string  required
      Example: "2023-01-20T15:16:17Z"
  • total_count  integer  required
get  /v0.1/merchants/{merchant_code}/api-keys
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys
List API keys response
{
  "items": [
    {
      "created_at": "2023-03-24T10:10:10Z",
      "id": "sup_pk_1tpmgizNLHMkx1DdKd2hdzorZAaf6AcZ9",
      "name": "",
      "preview": "Aaf6AcZ9",
      "scopes": [],
      "type": "public",
      "updated_at": "2023-03-24T10:10:10Z"
    },
    {
      "created_at": "2023-03-25T09:10:10Z",
      "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
      "name": "Test Key",
      "preview": "TGhqew1b",
      "scopes": [
        "transactions.history",
        "user.app-settings",
        "user.profile_readonly",
        "user.profile",
        "user.subaccounts",
        "user.payout-settings",
        "products",
        "payments",
        "payment_instruments",
        "readers.read",
        "readers.write"
      ],
      "type": "secret",
      "updated_at": "2023-03-25T09:10:10Z"
    }
  ],
  "total_count": 2
}
API Keys

Create an API key

Creates a new API key for the user.

Scopes: api_keys:write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Body Parameters

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

Response 201

  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    Unique identifier of the API Key.

    Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
  • name  string  required

    User-assigned name of the API Key.

    Example: "My API Key"
  • plaintext  string

    The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

    Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
  • preview  string  required

    Last 8 characters of the API key.

    Example: "p6cL1vyZ"
  • scopes  []string  required
  • type  string  required
    Options:  public secret
    Example: "secret"
  • updated_at  string  required
    Example: "2023-01-20T15:16:17Z"
post  /v0.1/merchants/{merchant_code}/api-keys
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys
Create an API key response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}
API Keys

Retrieve an API Key

Gets an API key.

Scopes: api_keys

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • key_id  string  required
    Example: sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9

Response 200

  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    Unique identifier of the API Key.

    Example: "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU"
  • name  string  required

    User-assigned name of the API Key.

    Example: "My API Key"
  • plaintext  string

    The plaintext value of the API key. This field is returned only in the response to API key creation and is never again available in the plaintext form.

    Example: "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ"
  • preview  string  required

    Last 8 characters of the API key.

    Example: "p6cL1vyZ"
  • scopes  []string  required
  • type  string  required
    Options:  public secret
    Example: "secret"
  • updated_at  string  required
    Example: "2023-01-20T15:16:17Z"
get  /v0.1/merchants/{merchant_code}/api-keys/{key_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}
Retrieve an API Key response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "sup_pk_0D1FIpM6xqueY3L4Y994nseK0xMfOjPAU",
  "name": "My API Key",
  "plaintext": "sup_sk_LZFWoLydp6S4S4KQpGVs1POzzp6cL1vyZ",
  "preview": "p6cL1vyZ",
  "scopes": [
    "invoices.read",
    "invoices.write",
    "products",
    "user.app-settings"
  ],
  "type": "secret",
  "updated_at": "2023-01-20T15:16:17Z"
}
API Keys

Update an API key

Updates an API key.

Scopes: api_keys:write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • key_id  string  required
    Example: sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9

Body Parameters

  • name  string  required

    New name for the API key.

    Example: "My API Key"
  • scopes  []string  required
put  /v0.1/merchants/{merchant_code}/api-keys/{key_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}
API Keys

Revoke an API key

Revokes an API key.

Scopes: api_keys:write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • key_id  string  required
    Example: sup_pk_1tpmgSzNUHMkxZD1Kz2hdQorZAav6AcZ9
delete  /v0.1/merchants/{merchant_code}/api-keys/{key_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/api-keys/{key_id}

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 speicfic resource identified by resource id, resource type, and associated roles.

Attributes

  • attributes  object

    Object attributes that modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • 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"
  • 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: {}
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • status  string  required
  • updated_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • user  object

    User information.

     Show attributes
     Close
    Attributes
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • 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]"
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • nickname  string

      User's perferred 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"
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

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

List members

Lists merchant members with their roles and permissions.

Scopes:

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Query Parameters

  • offset  integer
    0
  • limit  integer
    Example: 10
  • email  string
    Example: user
  • status  string
  • roles  []string
    Example: role_employeerole_accountant

Response 200

  • items  []object  required
     Show attributes
     Close
    Attributes
    • attributes  object

      Object attributes that modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
    • created_at  string  required
      Example: "2023-01-20T15:16:17Z"
    • id  string  required

      ID of the member.

      Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • 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"
    • 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: {}
    • permissions  []string  required

      User's permissions.

       Show attributes
       Close
      Attributes
    • roles  []string  required

      User's roles.

       Show attributes
       Close
      Attributes
    • status  string  required
    • updated_at  string  required
      Example: "2023-01-20T15:16:17Z"
    • user  object

      User information.

       Show attributes
       Close
      Attributes
      • classic  object

        Classic identifiers of the user.

         Show attributes
         Close
        Attributes
        • user_id  integer  required
      • disabled_at  string

        Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

      • 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]"
      • id  string  required

        Identifier for the End-User (also called Subject).

        Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
      • mfa_on_login_enabled  boolean  required

        True if the user has enabled MFA on login.

        Example: true
      • nickname  string

        User's perferred 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"
      • virtual_user  boolean  required

        True if the user is a virtual user (operator).

  • total_count  integer  required
    Example: 3
get  /v0.1/merchants/{merchant_code}/members
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members
List members response
{
  "items": [
    {
      "created_at": "2023-01-20T15:16:17Z",
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_write",
        "developer_settings_read"
      ],
      "roles": [
        "role_admin",
        "role_member"
      ],
      "status": "accepted",
      "updated_at": "2023-02-20T15:16:17Z",
      "user": {
        "email": "[email protected]",
        "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
        "mfa_on_login_enabled": true,
        "virtual_user": false
      }
    }
  ],
  "total_count": 3
}
Members

Add member to merchant.

Scopes:

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Body Parameters

  • attributes  object

    Object attributes that modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • email  string  required

    Email address of the member to add.

  • 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.

  • 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: {}
  • nickname  string

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

    Example: "Test User"
  • password  string

    Password of the member to add. Only used if is_managed_user is true.

  • roles  []string  required

    List of roles to assign to the new member.

     Show attributes
     Close
    Attributes

Response 201

  • attributes  object

    Object attributes that modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • 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"
  • 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: {}
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • status  string  required
  • updated_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • user  object

    User information.

     Show attributes
     Close
    Attributes
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • 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]"
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • nickname  string

      User's perferred 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"
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

post  /v0.1/merchants/{merchant_code}/members
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members
Add member to merchant. response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_write",
    "developer_settings_read"
  ],
  "roles": [
    "role_admin",
    "role_member"
  ],
  "status": "accepted",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "email": "[email protected]",
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "mfa_on_login_enabled": true,
    "virtual_user": false
  }
}
Members

Get merchant member

Returns merchant member details.

Scopes:

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • member_id  string  required
    Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Response 200

  • attributes  object

    Object attributes that modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • 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"
  • 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: {}
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • status  string  required
  • updated_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • user  object

    User information.

     Show attributes
     Close
    Attributes
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • 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]"
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • nickname  string

      User's perferred 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"
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

get  /v0.1/merchants/{merchant_code}/members/{member_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id}
Get merchant member response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_write",
    "developer_settings_read"
  ],
  "roles": [
    "role_admin",
    "role_member"
  ],
  "status": "accepted",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "email": "[email protected]",
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "mfa_on_login_enabled": true,
    "virtual_user": false
  }
}
Members

Update merchant member

Update assigned roles of the member.

Scopes:

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • member_id  string  required
    Example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP

Body Parameters

  • attributes  object

    Object attributes that modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • 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: {}
  • roles  []string
     Show attributes
     Close
    Attributes
  • user  object

    Allows you to update user data of managed users.

     Show attributes
     Close
    Attributes
    • nickname  string

      User's perferred 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

  • attributes  object

    Object attributes that modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • id  string  required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • 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"
  • 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: {}
  • permissions  []string  required

    User's permissions.

     Show attributes
     Close
    Attributes
  • roles  []string  required

    User's roles.

     Show attributes
     Close
    Attributes
  • status  string  required
  • updated_at  string  required
    Example: "2023-01-20T15:16:17Z"
  • user  object

    User information.

     Show attributes
     Close
    Attributes
    • classic  object

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id  integer  required
    • disabled_at  string

      Time when the user has been disabled. Applies only to virtual users (virtual_user: true).

    • 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]"
    • id  string  required

      Identifier for the End-User (also called Subject).

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • mfa_on_login_enabled  boolean  required

      True if the user has enabled MFA on login.

      Example: true
    • nickname  string

      User's perferred 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"
    • virtual_user  boolean  required

      True if the user is a virtual user (operator).

put  /v0.1/merchants/{merchant_code}/members/{member_id}
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id}
Update merchant member response
{
  "created_at": "2023-01-20T15:16:17Z",
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_write",
    "developer_settings_read"
  ],
  "roles": [
    "role_admin",
    "role_member"
  ],
  "status": "accepted",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "email": "[email protected]",
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "mfa_on_login_enabled": true,
    "virtual_user": false
  }
}
Members

Delete member

Deletes member by ID.

Scopes:

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}

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

  • created_at  string  required

    Reader creation timestamp.

    Example: "2023-01-18T15:16:17Z"
  • 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"
  • 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"
  • meta  object

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

     Show attributes
     Close
    Attributes
    Example: {}
  • 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 ressource needs to get recreated
    Example: "paired"
  • updated_at  string  required

    Reader last-modification timestamp.

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

List Readers

Returns list of 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
    • created_at  string  required

      Reader creation timestamp.

      Example: "2023-01-18T15:16:17Z"
    • 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"
    • 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"
    • meta  object

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

       Show attributes
       Close
      Attributes
      Example: {}
    • 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 ressource needs to get recreated
      Example: "paired"
    • updated_at  string  required

      Reader last-modification timestamp.

      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": [
    {
      "created_at": "2023-01-18T15:16:17Z",
      "device": {
        "identifier": "U1DT3NA00-CN",
        "model": "solo"
      },
      "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
      "meta": {},
      "name": "Frontdesk",
      "status": "paired",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}
Readers

Create a Reader

Create a new reader linked to the merchant account.

Scopes: readers.write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC

Body Parameters

  • meta  object

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

     Show attributes
     Close
    Attributes
    Example: {}
  • name  string

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

    Example: "Frontdesk"
  • 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"

Response 201

  • created_at  string  required

    Reader creation timestamp.

    Example: "2023-01-18T15:16:17Z"
  • 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"
  • 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"
  • meta  object

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

     Show attributes
     Close
    Attributes
    Example: {}
  • 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 ressource needs to get recreated
    Example: "paired"
  • updated_at  string  required

    Reader last-modification timestamp.

    Example: "2023-01-20T15:16:17Z"
post  /v0.1/merchants/{merchant_code}/readers
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers
Response
""
Readers

Retrieve a Reader

Gets a Reader.

Scopes: readers.read

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • id  string  required
    Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Response 200

  • created_at  string  required

    Reader creation timestamp.

    Example: "2023-01-18T15:16:17Z"
  • 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"
  • 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"
  • meta  object

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

     Show attributes
     Close
    Attributes
    Example: {}
  • 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 ressource needs to get recreated
    Example: "paired"
  • updated_at  string  required

    Reader last-modification timestamp.

    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
{
  "created_at": "2023-01-18T15:16:17Z",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "meta": {},
  "name": "Frontdesk",
  "status": "paired",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Delete a reader

Deletes 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

Update a Reader

Updates a Reader.

Scopes: readers.write

Path Parameters

  • merchant_code  string  required
    Example: MC0X0ABC
  • id  string  required
    Example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65

Body Parameters

  • meta  object

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

     Show attributes
     Close
    Attributes
    Example: {}
  • name  string

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

    Example: "Frontdesk"
patch  /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

  • 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"
    • 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"
    • 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"
    • tags  object

      Additional metadata for the transaction. It is key-value object that can be associoated with the transaction.

       Show attributes
       Close
      Attributes
      Example: {}
  • 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"
  • description  string

    Description of the checkout to be shown in the Merchant Sales

  • 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"
  • 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
  • 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
    • 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
    • value  integer  required

      Total amount of the transaction. It must be a positive integer.

      Example: 1000

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

Receipts

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

The Receipt object

Attributes

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

    Receipt merchant data

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

    Transaction information.

     Show attributes
     Close
    Attributes
    • amount  string

      Transaction amount.

    • card  object
       Show attributes
       Close
      Attributes
      • last_4_digits  string

        Card last 4 digits.

      • type  string

        Card Scheme.

    • currency  string

      Transaction currency.

    • entry_mode  string

      Transaction entry mode.

    • events  []object

      Events

       Show attributes
       Close
      Attributes
      • amount  number

        Amount of the event.

      • id  integer

        Unique ID of the transaction event.

      • receipt_no  string
      • status  string

        Status of the transaction event.

      • timestamp  string

        Date and time of the transaction event.

      • transaction_id  string

        Unique ID of the transaction.

      • type  string

        Type of the transaction event.

    • installments_count  integer

      Number of installments.

    • payment_type  string

      Transaction type.

    • products  []object

      Products

       Show attributes
       Close
      Attributes
      • description  string

        Product description.

      • name  string

        Product name.

      • price  number

        Product price.

      • quantity  integer

        Product quantity.

      • total_price  number

        Quantity x product price.

    • receipt_no  string

      Receipt number

    • status  string

      Transaction processing status.

    • timestamp  string

      Time created at.

    • tip_amount  string

      Tip amount (included in transaction amount).

    • transaction_code  string

      Transaction code.

    • vat_amount  string

      Transaction VAT amount.

    • vat_rates  []object

      Vat rates.

       Show attributes
       Close
      Attributes
      • gross  number

        Gross

      • net  number

        Net

      • rate  number

        Rate

      • vat  number

        Vat

    • verification_method  string

      Cardholder verification method.

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

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Scopes:

Path Parameters

  • id  string  required

Query Parameters

  • mid  string  required
  • tx_event_id  integer

Response 200

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

    Receipt merchant data

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

    Transaction information.

     Show attributes
     Close
    Attributes
    • amount  string

      Transaction amount.

    • card  object
       Show attributes
       Close
      Attributes
      • last_4_digits  string

        Card last 4 digits.

      • type  string

        Card Scheme.

    • currency  string

      Transaction currency.

    • entry_mode  string

      Transaction entry mode.

    • events  []object

      Events

       Show attributes
       Close
      Attributes
      • amount  number

        Amount of the event.

      • id  integer

        Unique ID of the transaction event.

      • receipt_no  string
      • status  string

        Status of the transaction event.

      • timestamp  string

        Date and time of the transaction event.

      • transaction_id  string

        Unique ID of the transaction.

      • type  string

        Type of the transaction event.

    • installments_count  integer

      Number of installments.

    • payment_type  string

      Transaction type.

    • products  []object

      Products

       Show attributes
       Close
      Attributes
      • description  string

        Product description.

      • name  string

        Product name.

      • price  number

        Product price.

      • quantity  integer

        Product quantity.

      • total_price  number

        Quantity x product price.

    • receipt_no  string

      Receipt number

    • status  string

      Transaction processing status.

    • timestamp  string

      Time created at.

    • tip_amount  string

      Tip amount (included in transaction amount).

    • transaction_code  string

      Transaction code.

    • vat_amount  string

      Transaction VAT amount.

    • vat_rates  []object

      Vat rates.

       Show attributes
       Close
      Attributes
      • gross  number

        Gross

      • net  number

        Net

      • rate  number

        Rate

      • vat  number

        Vat

    • verification_method  string

      Cardholder verification method.

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