Skip to content
SumUp Developer

API Reference

SumUp API reference and code samples.

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

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

View YAML spec View JSON spec
Base URL
https://api.sumup.com

SDKs

The SumUp SDKs reduce the amount of work required to use our REST APIs. SumUp maintains SDKs for PHP, Node.js, Python, Go, Rust, and .NET.

SDKs

Install SDK
 
# Select a client library to see installation instructions.
npm install --save @sumup/sdk
go get github.com/sumup/sumup-go
// Maven
<dependency>
  <groupId>com.stripe</groupId>
  <artifactId>stripe-java</artifactId>
  <version>31.1.0</version>
</dependency>


// Gradle
compile "com.sumup:sumup:0.0.5"
dotnet add package SumUp
pip install python
composer require sumup/sumup-ecom-php-sdk
cargo add sumup

You can also explore out APIs in Postman using SumUp Developers public collection.

Authentication

The SumUp API uses API keys to authenticate requests. You can view, create, and manage your API keys in the Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Keep your API keys secret and safe. Do not share your API keys or expose them in a publicly accessible areas such as client-side code (browser or apps) or in the GitHub.

All API requests must be made over HTTPS and authenticated. Calls made over plain HTTP or calls without authentication will fail.

Authenticate
 
curl https://api.sumup.com/v0.1/checkouts \
  -H "Authorization: Bearer sup_sk_MvxmLOl0..."
import { SumUp } from '@sumup/sdk';


const sumup = new SumUp({ apiKey: 'sup_sk_MvxmLOl0...' });
package main


import (
  sumup "github.com/sumup/sumup-go"
)


func main() {
  client := sumup.NewClient().WithAuth("sup_sk_MvxmLOl0...")
}
SumUpClient client =
    SumUpClient.builder()
        .accessToken("sup_sk_MvxmLOl0...")
        .build();
using SumUp;


var client = new SumUpClient(new SumUpClientOptions
{
    AccessToken = "sup_sk_MvxmLOl0...",
});
from sumup import Sumup


client = SumUp(api_key="sup_sk_MvxmLOl0...")
composer require sumup/sumup-ecom-php-sdk
use sumup::Client;


let client = Client::default().with_authorization("sup_sk_MvxmLOl0...");

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.

Checkout

  • checkout_reference string max length: 90

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

  • amount number

    Amount of the payment.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • merchant_code string

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • id string read only

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDING FAILED PAID EXPIRED

    Current status of the checkout.

  • date string date-time

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

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

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

    Example: "831ff8d4cd5958ab5670"
  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

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

List checkouts

Lists created checkout resources according to the applied checkout_reference.

Required scopes: payments

Query Parameters

  • checkout_reference string

    Filters the list of checkout resources by the unique ID of the checkout.

Response 200

[]object
 Show attributes
 Close
Attributes
  • checkout_reference string max length: 90

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

  • amount number

    Amount of the payment.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • merchant_code string

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • id string read only

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDING FAILED PAID EXPIRED

    Current status of the checkout.

  • date string date-time

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

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

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

    Example: "831ff8d4cd5958ab5670"
  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • transaction_code string read only

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

    Example: "TEENSK4W2K"
  • transaction_id string read only

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

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

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url string

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

    Example: "https://mysite.com/completed_purchase"
  • payment_instrument object

    Object containing token information for the specified payment instrument

     Show attributes
     Close
    Attributes
    • token string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
GET /v0.1/checkouts 
curl https://api.sumup.com/v0.1/checkouts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.list();
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.ListAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().listCheckouts();
from sumup import Sumup


client = Sumup()


result = client.checkouts.list()
client := sumup.NewClient()


result, err := client.Checkouts.List(context.Background())
use sumup::Client;


let client = Client::default();


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

Create a checkout

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

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

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

Required scopes: payments

Body Parameters

  • checkout_reference string max length: 90 required

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

  • amount number required

    Amount of the payment.

  • currency string required

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

    Example: "EUR"
  • merchant_code string required

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • customer_id string

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

  • purpose string default: CHECKOUT
    Options:  CHECKOUT SETUP_RECURRING_PAYMENT

    Purpose of the checkout.

  • id string read only

    Unique ID of the checkout resource.

  • status string read only
    Options:  PENDING FAILED PAID

    Current status of the checkout.

  • date string date-timeread only

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

    Example: "2020-02-29T10:56:56+00:00"
  • transactions []object unique itemsread only

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • redirect_url string

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

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

Checkout

  • checkout_reference string max length: 90

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

  • amount number

    Amount of the payment.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • merchant_code string

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • id string read only

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDING FAILED PAID EXPIRED

    Current status of the checkout.

  • date string date-time

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

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

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

    Example: "831ff8d4cd5958ab5670"
  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
POST /v0.1/checkouts 
curl https://api.sumup.com/v0.1/checkouts \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "checkout_reference": "",
    "amount": 0,
    "currency": "EUR",
    "merchant_code": "MH4H92C7"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.create({
  checkout_reference: "",
  amount: 0,
  currency: "EUR",
  merchant_code: "MH4H92C7",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.CreateAsync(
    new CheckoutCreateRequest
    {
        CheckoutReference = "",
        Amount = 0,
        Currency = "EUR",
        MerchantCode = "MH4H92C7",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().createCheckout(
  CheckoutCreateRequest.builder()
    .checkoutReference("")
    .amount(0f)
    .currency(Currency.fromValue("EUR"))
    .merchantCode("MH4H92C7")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.create(CreateCheckoutBody(
  checkout_reference="",
  amount=0,
  currency="EUR",
  merchant_code="MH4H92C7",
))
client := sumup.NewClient()


result, err := client.Checkouts.Create(context.Background(), checkouts.CreateCheckoutBody{
  CheckoutReference: "",
  Amount: 0,
  Currency: "EUR",
  MerchantCode: "MH4H92C7",
})
use sumup::Client;


let client = Client::default();


let result = client.checkouts().create(sumup::CreateCheckoutBody{
  checkout_reference: "".to_string(),
  amount: 0,
  currency: "EUR".to_string(),
  merchant_code: "MH4H92C7".to_string(),
}).await;
Response
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "merchant_country": "DE",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "012345",
      "internal_id": 0
    }
  ]
}
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "redirect_url": "https://mysite.com/completed_purchase",
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "012345",
      "internal_id": 0
    }
  ]
}
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2021-06-29T11:08:36.000+00:00",
  "merchant_name": "My company",
  "merchant_country": "DE",
  "redirect_url": "https://sumup.com",
  "purpose": "CHECKOUT",
  "transactions": [
    {
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "installments_count": 1,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": "CUSTOMER_ENTRY",
      "auth_code": "012345",
      "internal_id": 0
    }
  ]
}
Checkouts

Retrieve a checkout

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

Required scopes: payments

Path Parameters

  • id string required

    Unique ID of the checkout resource.

Response 200

  • checkout_reference string max length: 90

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

  • amount number

    Amount of the payment.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • merchant_code string

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • id string read only

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDING FAILED PAID EXPIRED

    Current status of the checkout.

  • date string date-time

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

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

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

    Example: "831ff8d4cd5958ab5670"
  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • transaction_code string read only

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

    Example: "TEENSK4W2K"
  • transaction_id string read only

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

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

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url string

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

    Example: "https://mysite.com/completed_purchase"
  • payment_instrument object

    Object containing token information for the specified payment instrument

     Show attributes
     Close
    Attributes
    • token string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
GET /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.get("id");
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.GetAsync(
    "id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().getCheckout(
  "id"
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.get("id")
client := sumup.NewClient()


result, err := client.Checkouts.Get(context.Background(), "id")
use sumup::Client;


let client = Client::default();


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

Process a checkout

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

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

Path Parameters

  • id string required

    Unique ID of the checkout resource.

Body Parameters

  • payment_type string required
    Options:  card boleto ideal blik bancontact

    Describes the payment method used to attempt processing

  • installments integer minimum: 1maximum: 12

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

  • mandate object

    Mandate is passed when a card is to be tokenized

     Show attributes
     Close
    Attributes
    • type string required
      Options:  recurrent

      Indicates the mandate type

    • user_agent string required

      Operating system and web client used by the end-user

    • user_ip string

      IP address of the end user. Supports IPv4 and IPv6

    Example: {"type":"recurrent","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36","user_ip":"172.217.169.174"}
  • card object

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

     Show attributes
     Close
    Attributes
    • name string write only required

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

      Example: "FIRSTNAME LASTNAME"
    • number string write only required

      Number of the payment card (without spaces).

      Example: "1234567890123456"
    • expiry_year string min length: 2max length: 4write only required

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

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

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

    • cvv string min length: 3max length: 4write only required

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

      Example: "123"
    • zip_code string min length: 5max length: 5write only

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

      Example: "12345"
    • last_4_digits string min length: 4max length: 4read only required

      Last 4 digits of the payment card number.

      Example: "3456"
    • type string required

      Issuing card network of the payment card used for the transaction.

  • token string

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

  • customer_id string

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

  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Response 200

  • checkout_reference string max length: 90

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

  • amount number

    Amount of the payment.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • merchant_code string

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • id string read only

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDING FAILED PAID EXPIRED

    Current status of the checkout.

  • date string date-time

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

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

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

    Example: "831ff8d4cd5958ab5670"
  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • transaction_code string read only

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

    Example: "TEENSK4W2K"
  • transaction_id string read only

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

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

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url string

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

    Example: "https://mysite.com/completed_purchase"
  • payment_instrument object

    Object containing token information for the specified payment instrument

     Show attributes
     Close
    Attributes
    • token string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"

Response 202

  • next_step object

    Required action processing 3D Secure payments.

     Show attributes
     Close
    Attributes
    • url string

      Where the end user is redirected.

      Example: "https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A"
    • method string

      Method used to complete the redirect.

      Example: "POST"
    • redirect_url string

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

      Example: "https://mysite.com/completed_purchase"
    • mechanism []string

      Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either.

       Show attributes
       Close
      Attributes
    • payload object

      Contains parameters essential for form redirection. Number of object keys and their content can vary.

       Show attributes
       Close
      Attributes
      • PaReq
        Example: "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw=="
      • MD
        Example: "b1a536c0-29b9-11eb-adc1-0242ac120002"
      • TermUrl
        Example: "https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment"
PUT /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "payment_type": ""
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.process("id", {
  payment_type: "",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.ProcessAsync(
    "id",
    new ProcessCheckout
    {
        PaymentType = "",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().processCheckout(
  "id",
  ProcessCheckout.builder()
    .paymentType(PaymentType.fromValue(""))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.process("id", ProcessCheckoutBody(
  payment_type="",
))
client := sumup.NewClient()


result, err := client.Checkouts.Process(context.Background(), "id", checkouts.ProcessCheckoutBody{
  PaymentType: "",
})
use sumup::Client;


let client = Client::default();


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

Deactivate a checkout

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

Required scopes: payments

Path Parameters

  • id string required

    Unique ID of the checkout resource.

Checkout

  • checkout_reference string max length: 90

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

  • amount number

    Amount of the payment.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • merchant_code string

    Unique identifying code of the merchant profile.

    Example: "MH4H92C7"
  • description string

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

  • return_url string uri

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

  • id string read only

    Unique ID of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDING FAILED PAID EXPIRED

    Current status of the checkout.

  • date string date-time

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

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string date-timenullable

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

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

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

    Example: "831ff8d4cd5958ab5670"
  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    List of transactions related to the payment.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

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

      Example: "MH4H92C7"
    • vat_amount number

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

      Example: 6
    • tip_amount number

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

      Example: 3
    • entry_mode string

      Entry mode of the payment details.

    • auth_code string

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

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
DELETE /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.deactivate("id");
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.DeactivateAsync(
    "id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().deactivateCheckout(
  "id"
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.deactivate("id")
client := sumup.NewClient()


result, err := client.Checkouts.Deactivate(context.Background(), "id")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().deactivate("id").await;
Response
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
  "amount": 2,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Deletion example",
  "purpose": "CHECKOUT",
  "status": "EXPIRED",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "merchant_name": "Sample Merchant",
  "transactions": []
}
Checkouts

Get available payment methods

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

Required scopes: payments

Path Parameters

  • merchant_code string required

    The SumUp merchant code.

    Example: "MH4H92C7"

Query Parameters

  • amount number

    The amount for which the payment methods should be eligible, in major units. Note that currency must also be provided when filtering by amount.

    Example: 9.99
  • currency string

    The currency for which the payment methods should be eligible.

    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 \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.listAvailablePaymentMethods("MH4H92C7");
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.ListAvailablePaymentMethodsAsync(
    "MH4H92C7"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().getPaymentMethods(
  "MH4H92C7"
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.list_available_payment_methods("MH4H92C7")
client := sumup.NewClient()


result, err := client.Checkouts.ListAvailablePaymentMethods(context.Background(), "MH4H92C7")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().list_available_payment_methods("MH4H92C7", sumup::GetPaymentMethodsParams{
    amount: Some(9.99),
    currency: Some("EUR".to_string()),
}).await;
Response
{
  "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

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"
The Customer object
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Create a customer

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

Required scopes: payment_instruments

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"
POST /v0.1/customers 
curl https://api.sumup.com/v0.1/customers \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "customer_id": "831ff8d4cd5958ab5670"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.create({
  customer_id: "831ff8d4cd5958ab5670",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.CreateAsync(
    new Customer
    {
        CustomerId = "831ff8d4cd5958ab5670",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().createCustomer(
  Customer.builder()
    .customerId("831ff8d4cd5958ab5670")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.customers.create(CreateCustomerBody(
  customer_id="831ff8d4cd5958ab5670",
))
client := sumup.NewClient()


result, err := client.Customers.Create(context.Background(), customers.CreateCustomerBody{
  CustomerId: "831ff8d4cd5958ab5670",
})
use sumup::Client;


let client = Client::default();


let result = client.customers().create(sumup::CreateCustomerBody{
  customer_id: "831ff8d4cd5958ab5670".to_string(),
}).await;
Create a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Retrieve a customer

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"
GET /v0.1/customers/{customer_id} 
curl https://api.sumup.com/v0.1/customers/{customer_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.get("customer_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.GetAsync(
    "customer_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().getCustomer(
  "customer_id"
);
from sumup import Sumup


client = Sumup()


result = client.customers.get("customer_id")
client := sumup.NewClient()


result, err := client.Customers.Get(context.Background(), "customer_id")
use sumup::Client;


let client = Client::default();


let result = client.customers().get("customer_id").await;
Retrieve a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

Update a customer

Updates an identified saved customer resource's personal details.

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Body Parameters

  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Customer

  • customer_id string required

    Unique ID of the customer.

    Example: "831ff8d4cd5958ab5670"
  • personal_details object

    Personal details for the customer.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address object

      Profile's personal address information.

       Show attributes
       Close
      Attributes
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

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

        Example: "DE"
      • line_1 string

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

        Example: "Sample street"
      • line_2 string

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

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"
PUT /v0.1/customers/{customer_id} 
curl https://api.sumup.com/v0.1/customers/{customer_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.update("customer_id", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.UpdateAsync(
    "customer_id",
    new UpdateCustomerBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().updateCustomer(
  "customer_id",
  UpdateCustomerBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.customers.update("customer_id", UpdateCustomerBody(


))
client := sumup.NewClient()


result, err := client.Customers.Update(context.Background(), "customer_id", customers.UpdateCustomerBody{


})
use sumup::Client;


let client = Client::default();


let result = client.customers().update("customer_id", sumup::UpdateCustomerBody{}).await;
Update a customer response
{
  "customer_id": "831ff8d4cd5958ab5670",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}
Customers

List payment instruments

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

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

Response 200

[]object
 Show attributes
 Close
Attributes
  • token string read only

    Unique token identifying the saved payment card for a customer.

  • active boolean default: trueread only

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

  • type string
    Options:  card

    Type of the payment instrument.

  • card object

    Details of the payment card.

     Show attributes
     Close
    Attributes
    • last_4_digits string min length: 4max length: 4read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type string

      Issuing card network of the payment card used for the transaction.

  • mandate object

    Created mandate

     Show attributes
     Close
    Attributes
    • type string

      Indicates the mandate type

    • status string

      Mandate status

    • merchant_code string

      Merchant code which has the mandate

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • created_at string date-time

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

GET /v0.1/customers/{customer_id}/payment-instruments 
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.listPaymentInstruments("customer_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.ListPaymentInstrumentsAsync(
    "customer_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().listPaymentInstruments(
  "customer_id"
);
from sumup import Sumup


client = Sumup()


result = client.customers.list_payment_instruments("customer_id")
client := sumup.NewClient()


result, err := client.Customers.ListPaymentInstruments(context.Background(), "customer_id")
use sumup::Client;


let client = Client::default();


let result = client.customers().list_payment_instruments("customer_id").await;
List payment instruments response
[
  {
    "token": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3",
    "active": true,
    "type": "card",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MH4H92C7"
    },
    "card": {
      "last_4_digits": "0001",
      "type": "VISA"
    },
    "created_at": "2021-03-30T10:06:07.000+00:00"
  }
]
Customers

Deactivate a payment instrument

Deactivates an identified card payment instrument resource for a customer.

Required scopes: payment_instruments

Path Parameters

  • customer_id string required

    Unique ID of the saved customer resource.

  • token string required

    Unique token identifying the card saved as a payment instrument resource.

DELETE /v0.1/customers/{customer_id}/payment-instruments/{token} 
curl https://api.sumup.com/v0.1/customers/{customer_id}/payment-instruments/{token} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.customers.deactivatePaymentInstrument("customer_id", "token");
using SumUp;


var client = new SumUpClient();


var result = await client.Customers.DeactivatePaymentInstrumentAsync(
    "customer_id",
    "token"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.customers().deactivatePaymentInstrument(
  "customer_id",
  "token"
);
from sumup import Sumup


client = Sumup()


result = client.customers.deactivate_payment_instrument("customer_id", "token")
client := sumup.NewClient()


result, err := client.Customers.DeactivatePaymentInstrument(context.Background(), "customer_id", "token")
use sumup::Client;


let client = Client::default();


let result = client.customers().deactivate_payment_instrument("customer_id", "token").await;

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.

Required scopes: payments

Path Parameters

  • txn_id string required

    Unique ID of the transaction.

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.

POST /v0.1/me/refund/{txn_id} 
curl https://api.sumup.com/v0.1/me/refund/{txn_id} \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.refund("txn_id", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.RefundAsync(
    "txn_id",
    new RefundTransactionBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.transactions().refundTransaction(
  "txn_id",
  RefundTransactionBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.transactions.refund("txn_id", RefundTransactionBody(


))
client := sumup.NewClient()


result, err := client.Transactions.Refund(context.Background(), "txn_id", transactions.RefundTransactionBody{


})
use sumup::Client;


let client = Client::default();


let result = client.transactions().refund("txn_id", sumup::RefundTransactionBody{}).await;
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
Required scopes: transactions.history

Path Parameters

  • merchant_code string required
    Example: "MH4H92C7"

Query Parameters

  • id string

    Retrieves the transaction resource with the specified transaction ID (the id parameter in the transaction resource).

  • internal_id string

    Retrieves the transaction resource with the specified internal transaction ID (the internal_id parameter in the transaction resource).

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

  • foreign_transaction_id string

    External/foreign transaction id (passed by clients).

  • client_transaction_id string

    Client transaction id.

Response 200

  • id string

    Unique ID of the transaction.

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

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

    Example: "TEENSK4W2K"
  • amount number

    Total amount of the transaction.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • timestamp string date-time

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

    Example: "2020-02-29T10:56:56.876Z"
  • status string
    Options:  SUCCESSFUL CANCELLED FAILED PENDING

    Current status of the transaction.

  • payment_type string

    Payment type used for the transaction.

  • installments_count integer minimum: 1

    Current number of the installment for deferred payments.

  • merchant_code string

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

    Example: "MH4H92C7"
  • vat_amount number

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

    Example: 6
  • tip_amount number

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

    Example: 3
  • entry_mode string

    Entry mode of the payment details.

  • auth_code string

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

    Example: "053201"
  • internal_id integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • product_summary string

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

  • payouts_total integer

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

  • payouts_received integer

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

  • payout_plan string
    Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

  • username string email

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

  • lat number minimum: 0maximum: 90

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

  • lon number minimum: 0maximum: 180

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

  • horizontal_accuracy number

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

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

    Simple name of the payment type.

  • verification_method string
    Options:  none na signature offline PIN online PIN offline PIN + signature confirmation code verified

    Verification method used for the transaction.

  • card object

    Details of the payment card.

     Show attributes
     Close
    Attributes
    • last_4_digits string min length: 4max length: 4read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type string

      Issuing card network of the payment card used for the transaction.

  • local_time string date-time

    Local date and time of the creation of the transaction.

  • payout_type string
    Options:  BANK_ACCOUNT BALANCE PREPAID_CARD

    Payout type for the transaction.

  • products []object

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

     Show attributes
     Close
    Attributes
    • name string

      Name of the product from the merchant's catalog.

    • price number

      Price of the product without VAT.

    • vat_rate number

      VAT rate applicable to the product.

    • single_vat_amount number

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

    • price_with_vat number

      Price of a single product item with VAT.

    • vat_amount number

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

    • quantity number

      Number of product items for the purchase.

    • total_price number

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

    • total_with_vat number

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

  • vat_rates []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
  • transaction_events []object

    List of transaction events related to the transaction.

     Show attributes
     Close
    Attributes
    • id integer

      Unique ID of the transaction event.

    • event_type string

      Type of the transaction event.

    • status string

      Status of the transaction event.

    • amount number

      Amount of the event.

    • due_date string date

      Date when the transaction event is due to occur.

    • date string date

      Date when the transaction event occurred.

    • installment_number integer

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

    • timestamp string date-time

      Date and time of the transaction event.

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

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

  • links []object unique items

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Attributes
  • events []object unique items

    List of events related to the transaction.

     Show attributes
     Close
    Attributes
    • id integer

      Unique ID of the transaction event.

    • transaction_id string

      Unique ID of the transaction.

    • type string

      Type of the transaction event.

    • status string

      Status of the transaction event.

    • amount number

      Amount of the event.

    • timestamp string date-time

      Date and time of the transaction event.

    • fee_amount number

      Amount of the fee related to the event.

    • installment_number integer

      Consecutive number of the installment.

    • deducted_amount number

      Amount deducted for the event.

    • deducted_fee_amount number

      Amount of the fee deducted for the event.

  • location object

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

     Show attributes
     Close
    Attributes
    • lat number minimum: 0maximum: 90

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

    • lon number minimum: 0maximum: 180

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

    • horizontal_accuracy number

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

  • tax_enabled boolean

    Indicates whether tax deduction is enabled for the transaction.

GET /v2.1/merchants/{merchant_code}/transactions 
curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.get("MH4H92C7");
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.GetAsync(
    "MH4H92C7"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.transactions().getTransactionV2_1(
  "MH4H92C7"
);
from sumup import Sumup


client = Sumup()


result = client.transactions.get("MH4H92C7")
client := sumup.NewClient()


result, err := client.Transactions.Get(context.Background(), "MH4H92C7")
use sumup::Client;


let client = Client::default();


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

List transactions

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

Required scopes: transactions.history

Path Parameters

  • merchant_code string required
    Example: "MH4H92C7"

Query Parameters

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

  • order string default: ascending
    Options:  ascending descending

    Specifies the order in which the returned results are displayed.

  • limit integer

    Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.

  • users []string

    Filters the returned results by user email.

  • statuses []string
    Options:  SUCCESSFUL CANCELLED FAILED REFUNDED CHARGE_BACK

    Filters the returned results by the specified list of final statuses of the transactions.

  • payment_types []string
    Options:  CASH POS ECOM RECURRING BITCOIN BALANCE MOTO BOLETO DIRECT_DEBIT APM UNKNOWN

    Filters the returned results by the specified list of payment types used for the transactions.

  • entry_modes[] []string
    Options:  BOLETO SOFORT IDEAL BANCONTACT EPS MYBANK SATISPAY BLIK P24 GIROPAY PIX QR_CODE_PIX APPLE_PAY GOOGLE_PAY PAYPAL NONE CHIP MANUAL_ENTRY CUSTOMER_ENTRY MAGSTRIPE_FALLBACK MAGSTRIPE DIRECT_DEBIT CONTACTLESS MOTO CONTACTLESS_MAGSTRIPE N/A

    Filters the returned results by the specified list of entry modes.

  • types []string
    Options:  PAYMENT REFUND CHARGE_BACK

    Filters the returned results by the specified list of transaction types.

  • changes_since string date-time

    Filters the results by the latest modification time of resources and returns only transactions that are modified at or after the specified timestamp (in ISO8601 format).

  • newest_time string date-time

    Filters the results by the creation time of resources and returns only transactions that are created before the specified timestamp (in ISO8601 format).

  • newest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are smaller than the specified value. This parameters supersedes the newest_time parameter (if both are provided in the request).

  • oldest_time string date-time

    Filters the results by the creation time of resources and returns only transactions that are created at or after the specified timestamp (in ISO8601 format).

  • oldest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are greater than the specified value. This parameters supersedes the oldest_time parameter (if both are provided in the request).

Response 200

  • items []object
     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • product_summary string

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

    • payouts_total integer

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

    • payouts_received integer

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

    • payout_plan string
      Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

    • transaction_id string

      Unique ID of the transaction.

    • client_transaction_id string

      Client-specific ID of the transaction.

    • user string email

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

    • type string
      Options:  PAYMENT REFUND CHARGE_BACK

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

    • card_type string

      Issuing card network of the payment card used for the transaction.

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

      Specifies the relation to the current resource.

    • href string uri

      URL for accessing the related resource.

    • type string

      Specifies the media type of the related resource.

GET /v2.1/merchants/{merchant_code}/transactions/history 
curl https://api.sumup.com/v2.1/merchants/{merchant_code}/transactions/history \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.list("MH4H92C7");
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.ListAsync(
    "MH4H92C7"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.transactions().listTransactionsV2_1(
  "MH4H92C7"
);
from sumup import Sumup


client = Sumup()


result = client.transactions.list("MH4H92C7")
client := sumup.NewClient()


result, err := client.Transactions.List(context.Background(), "MH4H92C7")
use sumup::Client;


let client = Client::default();


let result = client.transactions().list("MH4H92C7", sumup::ListTransactionsV2_1Params{
    transaction_code: Some("transaction_code".to_string()),
    order: Some("order".to_string()),
    limit: Some("limit".to_string()),
    users: Some("users".to_string()),
    statuses: Some("statuses".to_string()),
    payment_types: Some("payment_types".to_string()),
    entry_modes: Some("entry_modes[]".to_string()),
    types: Some("types".to_string()),
    changes_since: Some("changes_since".to_string()),
    newest_time: Some("newest_time".to_string()),
    newest_ref: Some("newest_ref".to_string()),
    oldest_time: Some("oldest_time".to_string()),
    oldest_ref: Some("oldest_ref".to_string()),
}).await;
List transactions response
{
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null
    }
  ],
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ]
}
Transactions

Retrieve a transactionDeprecated

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
Required scopes: transactions.history

Query Parameters

  • id string

    Retrieves the transaction resource with the specified transaction ID (the id parameter in the transaction resource).

  • internal_id string

    Retrieves the transaction resource with the specified internal transaction ID (the internal_id parameter in the transaction resource).

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

Response 200

  • id string

    Unique ID of the transaction.

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

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

    Example: "TEENSK4W2K"
  • amount number

    Total amount of the transaction.

    Example: 10.1
  • currency string

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

    Example: "EUR"
  • timestamp string date-time

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

    Example: "2020-02-29T10:56:56.876Z"
  • status string
    Options:  SUCCESSFUL CANCELLED FAILED PENDING

    Current status of the transaction.

  • payment_type string

    Payment type used for the transaction.

  • installments_count integer minimum: 1

    Current number of the installment for deferred payments.

  • merchant_code string

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

    Example: "MH4H92C7"
  • vat_amount number

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

    Example: 6
  • tip_amount number

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

    Example: 3
  • entry_mode string

    Entry mode of the payment details.

  • auth_code string

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

    Example: "053201"
  • internal_id integer

    Internal unique ID of the transaction on the SumUp platform.

    Example: 1763892018
  • product_summary string

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

  • payouts_total integer

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

  • payouts_received integer

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

  • payout_plan string
    Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

  • username string email

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

  • lat number minimum: 0maximum: 90

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

  • lon number minimum: 0maximum: 180

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

  • horizontal_accuracy number

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

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

    Simple name of the payment type.

  • verification_method string
    Options:  none na signature offline PIN online PIN offline PIN + signature confirmation code verified

    Verification method used for the transaction.

  • card object

    Details of the payment card.

     Show attributes
     Close
    Attributes
    • last_4_digits string min length: 4max length: 4read only

      Last 4 digits of the payment card number.

      Example: "3456"
    • type string

      Issuing card network of the payment card used for the transaction.

  • local_time string date-time

    Local date and time of the creation of the transaction.

  • payout_type string
    Options:  BANK_ACCOUNT BALANCE PREPAID_CARD

    Payout type for the transaction.

  • products []object

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

     Show attributes
     Close
    Attributes
    • name string

      Name of the product from the merchant's catalog.

    • price number

      Price of the product without VAT.

    • vat_rate number

      VAT rate applicable to the product.

    • single_vat_amount number

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

    • price_with_vat number

      Price of a single product item with VAT.

    • vat_amount number

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

    • quantity number

      Number of product items for the purchase.

    • total_price number

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

    • total_with_vat number

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

  • vat_rates []object

    List of VAT rates applicable to the transaction.

     Show attributes
     Close
    Attributes
  • transaction_events []object

    List of transaction events related to the transaction.

     Show attributes
     Close
    Attributes
    • id integer

      Unique ID of the transaction event.

    • event_type string

      Type of the transaction event.

    • status string

      Status of the transaction event.

    • amount number

      Amount of the event.

    • due_date string date

      Date when the transaction event is due to occur.

    • date string date

      Date when the transaction event occurred.

    • installment_number integer

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

    • timestamp string date-time

      Date and time of the transaction event.

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

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

  • links []object unique items

    List of hyperlinks for accessing related resources.

     Show attributes
     Close
    Attributes
  • events []object unique items

    List of events related to the transaction.

     Show attributes
     Close
    Attributes
    • id integer

      Unique ID of the transaction event.

    • transaction_id string

      Unique ID of the transaction.

    • type string

      Type of the transaction event.

    • status string

      Status of the transaction event.

    • amount number

      Amount of the event.

    • timestamp string date-time

      Date and time of the transaction event.

    • fee_amount number

      Amount of the fee related to the event.

    • installment_number integer

      Consecutive number of the installment.

    • deducted_amount number

      Amount deducted for the event.

    • deducted_fee_amount number

      Amount of the fee deducted for the event.

  • location object

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

     Show attributes
     Close
    Attributes
    • lat number minimum: 0maximum: 90

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

    • lon number minimum: 0maximum: 180

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

    • horizontal_accuracy number

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

  • tax_enabled boolean

    Indicates whether tax deduction is enabled for the transaction.

GET /v0.1/me/transactions 
curl https://api.sumup.com/v0.1/me/transactions \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.getDeprecated();
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.GetDeprecatedAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.transactions().getTransaction();
from sumup import Sumup


client = Sumup()


result = client.transactions.get_deprecated()
client := sumup.NewClient()


result, err := client.Transactions.GetDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


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

List transactionsDeprecated

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

Required scopes: transactions.history

Query Parameters

  • transaction_code string

    Retrieves the transaction resource with the specified transaction code.

  • order string default: ascending
    Options:  ascending descending

    Specifies the order in which the returned results are displayed.

  • limit integer

    Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.

  • users []string

    Filters the returned results by user email.

  • statuses []string
    Options:  SUCCESSFUL CANCELLED FAILED REFUNDED CHARGE_BACK

    Filters the returned results by the specified list of final statuses of the transactions.

  • payment_types []string
    Options:  CASH POS ECOM RECURRING BITCOIN BALANCE MOTO BOLETO DIRECT_DEBIT APM UNKNOWN

    Filters the returned results by the specified list of payment types used for the transactions.

  • types []string
    Options:  PAYMENT REFUND CHARGE_BACK

    Filters the returned results by the specified list of transaction types.

  • changes_since string date-time

    Filters the results by the latest modification time of resources and returns only transactions that are modified at or after the specified timestamp (in ISO8601 format).

  • newest_time string date-time

    Filters the results by the creation time of resources and returns only transactions that are created before the specified timestamp (in ISO8601 format).

  • newest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are smaller than the specified value. This parameters supersedes the newest_time parameter (if both are provided in the request).

  • oldest_time string date-time

    Filters the results by the creation time of resources and returns only transactions that are created at or after the specified timestamp (in ISO8601 format).

  • oldest_ref string

    Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are greater than the specified value. This parameters supersedes the oldest_time parameter (if both are provided in the request).

Response 200

  • items []object
     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

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

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

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency string

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

      Example: "EUR"
    • timestamp string date-time

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

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFUL CANCELLED FAILED PENDING

      Current status of the transaction.

    • payment_type string

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • product_summary string

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

    • payouts_total integer

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

    • payouts_received integer

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

    • payout_plan string
      Options:  SINGLE_PAYMENT TRUE_INSTALLMENT ACCELERATED_INSTALLMENT

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

    • transaction_id string

      Unique ID of the transaction.

    • client_transaction_id string

      Client-specific ID of the transaction.

    • user string email

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

    • type string
      Options:  PAYMENT REFUND CHARGE_BACK

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

    • card_type string

      Issuing card network of the payment card used for the transaction.

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

      Specifies the relation to the current resource.

    • href string uri

      URL for accessing the related 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 \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.transactions.listDeprecated();
using SumUp;


var client = new SumUpClient();


var result = await client.Transactions.ListDeprecatedAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.transactions().listTransactions();
from sumup import Sumup


client = Sumup()


result = client.transactions.list_deprecated()
client := sumup.NewClient()


result, err := client.Transactions.ListDeprecated(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.transactions().list_deprecated(sumup::ListTransactionsParams{
    transaction_code: Some("transaction_code".to_string()),
    order: Some("order".to_string()),
    limit: Some("limit".to_string()),
    users: Some("users".to_string()),
    statuses: Some("statuses".to_string()),
    payment_types: Some("payment_types".to_string()),
    types: Some("types".to_string()),
    changes_since: Some("changes_since".to_string()),
    newest_time: Some("newest_time".to_string()),
    newest_ref: Some("newest_ref".to_string()),
    oldest_time: Some("oldest_time".to_string()),
    oldest_ref: Some("oldest_ref".to_string()),
}).await;
List transactions response
{
  "items": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "product_summary": null,
      "payouts_total": null,
      "payouts_received": null,
      "payout_plan": null,
      "transaction_id": null,
      "client_transaction_id": null,
      "user": null,
      "type": null,
      "card_type": null
    }
  ],
  "links": [
    {
      "rel": null,
      "href": null,
      "type": null
    }
  ]
}

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

Financial Payouts

[]object
 Show attributes
 Close
Attributes
  • amount number
  • currency string
  • date string date
  • 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.

Required scopes: user.profile user.profile_readonly

Path Parameters

  • merchant_code string required
    Example: "MH4H92C7"

Query Parameters

  • start_date string date required

    Start date (in ISO8601 format).

  • end_date string date required

    End date (in ISO8601 format).

  • format string
    Options:  json csv
  • limit integer
  • order string
    Options:  desc asc

Financial Payouts

[]object
 Show attributes
 Close
Attributes
  • amount number
  • currency string
  • date string date
  • 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 /v1.0/merchants/{merchant_code}/payouts 
curl https://api.sumup.com/v1.0/merchants/{merchant_code}/payouts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.payouts.list("MH4H92C7", "start_date", "end_date");
using SumUp;


var client = new SumUpClient();


var result = await client.Payouts.ListAsync(
    "MH4H92C7",
    "start_date",
    "end_date"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.payouts().listPayoutsV1(
  "MH4H92C7",
  java.time.LocalDate.parse("start_date"),
  java.time.LocalDate.parse("end_date")
);
from sumup import Sumup


client = Sumup()


result = client.payouts.list("MH4H92C7", "start_date", "end_date")
client := sumup.NewClient()


result, err := client.Payouts.List(context.Background(), "MH4H92C7", "start_date", "end_date")
use sumup::Client;


let client = Client::default();


let result = client.payouts().list("MH4H92C7", sumup::ListPayoutsV1Params{
    start_date: Some("start_date".to_string()),
    end_date: Some("end_date".to_string()),
    format: Some("format".to_string()),
    limit: Some("limit".to_string()),
    order: Some("order".to_string()),
}).await;
List payouts response
[
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]
Payouts

List payoutsDeprecated

Lists ordered payouts for the merchant profile.

Required scopes: user.profile user.profile_readonly

Query Parameters

  • start_date string date required

    Start date (in ISO8601 format).

  • end_date string date required

    End date (in ISO8601 format).

  • format string
    Options:  json csv
  • limit integer
  • order string
    Options:  desc asc

Financial Payouts

[]object
 Show attributes
 Close
Attributes
  • amount number
  • currency string
  • date string date
  • 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 \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.payouts.listDeprecated("start_date", "end_date");
using SumUp;


var client = new SumUpClient();


var result = await client.Payouts.ListDeprecatedAsync(
    "start_date",
    "end_date"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.payouts().listPayouts(
  java.time.LocalDate.parse("start_date"),
  java.time.LocalDate.parse("end_date")
);
from sumup import Sumup


client = Sumup()


result = client.payouts.list_deprecated("start_date", "end_date")
client := sumup.NewClient()


result, err := client.Payouts.ListDeprecated(context.Background(), "start_date", "end_date")
use sumup::Client;


let client = Client::default();


let result = client.payouts().list_deprecated(sumup::ListPayoutsParams{
    start_date: Some("start_date".to_string()),
    end_date: Some("end_date".to_string()),
    format: Some("format".to_string()),
    limit: Some("limit".to_string()),
    order: Some("order".to_string()),
}).await;
List payouts response
[
  {
    "amount": null,
    "currency": null,
    "date": null,
    "fee": null,
    "id": null,
    "reference": null,
    "status": null,
    "transaction_code": null,
    "type": null
  }
]

Receipts

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

The Receipt object

Receipt

  • transaction_data object

    Transaction information.

     Show attributes
     Close
    Attributes
    • transaction_code string

      Transaction code.

    • amount string

      Transaction amount.

    • vat_amount string

      Transaction VAT amount.

    • tip_amount string

      Tip amount (included in transaction amount).

    • currency string

      Transaction currency.

    • timestamp string date-time

      Time created at.

    • status string

      Transaction processing status.

    • payment_type string

      Transaction type.

    • entry_mode string

      Transaction entry mode.

    • verification_method string

      Cardholder verification method.

    • card object
       Show attributes
       Close
      Attributes
      • last_4_digits string

        Card last 4 digits.

      • type string

        Card Scheme.

    • installments_count integer

      Number of installments.

    • products []object

      Products

       Show attributes
       Close
      Attributes
      • name string

        Product name.

      • description string

        Product description.

      • price number

        Product price.

      • quantity integer

        Product quantity.

      • total_price number

        Quantity x product price.

    • vat_rates []object

      Vat rates.

       Show attributes
       Close
      Attributes
      • gross number

        Gross

      • net number

        Net

      • rate number

        Rate

      • vat number

        Vat

    • events []object

      Events

       Show attributes
       Close
      Attributes
      • id integer

        Unique ID of the transaction event.

      • transaction_id string

        Unique ID of the transaction.

      • type string

        Type of the transaction event.

      • status string

        Status of the transaction event.

      • amount number

        Amount of the event.

      • timestamp string date-time

        Date and time of the transaction event.

      • receipt_no string
    • receipt_no string

      Receipt number

  • merchant_data object

    Receipt merchant data

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

Retrieve receipt details

Retrieves receipt specific data for a transaction.

Path Parameters

  • id string required

    SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD.

Query Parameters

  • mid string required

    Merchant code.

  • tx_event_id integer

    The ID of the transaction event (refund).

Receipt

  • transaction_data object

    Transaction information.

     Show attributes
     Close
    Attributes
    • transaction_code string

      Transaction code.

    • amount string

      Transaction amount.

    • vat_amount string

      Transaction VAT amount.

    • tip_amount string

      Tip amount (included in transaction amount).

    • currency string

      Transaction currency.

    • timestamp string date-time

      Time created at.

    • status string

      Transaction processing status.

    • payment_type string

      Transaction type.

    • entry_mode string

      Transaction entry mode.

    • verification_method string

      Cardholder verification method.

    • card object
       Show attributes
       Close
      Attributes
      • last_4_digits string

        Card last 4 digits.

      • type string

        Card Scheme.

    • installments_count integer

      Number of installments.

    • products []object

      Products

       Show attributes
       Close
      Attributes
      • name string

        Product name.

      • description string

        Product description.

      • price number

        Product price.

      • quantity integer

        Product quantity.

      • total_price number

        Quantity x product price.

    • vat_rates []object

      Vat rates.

       Show attributes
       Close
      Attributes
      • gross number

        Gross

      • net number

        Net

      • rate number

        Rate

      • vat number

        Vat

    • events []object

      Events

       Show attributes
       Close
      Attributes
      • id integer

        Unique ID of the transaction event.

      • transaction_id string

        Unique ID of the transaction.

      • type string

        Type of the transaction event.

      • status string

        Status of the transaction event.

      • amount number

        Amount of the event.

      • timestamp string date-time

        Date and time of the transaction event.

      • receipt_no string
    • receipt_no string

      Receipt number

  • merchant_data object

    Receipt merchant data

     Show attributes
     Close
    Attributes
    • merchant_profile object
       Show attributes
       Close
      Attributes
      • merchant_code string
        Example: "MH4H92C7"
      • business_name string
      • email string
      • address object
         Show attributes
         Close
        Attributes
        • address_line1 string
        • city string
        • country string
        • country_en_name string
        • country_native_name string
        • post_code string
        • landline string
    • locale string
  • emv_data object
     Show attributes
     Close
    Attributes
  • acquirer_data object
     Show attributes
     Close
    Attributes
    • tid string
    • authorization_code string
    • return_code string
    • local_time string
GET /v1.1/receipts/{id} 
curl https://api.sumup.com/v1.1/receipts/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.receipts.get("id", "mid");
using SumUp;


var client = new SumUpClient();


var result = await client.Receipts.GetAsync(
    "id",
    "mid"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.receipts().getReceipt(
  "id",
  "mid"
);
from sumup import Sumup


client = Sumup()


result = client.receipts.get("id", "mid")
client := sumup.NewClient()


result, err := client.Receipts.Get(context.Background(), "id", "mid")
use sumup::Client;


let client = Client::default();


let result = client.receipts().get("id", sumup::GetReceiptParams{
    mid: Some("mid".to_string()),
    tx_event_id: Some("tx_event_id".to_string()),
}).await;
Retrieve receipt details response
{
  "transaction_data": {
    "transaction_code": null,
    "amount": null,
    "vat_amount": null,
    "tip_amount": null,
    "currency": null,
    "timestamp": null,
    "status": null,
    "payment_type": null,
    "entry_mode": null,
    "verification_method": null,
    "card": {
      "last_4_digits": null,
      "type": null
    },
    "installments_count": null,
    "products": [
      {
        "name": null,
        "description": null,
        "price": null,
        "quantity": null,
        "total_price": null
      }
    ],
    "vat_rates": [
      {
        "gross": null,
        "net": null,
        "rate": null,
        "vat": null
      }
    ],
    "events": [
      {
        "id": null,
        "transaction_id": null,
        "type": null,
        "status": null,
        "amount": null,
        "timestamp": null,
        "receipt_no": null
      }
    ],
    "receipt_no": null
  },
  "merchant_data": {
    "merchant_profile": {
      "merchant_code": "MH4H92C7",
      "business_name": null,
      "email": null,
      "address": {
        "address_line1": null,
        "city": null,
        "country": null,
        "country_en_name": null,
        "country_native_name": null,
        "post_code": null,
        "landline": null
      }
    },
    "locale": null
  },
  "emv_data": {},
  "acquirer_data": {
    "tid": null,
    "authorization_code": null,
    "return_code": null,
    "local_time": null
  }
}

MembersPreview feature

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

The Member object

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

Member

  • id string required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles []string required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions []string deprecated required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at string date-time required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

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

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id string required

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

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email string required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled boolean required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user boolean required

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

    • service_account_user boolean required

      True if the user is a service account.

    • disabled_at string date-time

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

    • nickname string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture string uri

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic object deprecated

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id integer required
  • invite object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email string email required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at string date-time required
      Example: "2023-01-20T15:16:17Z"
  • status string required

    The status of the membership.

  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
The Member object
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

List members

Lists merchant members.

Required permissions: merchant_read

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Query Parameters

  • offset integer minimum: 0default: 0

    Offset of the first member to return.

    Example: 0
  • limit integer minimum: 1maximum: 25default: 10

    Maximum number of members to return.

    Example: 10
  • scroll boolean default: false

    Indicates to skip count query.

    Example: true
  • email string

    Filter the returned members by email address prefix.

    Example: "user"
  • user.id string uuid

    Search for a member by user id.

    Example: "245b2ead-85bf-45ff-856f-311a88a5d454"
  • status string
    Options:  accepted pending expired disabled unknown

    Filter the returned members by the membership status.

  • roles []string

    Filter the returned members by role.

    Example: ["role_employee","role_accountant"]

Response 200

  • items []object required
     Show attributes
     Close
    Member
    • id string required

      ID of the member.

      Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • roles []string required

      User's roles.

       Show attributes
       Close
      Attributes
    • permissions []string deprecated required

      User's permissions.

       Show attributes
       Close
      Attributes
    • created_at string date-time required

      The timestamp of when the member was created.

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

      The timestamp of when the member was last updated.

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

      Information about the user associated with the membership.

       Show attributes
       Close
      Attributes
      • id string required

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

        Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
      • email string required

        End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

        Example: "example@sumup.com"
      • mfa_on_login_enabled boolean required

        True if the user has enabled MFA on login.

        Example: true
      • virtual_user boolean required

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

      • service_account_user boolean required

        True if the user is a service account.

      • disabled_at string date-time

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

      • nickname string

        User's preferred name. Used for display purposes only.

        Example: "Test User"
      • picture string uri

        URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

        Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
      • classic object deprecated

        Classic identifiers of the user.

         Show attributes
         Close
        Attributes
        • user_id integer required
    • invite object

      Pending invitation for membership.

       Show attributes
       Close
      Invite
      • email string email required

        Email address of the invited user.

        Example: "boaty.mcboatface@sumup.com"
      • expires_at string date-time required
        Example: "2023-01-20T15:16:17Z"
    • status string required

      The status of the membership.

    • metadata object max properties: 64

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

       Show attributes
       Close
      Attributes
      Example: {}
    • attributes object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
  • total_count integer
    Example: 3
GET /v0.1/merchants/{merchant_code}/members 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.members.list("MK10CL2A");
using SumUp;


var client = new SumUpClient();


var result = await client.Members.ListAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.members().listMerchantMembers(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.members.list("MK10CL2A")
client := sumup.NewClient()


result, err := client.Members.List(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.members().list("MK10CL2A", sumup::ListMerchantMembersParams{
    offset: Some(0),
    limit: Some(10),
    scroll: Some(true),
    email: Some("user".to_string()),
    user_id: Some("245b2ead-85bf-45ff-856f-311a88a5d454".to_string()),
    status: Some("status".to_string()),
    roles: Some(["role_employee","role_accountant"]),
}).await;
List members response
{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "roles": [
        "role_admin",
        "role_owner"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-02-20T15:16:17Z",
      "user": {
        "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
        "email": "example@sumup.com",
        "mfa_on_login_enabled": true,
        "virtual_user": false,
        "service_account_user": false
      },
      "status": "accepted"
    }
  ],
  "total_count": 3
}
Members

Create a member

Create a merchant member.

Required permissions: members_create

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Body Parameters

  • is_managed_user boolean

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

  • email string email required

    Email address of the member to add.

  • password string min length: 8password

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

  • nickname string

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

    Example: "Test User"
  • roles []string required

    List of roles to assign to the new member.

     Show attributes
     Close
    Attributes
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}

Member

  • id string required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles []string required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions []string deprecated required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at string date-time required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

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

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id string required

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

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email string required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled boolean required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user boolean required

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

    • service_account_user boolean required

      True if the user is a service account.

    • disabled_at string date-time

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

    • nickname string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture string uri

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic object deprecated

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id integer required
  • invite object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email string email required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at string date-time required
      Example: "2023-01-20T15:16:17Z"
  • status string required

    The status of the membership.

  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
POST /v0.1/merchants/{merchant_code}/members 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "email": "karl.berg@example.com",
    "roles": [
      "role_employee"
    ]
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.members.create("MK10CL2A", {
  email: "karl.berg@example.com",
  roles: ["role_employee"],
});
using SumUp;


var client = new SumUpClient();


var result = await client.Members.CreateAsync(
    "MK10CL2A",
    new CreateMerchantMemberBody
    {
        Email = "karl.berg@example.com",
        Roles = new[] { "role_employee" },
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.members().createMerchantMember(
  "MK10CL2A",
  CreateMerchantMemberBody.builder()
    .email("karl.berg@example.com")
    .roles(java.util.List.of(
        "role_employee"
      ))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.members.create("MK10CL2A", CreateMerchantMemberBody(
  email="karl.berg@example.com",
  roles=["role_employee"],
))
client := sumup.NewClient()


result, err := client.Members.Create(context.Background(), "MK10CL2A", members.CreateMerchantMemberBody{
  Email: "karl.berg@example.com",
  Roles: ["role_employee"],
})
use sumup::Client;


let client = Client::default();


let result = client.members().create("MK10CL2A", sumup::CreateMerchantMemberBody{
  email: "karl.berg@example.com".to_string(),
  roles: vec!["role_employee"],
}).await;
Create a member response
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

Retrieve a member

Retrieve a merchant member.

Required permissions: members_view

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • member_id string required

    The ID of the member to retrieve.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Member

  • id string required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles []string required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions []string deprecated required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at string date-time required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

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

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id string required

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

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email string required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled boolean required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user boolean required

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

    • service_account_user boolean required

      True if the user is a service account.

    • disabled_at string date-time

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

    • nickname string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture string uri

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic object deprecated

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id integer required
  • invite object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email string email required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at string date-time required
      Example: "2023-01-20T15:16:17Z"
  • status string required

    The status of the membership.

  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
GET /v0.1/merchants/{merchant_code}/members/{member_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.members.get("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
using SumUp;


var client = new SumUpClient();


var result = await client.Members.GetAsync(
    "MK10CL2A",
    "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.members().getMerchantMember(
  "MK10CL2A",
  "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
from sumup import Sumup


client = Sumup()


result = client.members.get("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Members.Get(context.Background(), "MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.members().get("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;
Retrieve a member response
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

Update a member

Update the merchant member.

Required permissions: members_update

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • member_id string required

    The ID of the member to retrieve.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Body Parameters

  • roles []string
     Show attributes
     Close
    Attributes
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • user object

    Allows you to update user data of managed users.

     Show attributes
     Close
    Attributes
    • nickname string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • password string min length: 8password

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

Member

  • id string required

    ID of the member.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • roles []string required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions []string deprecated required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at string date-time required

    The timestamp of when the member was created.

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

    The timestamp of when the member was last updated.

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

    Information about the user associated with the membership.

     Show attributes
     Close
    Attributes
    • id string required

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

      Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
    • email string required

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.

      Example: "example@sumup.com"
    • mfa_on_login_enabled boolean required

      True if the user has enabled MFA on login.

      Example: true
    • virtual_user boolean required

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

    • service_account_user boolean required

      True if the user is a service account.

    • disabled_at string date-time

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

    • nickname string

      User's preferred name. Used for display purposes only.

      Example: "Test User"
    • picture string uri

      URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

      Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
    • classic object deprecated

      Classic identifiers of the user.

       Show attributes
       Close
      Attributes
      • user_id integer required
  • invite object

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email string email required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at string date-time required
      Example: "2023-01-20T15:16:17Z"
  • status string required

    The status of the membership.

  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
PUT /v0.1/merchants/{merchant_code}/members/{member_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/members/{member_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "Update member\'s role": {
      "roles": [
        "role_manager"
      ]
    },
    "Update managed user": {
      "user": {
        "nickname": "New Employee Name"
      }
    }
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.members.update("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", {
  Update member's role: {"roles":["role_manager"]},
  Update managed user: {"user":{"nickname":"New Employee Name"}},
});
using SumUp;


var client = new SumUpClient();


var result = await client.Members.UpdateAsync(
    "MK10CL2A",
    "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
    new UpdateMerchantMemberBody
    {
        UpdateMemberSRole = null,
        UpdateManagedUser = null,
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.members().updateMerchantMember(
  "MK10CL2A",
  "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  UpdateMerchantMemberBody.builder()
    .updateMemberSRole(null)
    .updateManagedUser(null)
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.members.update("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", UpdateMerchantMemberBody(
  Update member's role={"roles":["role_manager"]},
  Update managed user={"user":{"nickname":"New Employee Name"}},
))
client := sumup.NewClient()


result, err := client.Members.Update(context.Background(), "MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", members.UpdateMerchantMemberBody{
  UpdateMemberSRole: {"roles":["role_manager"]},
  UpdateManagedUser: {"user":{"nickname":"New Employee Name"}},
})
use sumup::Client;


let client = Client::default();


let result = client.members().update("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", sumup::UpdateMerchantMemberBody{
  update_member_s_role: {"roles":["role_manager"]},
  update_managed_user: {"user":{"nickname":"New Employee Name"}},
}).await;
Update a member response
{
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "roles": [
    "role_admin",
    "role_owner"
  ],
  "permissions": [
    "members_read",
    "members_write",
    "create_moto_payments",
    "full_transaction_history_view",
    "refund_transactions",
    "create_referral",
    "developer_settings_edit",
    "developer_settings_access"
  ],
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-02-20T15:16:17Z",
  "user": {
    "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
    "email": "example@sumup.com",
    "mfa_on_login_enabled": true,
    "virtual_user": false,
    "service_account_user": false
  },
  "status": "accepted"
}
Members

Delete a member

Deletes a merchant member.

Required permissions: members_delete

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • member_id string required

    The ID of the member to retrieve.

    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} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.members.delete("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
using SumUp;


var client = new SumUpClient();


var result = await client.Members.DeleteAsync(
    "MK10CL2A",
    "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.members().deleteMerchantMember(
  "MK10CL2A",
  "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
from sumup import Sumup


client = Sumup()


result = client.members.delete("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Members.Delete(context.Background(), "MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.members().delete("MK10CL2A", "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;

MembershipsPreview feature

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

The Membership object

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

Membership

  • id string required

    ID of the membership.

    Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • resource_id string required

    ID of the resource the membership is in.

    Example: "M2DDT39A"
  • type string required

    The type of the membership resource. Possible values are:

    • merchant - merchant account(s)
    • organization - organization(s)
    Example: "merchant"
  • roles []string required

    User's roles.

     Show attributes
     Close
    Attributes
  • permissions []string deprecated required

    User's permissions.

     Show attributes
     Close
    Attributes
  • created_at string date-time required

    The timestamp of when the membership was created.

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

    The timestamp of when the membership was last updated.

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

    Pending invitation for membership.

     Show attributes
     Close
    Invite
    • email string email required

      Email address of the invited user.

      Example: "boaty.mcboatface@sumup.com"
    • expires_at string date-time required
      Example: "2023-01-20T15:16:17Z"
  • status string required

    The status of the membership.

  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • attributes object

    Object attributes that are modifiable only by SumUp applications.

     Show attributes
     Close
    Attributes
    Example: {}
  • resource object required

    Information about the resource the membership is in.

     Show attributes
     Close
    Resource
    • id string required

      ID of the resource the membership is in.

      Example: "M2DDT39A"
    • type string required

      The type of the membership resource. Possible values are:

      • merchant - merchant account(s)
      • organization - organization(s)
      Example: "merchant"
    • name string required

      Display name of the resource.

      Example: "Acme Corp"
    • logo string max length: 256uri

      Logo fo the resource.

      Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
    • created_at string date-time required

      The timestamp of when the membership resource was created.

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

      The timestamp of when the membership resource was last updated.

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

      Object attributes that are modifiable only by SumUp applications.

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

List memberships

List memberships of the current user.

Query Parameters

  • offset integer minimum: 0default: 0

    Offset of the first member to return.

    Example: 0
  • limit integer minimum: 1maximum: 25default: 10

    Maximum number of members to return.

    Example: 10
  • kind string

    Filter memberships by resource kind.

    Example: "merchant"
  • status string
    Options:  accepted pending expired disabled unknown

    Filter the returned memberships by the membership status.

  • resource.type string

    Filter memberships by resource kind.

    Example: "merchant"
  • resource.attributes.sandbox boolean

    Filter memberships by the sandbox status of the resource the membership is in.

  • resource.name string

    Filter memberships by the name of the resource the membership is in.

  • resource.parent.id string nullable

    Filter memberships by the parent of the resource the membership is in. When filtering by parent both resource.parent.id and resource.parent.type must be present. Pass explicit null to filter for resources without a parent.

  • resource.parent.type object nullable

    Filter memberships by the parent of the resource the membership is in. When filtering by parent both resource.parent.id and resource.parent.type must be present. Pass explicit null to filter for resources without a parent.

  • roles []string

    Filter the returned memberships by role.

    Example: ["role_employee","role_accountant"]

Response 200

  • items []object required
     Show attributes
     Close
    Membership
    • id string required

      ID of the membership.

      Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • resource_id string required

      ID of the resource the membership is in.

      Example: "M2DDT39A"
    • type string required

      The type of the membership resource. Possible values are:

      • merchant - merchant account(s)
      • organization - organization(s)
      Example: "merchant"
    • roles []string required

      User's roles.

       Show attributes
       Close
      Attributes
    • permissions []string deprecated required

      User's permissions.

       Show attributes
       Close
      Attributes
    • created_at string date-time required

      The timestamp of when the membership was created.

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

      The timestamp of when the membership was last updated.

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

      Pending invitation for membership.

       Show attributes
       Close
      Invite
      • email string email required

        Email address of the invited user.

        Example: "boaty.mcboatface@sumup.com"
      • expires_at string date-time required
        Example: "2023-01-20T15:16:17Z"
    • status string required

      The status of the membership.

    • metadata object max properties: 64

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

       Show attributes
       Close
      Attributes
      Example: {}
    • attributes object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
    • resource object required

      Information about the resource the membership is in.

       Show attributes
       Close
      Resource
      • id string required

        ID of the resource the membership is in.

        Example: "M2DDT39A"
      • type string required

        The type of the membership resource. Possible values are:

        • merchant - merchant account(s)
        • organization - organization(s)
        Example: "merchant"
      • name string required

        Display name of the resource.

        Example: "Acme Corp"
      • logo string max length: 256uri

        Logo fo the resource.

        Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
      • created_at string date-time required

        The timestamp of when the membership resource was created.

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

        The timestamp of when the membership resource was last updated.

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

        Object attributes that are modifiable only by SumUp applications.

         Show attributes
         Close
        Attributes
        Example: {}
  • total_count integer required
    Example: 3
GET /v0.1/memberships 
curl https://api.sumup.com/v0.1/memberships \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.memberships.list();
using SumUp;


var client = new SumUpClient();


var result = await client.Memberships.ListAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.memberships().listMemberships();
from sumup import Sumup


client = Sumup()


result = client.memberships.list()
client := sumup.NewClient()


result, err := client.Memberships.List(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.memberships().list(sumup::ListMembershipsParams{
    offset: Some(0),
    limit: Some(10),
    kind: Some("merchant".to_string()),
    status: Some("status".to_string()),
    resource_type: Some("merchant".to_string()),
    resource_attributes_sandbox: Some("resource.attributes.sandbox".to_string()),
    resource_name: Some("resource.name".to_string()),
    resource_parent_id: Some("resource.parent.id".to_string()),
    resource_parent_type: Some("resource.parent.type".to_string()),
    roles: Some(["role_employee","role_accountant"]),
}).await;
List memberships response
{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "resource_id": "M2DDT39A",
      "type": "merchant",
      "roles": [
        "role_admin"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z",
      "invite": {
        "email": "boaty.mcboatface@sumup.com",
        "expires_at": "2023-01-20T15:16:17Z"
      },
      "status": "",
      "metadata": {},
      "attributes": {},
      "resource": {
        "id": "M2DDT39A",
        "type": "merchant",
        "name": "Acme Corp",
        "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
        "created_at": "2023-01-20T15:16:17Z",
        "updated_at": "2023-01-20T15:16:17Z",
        "attributes": {}
      }
    }
  ],
  "total_count": 3
}

RolesPreview feature

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

The Role object

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

Role

  • id string required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name string required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions []string max items: 100 required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined boolean required

    True if the role is provided by SumUp.

    Example: true
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

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

List roles

List merchant's custom roles.

Required permissions: roles_list

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Response 200

  • items []object required
     Show attributes
     Close
    Role
    • id string required

      Unique identifier of the role.

      Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • name string required

      User-defined name of the role.

      Example: "Senior Shop Manager II"
    • description string

      User-defined description of the role.

      Example: "Manges the shop and the employees."
    • permissions []string max items: 100 required

      List of permission granted by this role.

       Show attributes
       Close
      Attributes
    • is_predefined boolean required

      True if the role is provided by SumUp.

      Example: true
    • metadata object max properties: 64

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

       Show attributes
       Close
      Attributes
      Example: {}
    • created_at string date-time required

      The timestamp of when the role was created.

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

      The timestamp of when the role was last updated.

      Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/roles 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.roles.list("MK10CL2A");
using SumUp;


var client = new SumUpClient();


var result = await client.Roles.ListAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.roles().listMerchantRoles(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.roles.list("MK10CL2A")
client := sumup.NewClient()


result, err := client.Roles.List(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.roles().list("MK10CL2A").await;
List roles response
{
  "items": [
    {
      "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "name": "Senior Shop Manager II",
      "description": "Manges the shop and the employees.",
      "permissions": [],
      "is_predefined": true,
      "metadata": {},
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}
Roles

Create a role

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

Required permissions: roles_create

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Body Parameters

  • name string required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • permissions []string max items: 100 required

    User's permissions.

     Show attributes
     Close
    Attributes
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • description string

    User-defined description of the role.

    Example: "Manges the shop and the employees."

Role

  • id string required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name string required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions []string max items: 100 required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined boolean required

    True if the role is provided by SumUp.

    Example: true
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
POST /v0.1/merchants/{merchant_code}/roles 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "name": "Senior Shop Manager II",
    "permissions": [
      "catalog_access",
      "taxes_access",
      "members_access"
    ]
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.roles.create("MK10CL2A", {
  name: "Senior Shop Manager II",
  permissions: ["catalog_access","taxes_access","members_access"],
});
using SumUp;


var client = new SumUpClient();


var result = await client.Roles.CreateAsync(
    "MK10CL2A",
    new CreateMerchantRoleBody
    {
        Name = "Senior Shop Manager II",
        Permissions = new[] { "catalog_access", "taxes_access", "members_access" },
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.roles().createMerchantRole(
  "MK10CL2A",
  CreateMerchantRoleBody.builder()
    .name("Senior Shop Manager II")
    .permissions(java.util.List.of(
        "catalog_access",
        "taxes_access",
        "members_access"
      ))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.roles.create("MK10CL2A", CreateMerchantRoleBody(
  name="Senior Shop Manager II",
  permissions=["catalog_access","taxes_access","members_access"],
))
client := sumup.NewClient()


result, err := client.Roles.Create(context.Background(), "MK10CL2A", roles.CreateMerchantRoleBody{
  Name: "Senior Shop Manager II",
  Permissions: ["catalog_access","taxes_access","members_access"],
})
use sumup::Client;


let client = Client::default();


let result = client.roles().create("MK10CL2A", sumup::CreateMerchantRoleBody{
  name: "Senior Shop Manager II".to_string(),
  permissions: vec!["catalog_access", "taxes_access", "members_access"],
}).await;
Create a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

Retrieve a role

Retrieve a custom role by ID.

Required permissions: roles_view

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • role_id string required

    The ID of the role to retrieve.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Role

  • id string required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name string required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions []string max items: 100 required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined boolean required

    True if the role is provided by SumUp.

    Example: true
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.roles.get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
using SumUp;


var client = new SumUpClient();


var result = await client.Roles.GetAsync(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.roles().getMerchantRole(
  "MK10CL2A",
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
from sumup import Sumup


client = Sumup()


result = client.roles.get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Roles.Get(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.roles().get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;
Retrieve a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

Update a role

Update a custom role.

Required permissions: roles_update

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • role_id string required

    The ID of the role to retrieve.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Body Parameters

  • name string

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • permissions []string max items: 100

    User's permissions.

     Show attributes
     Close
    Attributes
  • description string

    User-defined description of the role.

    Example: "Manges the shop and the employees."

Role

  • id string required

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • name string required

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • description string

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions []string max items: 100 required

    List of permission granted by this role.

     Show attributes
     Close
    Attributes
  • is_predefined boolean required

    True if the role is provided by SumUp.

    Example: true
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
PATCH /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X PATCH \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "name": "Senior Shop Manager III",
    "permissions": [
      "catalog_edit",
      "taxes_access",
      "members_edit"
    ]
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.roles.update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", {
  name: "Senior Shop Manager III",
  permissions: ["catalog_edit","taxes_access","members_edit"],
});
using SumUp;


var client = new SumUpClient();


var result = await client.Roles.UpdateAsync(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
    new UpdateMerchantRoleBody
    {
        Name = "Senior Shop Manager III",
        Permissions = new[] { "catalog_edit", "taxes_access", "members_edit" },
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.roles().updateMerchantRole(
  "MK10CL2A",
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  UpdateMerchantRoleBody.builder()
    .name("Senior Shop Manager III")
    .permissions(java.util.List.of(
        "catalog_edit",
        "taxes_access",
        "members_edit"
      ))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.roles.update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", UpdateMerchantRoleBody(
  name="Senior Shop Manager III",
  permissions=["catalog_edit","taxes_access","members_edit"],
))
client := sumup.NewClient()


result, err := client.Roles.Update(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", roles.UpdateMerchantRoleBody{
  Name: "Senior Shop Manager III",
  Permissions: ["catalog_edit","taxes_access","members_edit"],
})
use sumup::Client;


let client = Client::default();


let result = client.roles().update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", sumup::UpdateMerchantRoleBody{
  name: "Senior Shop Manager III".to_string(),
  permissions: vec!["catalog_edit", "taxes_access", "members_edit"],
}).await;
Update a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

Delete a role

Delete a custom role.

Required permissions: roles_delete

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • role_id string required

    The ID of the role to retrieve.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
DELETE /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.roles.delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");
using SumUp;


var client = new SumUpClient();


var result = await client.Roles.DeleteAsync(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.roles().deleteMerchantRole(
  "MK10CL2A",
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
from sumup import Sumup


client = Sumup()


result = client.roles.delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
client := sumup.NewClient()


result, err := client.Roles.Delete(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.roles().delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;

Merchants

Merchant account represents a single business entity at SumUp.

The Merchant object

Merchant

  • merchant_code string read only

    Short unique identifier for the merchant.

    Example: "MK01A8C2"
  • organization_id string

    ID of the organization the merchant belongs to (if any).

    Example: "G0UZPVAX"
  • business_type string

    The business type.

    • sole_trader: The business is run by an self-employed individual.
    • company: The business is run as a company with one or more shareholders
    • partnership: The business is run as a company with two or more shareholders that can be also other legal entities
    • non_profit: The business is run as a nonprofit organization that operates for public or social benefit
    • government_entity: The business is state owned and operated
  • company object docs

    Information about the company or business. This is legal information that is used for verification.

     Show attributes
     Close
    Attributes
    • name string max length: 512

      The company's legal name.

      Example: "Gin & Doughnuts Bar GmbH"
    • merchant_category_code string pattern: ^[0-9]{4}$

      The merchant category code for the account as specified by ISO18245. MCCs are used to classify businesses based on the goods or services they provide.

      Example: "1532"
    • legal_type string min length: 4max length: 64 docs

      The unique legal type reference as defined in the country SDK. We do not rely on IDs as used by other services. Consumers of this API are expected to use the country SDK to map to any other IDs, translation keys, or descriptions.

    • address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • trading_address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • identifiers []object

      A list of country-specific company identifiers.

    • phone_number string max length: 64

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • website string max length: 255nullable

      HTTP(S) URL of the company's website.

    • attributes object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
  • country string min length: 2max length: 2

    An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

    Example: "BR"
  • business_profile object

    Business information about the merchant. This information will be visible to the merchant's customers.

     Show attributes
     Close
    Attributes
    • name string max length: 512

      The customer-facing business name.

      Example: "Gin & Dougnuts"
    • dynamic_descriptor string max length: 30pattern: ^[a-zA-Z0-9 \-+\'_.]{0,30}$

      The descriptor is the text that your customer sees on their bank account statement. The more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).

    • website string max length: 512

      The business's publicly available website.

      Example: "https://gindoughnuts.com"
    • email string max length: 256

      A publicly available email address.

      Example: "contact@gindoughnuts.com"
    • phone_number string max length: 64

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • branding object

      Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.

       Show attributes
       Close
      Attributes
      • icon string uri

        An icon for the merchant. Must be square.

      • logo string uri

        A logo for the merchant that will be used in place of the icon and without the merchant's name next to it if there's sufficient space.

      • hero string uri

        Data-URL encoded hero image for the merchant business.

      • primary_color string

        A hex color value representing the primary branding color of this merchant (your brand color).

      • primary_color_fg string

        A hex color value representing the color of the text displayed on branding color of this merchant.

      • secondary_color string

        A hex color value representing the secondary branding color of this merchant (accent color used for buttons).

      • secondary_color_fg string

        A hex color value representing the color of the text displayed on secondary branding color of this merchant.

      • background_color string

        A hex color value representing the preferred background color of this merchant.

  • avatar string url

    A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see merchant.business_profile.branding.

  • alias string

    A user-facing name of the merchant account for use in dashboards and other user-facing applications. For customer-facing business name see merchant.business_profile.

  • default_currency string min length: 3max length: 3read only

    Three-letter ISO currency code representing the default currency for the account.

    Example: "EUR"
  • default_locale string min length: 2max length: 5

    Merchant's default locale, represented as a BCP47 RFC5646 language tag. This is typically an ISO 639-1 Alpha-2 ISO639‑1 language code in lowercase and an ISO 3166-1 Alpha-2 ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or fr-CA. In multilingual countries this is the merchant's preferred locale out of those, that are officially spoken in the country. In a countries with a single official language this will match the official language.

    Example: "de-DE"
  • sandbox boolean

    True if the merchant is a sandbox for testing.

  • meta object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • classic object
     Show attributes
     Close
    Attributes
    • id integer deprecated required

      Classic (serial) merchant ID.

      Example: 1234
  • version string

    The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

  • change_status string read only

    Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

  • created_at string date-timeread only

    The date and time when the resource was created. This is a string as defined in RFC 3339, section 5.6.

  • updated_at string date-timeread only

    The date and time when the resource was last updated. This is a string as defined in RFC 3339, section 5.6.

The Merchant object
{
  "merchant_code": "MK01A8C2",
  "organization_id": "G0UZPVAX",
  "business_type": null,
  "company": {
    "name": "Gin & Doughnuts Bar GmbH",
    "merchant_category_code": "1532",
    "legal_type": "de.freiberufler",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "trading_address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "identifiers": [
      {
        "ref": "de.gmbh",
        "value": "HRB 123456"
      }
    ],
    "phone_number": "+420123456789",
    "website": "https://www.sumup.com",
    "attributes": {}
  },
  "country": "BR",
  "business_profile": {
    "name": "Gin & Dougnuts",
    "dynamic_descriptor": null,
    "website": "https://gindoughnuts.com",
    "email": "contact@gindoughnuts.com",
    "phone_number": "+420123456789",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "branding": {
      "icon": null,
      "logo": null,
      "hero": null,
      "primary_color": "#FF4B3A",
      "primary_color_fg": "#FF4B3A",
      "secondary_color": "#FF4B3A",
      "secondary_color_fg": "#FF4B3A",
      "background_color": "#FF4B3A"
    }
  },
  "avatar": null,
  "alias": null,
  "default_currency": "EUR",
  "default_locale": "de-DE",
  "sandbox": null,
  "meta": {},
  "classic": {
    "id": 1234
  },
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
  "change_status": null,
  "created_at": "2021-08-31T12:00:00Z",
  "updated_at": "2021-08-31T12:00:00Z"
}
Merchants

Retrieve a Merchant

Retrieve a merchant.

Required scopes: user.profile user.profile_readonly
Required permissions: merchant_read

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Query Parameters

  • version string

    The version of the resource. At the moment, the only supported value is latest. When provided and the requested resource's change_status is pending, the resource will be returned with all pending changes applied. When no changes are pending the resource is returned as is. The change_status in the response body will reflect the current state of the resource.

Merchant

  • merchant_code string read only

    Short unique identifier for the merchant.

    Example: "MK01A8C2"
  • organization_id string

    ID of the organization the merchant belongs to (if any).

    Example: "G0UZPVAX"
  • business_type string

    The business type.

    • sole_trader: The business is run by an self-employed individual.
    • company: The business is run as a company with one or more shareholders
    • partnership: The business is run as a company with two or more shareholders that can be also other legal entities
    • non_profit: The business is run as a nonprofit organization that operates for public or social benefit
    • government_entity: The business is state owned and operated
  • company object docs

    Information about the company or business. This is legal information that is used for verification.

     Show attributes
     Close
    Attributes
    • name string max length: 512

      The company's legal name.

      Example: "Gin & Doughnuts Bar GmbH"
    • merchant_category_code string pattern: ^[0-9]{4}$

      The merchant category code for the account as specified by ISO18245. MCCs are used to classify businesses based on the goods or services they provide.

      Example: "1532"
    • legal_type string min length: 4max length: 64 docs

      The unique legal type reference as defined in the country SDK. We do not rely on IDs as used by other services. Consumers of this API are expected to use the country SDK to map to any other IDs, translation keys, or descriptions.

    • address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • trading_address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • identifiers []object

      A list of country-specific company identifiers.

    • phone_number string max length: 64

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • website string max length: 255nullable

      HTTP(S) URL of the company's website.

    • attributes object

      Object attributes that are modifiable only by SumUp applications.

       Show attributes
       Close
      Attributes
      Example: {}
  • country string min length: 2max length: 2

    An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

    Example: "BR"
  • business_profile object

    Business information about the merchant. This information will be visible to the merchant's customers.

     Show attributes
     Close
    Attributes
    • name string max length: 512

      The customer-facing business name.

      Example: "Gin & Dougnuts"
    • dynamic_descriptor string max length: 30pattern: ^[a-zA-Z0-9 \-+\'_.]{0,30}$

      The descriptor is the text that your customer sees on their bank account statement. The more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).

    • website string max length: 512

      The business's publicly available website.

      Example: "https://gindoughnuts.com"
    • email string max length: 256

      A publicly available email address.

      Example: "contact@gindoughnuts.com"
    • phone_number string max length: 64

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • branding object

      Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.

       Show attributes
       Close
      Attributes
      • icon string uri

        An icon for the merchant. Must be square.

      • logo string uri

        A logo for the merchant that will be used in place of the icon and without the merchant's name next to it if there's sufficient space.

      • hero string uri

        Data-URL encoded hero image for the merchant business.

      • primary_color string

        A hex color value representing the primary branding color of this merchant (your brand color).

      • primary_color_fg string

        A hex color value representing the color of the text displayed on branding color of this merchant.

      • secondary_color string

        A hex color value representing the secondary branding color of this merchant (accent color used for buttons).

      • secondary_color_fg string

        A hex color value representing the color of the text displayed on secondary branding color of this merchant.

      • background_color string

        A hex color value representing the preferred background color of this merchant.

  • avatar string url

    A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see merchant.business_profile.branding.

  • alias string

    A user-facing name of the merchant account for use in dashboards and other user-facing applications. For customer-facing business name see merchant.business_profile.

  • default_currency string min length: 3max length: 3read only

    Three-letter ISO currency code representing the default currency for the account.

    Example: "EUR"
  • default_locale string min length: 2max length: 5

    Merchant's default locale, represented as a BCP47 RFC5646 language tag. This is typically an ISO 639-1 Alpha-2 ISO639‑1 language code in lowercase and an ISO 3166-1 Alpha-2 ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or fr-CA. In multilingual countries this is the merchant's preferred locale out of those, that are officially spoken in the country. In a countries with a single official language this will match the official language.

    Example: "de-DE"
  • sandbox boolean

    True if the merchant is a sandbox for testing.

  • meta object

    A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

    Warning: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.

     Show attributes
     Close
    Attributes
    Example: {}
  • classic object
     Show attributes
     Close
    Attributes
    • id integer deprecated required

      Classic (serial) merchant ID.

      Example: 1234
  • version string

    The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

  • change_status string read only

    Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

  • created_at string date-timeread only

    The date and time when the resource was created. This is a string as defined in RFC 3339, section 5.6.

  • updated_at string date-timeread only

    The date and time when the resource was last updated. This is a string as defined in RFC 3339, section 5.6.

GET /v1/merchants/{merchant_code} 
curl https://api.sumup.com/v1/merchants/{merchant_code} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchants.get("MK10CL2A");
using SumUp;


var client = new SumUpClient();


var result = await client.Merchants.GetAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchants().getMerchant(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.merchants.get("MK10CL2A")
client := sumup.NewClient()


result, err := client.Merchants.Get(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.merchants().get("MK10CL2A", sumup::GetMerchantParams{
    version: Some("version".to_string()),
}).await;
Retrieve a Merchant response
{
  "merchant_code": "MK01A8C2",
  "organization_id": "G0UZPVAX",
  "business_type": null,
  "company": {
    "name": "Gin & Doughnuts Bar GmbH",
    "merchant_category_code": "1532",
    "legal_type": "de.freiberufler",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "trading_address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "identifiers": [
      {
        "ref": "de.gmbh",
        "value": "HRB 123456"
      }
    ],
    "phone_number": "+420123456789",
    "website": "https://www.sumup.com",
    "attributes": {}
  },
  "country": "BR",
  "business_profile": {
    "name": "Gin & Dougnuts",
    "dynamic_descriptor": null,
    "website": "https://gindoughnuts.com",
    "email": "contact@gindoughnuts.com",
    "phone_number": "+420123456789",
    "address": {
      "street_address": [
        "Paul-Linke-Ufer 39-40",
        "2. Hinterhof"
      ],
      "post_code": "10999",
      "city": "Berlin",
      "country": "DE"
    },
    "branding": {
      "icon": null,
      "logo": null,
      "hero": null,
      "primary_color": "#FF4B3A",
      "primary_color_fg": "#FF4B3A",
      "secondary_color": "#FF4B3A",
      "secondary_color_fg": "#FF4B3A",
      "background_color": "#FF4B3A"
    }
  },
  "avatar": null,
  "alias": null,
  "default_currency": "EUR",
  "default_locale": "de-DE",
  "sandbox": null,
  "meta": {},
  "classic": {
    "id": 1234
  },
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
  "change_status": null,
  "created_at": "2021-08-31T12:00:00Z",
  "updated_at": "2021-08-31T12:00:00Z"
}
Merchants

List Persons

Returns a list of persons related to the merchant.

Required scopes: user.profile user.profile_readonly
Required permissions: persons_read

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Query Parameters

  • version string

    The version of the resource. At the moment, the only supported value is latest. When provided and the requested resource's change_status is pending, the resource will be returned with all pending changes applied. When no changes are pending the resource is returned as is. The change_status in the response body will reflect the current state of the resource.

Response 200

  • items []object required
     Show attributes
     Close
    Attributes
    • id string read only

      The unique identifier for the person. This is a typeid.

    • user_id string

      A corresponding identity user ID for the person, if they have a user account.

    • birthdate string date

      The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.

      Example: "1980-01-12"
    • given_name string max length: 60

      The first name(s) of the individual.

      Example: "James Herrald"
    • family_name string max length: 60

      The last name(s) of the individual.

      Example: "Bond"
    • middle_name string max length: 60

      Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

      Example: "Maria Sophie"
    • phone_number string max length: 64

      A publicly available phone number in E.164 format.

      Example: "+420123456789"
    • relationships []string min items: 1max items: 1

      A list of roles the person has in the merchant or towards SumUp. A merchant must have at least one person with the relationship representative.

       Show attributes
       Close
      Attributes
    • ownership object
       Show attributes
       Close
      Attributes
      • share integer minimum: 25000maximum: 100000 required

        The percent of ownership shares held by the person expressed in percent mille (1/100000). Only persons with the relationship owner can have ownership.

        Example: 50000
    • address object docs

      An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

       Show attributes
       Close
      Attributes
      • street_address []string max items: 2
         Show attributes
         Close
        Attributes
      • post_code string max length: 32

        The postal code (aka. zip code) of the address.

        Example: "10999"
      • country string min length: 2max length: 2 required

        An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

        Example: "BR"
      • city string max length: 512

        The city of the address.

        Example: "Berlin"
      • province string max length: 512

        The province where the address is located. This may not be relevant in some countries.

        Example: "Berlin"
      • region string max length: 512

        The region where the address is located. This may not be relevant in some countries.

        Example: "Baden Wuerttemberg"
      • county string max length: 512

        A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

        Example: "Dublin County"
      • autonomous_community string max length: 512

        In Spain, an autonomous community is the first sub-national level of political and administrative division.

        Example: "Catalonia"
      • post_town string max length: 512

        A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

        Example: "London"
      • state string max length: 512

        Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

        Example: "California"
      • neighborhood string max length: 512

        Locality level of the address. Used in countries such as Brazil or Chile.

        Example: "Copacabana"
      • commune string max length: 512

        In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

        Example: "Providencia"
      • department string max length: 512

        A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

        Example: "Antioquia"
      • municipality string max length: 512

        A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

        Example: "Medellín"
      • district string max length: 512

        A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

        Example: "Lisbon District"
      • zip_code string max length: 512

        A US system of postal codes used by the United States Postal Service (USPS).

        Example: "94103"
      • eircode string max length: 512

        A postal address in Ireland.

        Example: "D02 X285"
      Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
    • identifiers []object max items: 5

      A list of country-specific personal identifiers.

       Show attributes
       Close
      Attributes
      • ref string required

        The unique reference for the personal identifier type.

        Example: "br.cpf"
      • value string required

        The company identifier value.

        Example: "847.060.136-90"
    • citizenship string min length: 2max length: 2

      An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

      Example: "BR"
    • nationality string nullable

      The persons nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard.

    • country_of_residence string min length: 2max length: 2nullable

      An ISO3166-1 alpha-2 country code representing the country where the person resides.

    • version string

      The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

    • change_status string read only

      Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

GET /v1/merchants/{merchant_code}/persons 
curl https://api.sumup.com/v1/merchants/{merchant_code}/persons \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchants.listPersons("MK10CL2A");
using SumUp;


var client = new SumUpClient();


var result = await client.Merchants.ListPersonsAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchants().listPersons(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.merchants.list_persons("MK10CL2A")
client := sumup.NewClient()


result, err := client.Merchants.ListPersons(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.merchants().list_persons("MK10CL2A", sumup::ListPersonsParams{
    version: Some("version".to_string()),
}).await;
List Persons response
{
  "items": [
    {
      "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
      "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
      "birthdate": "1980-01-12",
      "given_name": "James Herrald",
      "family_name": "Bond",
      "middle_name": "Maria Sophie",
      "phone_number": "+420123456789",
      "relationships": [
        "representative"
      ],
      "ownership": {
        "share": 50000
      },
      "address": {
        "street_address": [
          "Paul-Linke-Ufer 39-40",
          "2. Hinterhof"
        ],
        "post_code": "10999",
        "city": "Berlin",
        "country": "DE"
      },
      "identifiers": [
        {
          "ref": "br.cpf",
          "value": "847.060.136-90"
        }
      ],
      "citizenship": "BR",
      "nationality": null,
      "country_of_residence": null,
      "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
      "change_status": null
    }
  ]
}
Merchants

Retrieve a Person

Returns a single person related to the merchant.

Required scopes: user.profile user.profile_readonly
Required permissions: persons_read

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • person_id string required

    Person ID

    Example: "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z"

Query Parameters

  • version string

    The version of the resource. At the moment, the only supported value is latest. When provided and the requested resource's change_status is pending, the resource will be returned with all pending changes applied. When no changes are pending the resource is returned as is. The change_status in the response body will reflect the current state of the resource.

Response 200

  • id string read only

    The unique identifier for the person. This is a typeid.

  • user_id string

    A corresponding identity user ID for the person, if they have a user account.

  • birthdate string date

    The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.

    Example: "1980-01-12"
  • given_name string max length: 60

    The first name(s) of the individual.

    Example: "James Herrald"
  • family_name string max length: 60

    The last name(s) of the individual.

    Example: "Bond"
  • middle_name string max length: 60

    Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

    Example: "Maria Sophie"
  • phone_number string max length: 64

    A publicly available phone number in E.164 format.

    Example: "+420123456789"
  • relationships []string min items: 1max items: 1

    A list of roles the person has in the merchant or towards SumUp. A merchant must have at least one person with the relationship representative.

     Show attributes
     Close
    Attributes
  • ownership object
     Show attributes
     Close
    Attributes
    • share integer minimum: 25000maximum: 100000 required

      The percent of ownership shares held by the person expressed in percent mille (1/100000). Only persons with the relationship owner can have ownership.

      Example: 50000
  • address object docs

    An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.

     Show attributes
     Close
    Attributes
    • street_address []string max items: 2
       Show attributes
       Close
      Attributes
    • post_code string max length: 32

      The postal code (aka. zip code) of the address.

      Example: "10999"
    • country string min length: 2max length: 2 required

      An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

      Example: "BR"
    • city string max length: 512

      The city of the address.

      Example: "Berlin"
    • province string max length: 512

      The province where the address is located. This may not be relevant in some countries.

      Example: "Berlin"
    • region string max length: 512

      The region where the address is located. This may not be relevant in some countries.

      Example: "Baden Wuerttemberg"
    • county string max length: 512

      A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.

      Example: "Dublin County"
    • autonomous_community string max length: 512

      In Spain, an autonomous community is the first sub-national level of political and administrative division.

      Example: "Catalonia"
    • post_town string max length: 512

      A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.

      Example: "London"
    • state string max length: 512

      Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.

      Example: "California"
    • neighborhood string max length: 512

      Locality level of the address. Used in countries such as Brazil or Chile.

      Example: "Copacabana"
    • commune string max length: 512

      In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.

      Example: "Providencia"
    • department string max length: 512

      A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.

      Example: "Antioquia"
    • municipality string max length: 512

      A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.

      Example: "Medellín"
    • district string max length: 512

      A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.

      Example: "Lisbon District"
    • zip_code string max length: 512

      A US system of postal codes used by the United States Postal Service (USPS).

      Example: "94103"
    • eircode string max length: 512

      A postal address in Ireland.

      Example: "D02 X285"
    Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
  • identifiers []object max items: 5

    A list of country-specific personal identifiers.

     Show attributes
     Close
    Attributes
    • ref string required

      The unique reference for the personal identifier type.

      Example: "br.cpf"
    • value string required

      The company identifier value.

      Example: "847.060.136-90"
  • citizenship string min length: 2max length: 2

    An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.

    Example: "BR"
  • nationality string nullable

    The persons nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard.

  • country_of_residence string min length: 2max length: 2nullable

    An ISO3166-1 alpha-2 country code representing the country where the person resides.

  • version string

    The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.

  • change_status string read only

    Reflects the status of changes submitted through the PATCH endpoints for the merchant or persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

GET /v1/merchants/{merchant_code}/persons/{person_id} 
curl https://api.sumup.com/v1/merchants/{merchant_code}/persons/{person_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchants.getPerson("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z");
using SumUp;


var client = new SumUpClient();


var result = await client.Merchants.GetPersonAsync(
    "MK10CL2A",
    "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchants().getPerson(
  "MK10CL2A",
  "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z"
);
from sumup import Sumup


client = Sumup()


result = client.merchants.get_person("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z")
client := sumup.NewClient()


result, err := client.Merchants.GetPerson(context.Background(), "MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z")
use sumup::Client;


let client = Client::default();


let result = client.merchants().get_person("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z", sumup::GetPersonParams{
    version: Some("version".to_string()),
}).await;
Retrieve a Person response
{
  "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
  "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
  "birthdate": "1980-01-12",
  "given_name": "James Herrald",
  "family_name": "Bond",
  "middle_name": "Maria Sophie",
  "phone_number": "+420123456789",
  "relationships": [
    "representative"
  ],
  "ownership": {
    "share": 50000
  },
  "address": {
    "street_address": [
      "Paul-Linke-Ufer 39-40",
      "2. Hinterhof"
    ],
    "post_code": "10999",
    "city": "Berlin",
    "country": "DE"
  },
  "identifiers": [
    {
      "ref": "br.cpf",
      "value": "847.060.136-90"
    }
  ],
  "citizenship": "BR",
  "nationality": null,
  "country_of_residence": null,
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
  "change_status": null
}

Readers

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.

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

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

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

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

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the reader was created.

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

    The timestamp of when the reader was last updated.

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

List Readers

List all readers of the merchant.

Required scopes: readers.read
Required permissions: readers_list

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Response 200

  • items []object required
     Show attributes
     Close
    Reader
    • id string min length: 30max length: 30 required

      Unique identifier of the object.

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

      Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
    • name string max length: 500 required

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

      Example: "Frontdesk"
    • status string required

      The status of the reader object gives information about the current state of the reader.

      Possible values:

      • unknown - The reader status is unknown.
      • processing - The reader is created and waits for the physical device to confirm the pairing.
      • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
      • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
      Example: "paired"
    • device object required

      Information about the underlying physical device.

       Show attributes
       Close
      Attributes
      • identifier string required

        A unique identifier of the physical device (e.g. serial number).

        Example: "U1DT3NA00-CN"
      • model string required
        Options:  solo virtual-solo

        Identifier of the model of the device.

        Example: "solo"
    • metadata object max properties: 64

      Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

       Show attributes
       Close
      Attributes
      Example: {}
    • created_at string date-time required

      The timestamp of when the reader was created.

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

      The timestamp of when the reader was last updated.

      Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/readers 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.list("MK10CL2A");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.ListAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().listReaders(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.readers.list("MK10CL2A")
client := sumup.NewClient()


result, err := client.Readers.List(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.readers().list("MK10CL2A").await;
List Readers response
{
  "items": [
    {
      "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
      "name": "Frontdesk",
      "status": "paired",
      "device": {
        "identifier": "U1DT3NA00-CN",
        "model": "solo"
      },
      "metadata": {},
      "created_at": "2023-01-18T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}
Readers

Create a Reader

Create a new Reader for the merchant account.

Required scopes: readers.write
Required permissions: readers_create

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Body Parameters

  • pairing_code string min length: 8max length: 9 required

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

    Example: "4WLFDSBF"
  • name string max length: 500 required

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

    Example: "Frontdesk"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

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

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

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

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the reader was created.

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

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
POST /v0.1/merchants/{merchant_code}/readers 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "pairing_code": "4WLFDSBF",
    "name": "Frontdesk"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.create("MK10CL2A", {
  pairing_code: "4WLFDSBF",
  name: "Frontdesk",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.CreateAsync(
    "MK10CL2A",
    new CreateReaderBody
    {
        PairingCode = "4WLFDSBF",
        Name = "Frontdesk",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().createReader(
  "MK10CL2A",
  CreateReaderBody.builder()
    .pairingCode("4WLFDSBF")
    .name("Frontdesk")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.readers.create("MK10CL2A", CreateReaderBody(
  pairing_code="4WLFDSBF",
  name="Frontdesk",
))
client := sumup.NewClient()


result, err := client.Readers.Create(context.Background(), "MK10CL2A", readers.CreateReaderBody{
  PairingCode: "4WLFDSBF",
  Name: "Frontdesk",
})
use sumup::Client;


let client = Client::default();


let result = client.readers().create("MK10CL2A", sumup::CreateReaderBody{
  pairing_code: "4WLFDSBF".to_string(),
  name: "Frontdesk".to_string(),
}).await;
Response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "processing",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "created_at": "2023-05-09T14:50:20.214Z",
  "updated_at": "2023-05-09T14:52:58.714Z"
}
Readers

Retrieve a Reader

Retrieve a Reader.

Required scopes: readers.read
Required permissions: readers_view

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • id string min length: 30max length: 30 required

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

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

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

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

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the reader was created.

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

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.get("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.GetAsync(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().getReader(
  "MK10CL2A",
  "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
from sumup import Sumup


client = Sumup()


result = client.readers.get("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
client := sumup.NewClient()


result, err := client.Readers.Get(context.Background(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
use sumup::Client;


let client = Client::default();


let result = client.readers().get("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65").await;
Retrieve a Reader response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "metadata": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Update a Reader

Update a Reader.

Required scopes: readers.write
Required permissions: readers_update

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • id string min length: 30max length: 30 required

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"

Body Parameters

  • name string max length: 500

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

    Example: "Frontdesk"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}

Reader

  • id string min length: 30max length: 30 required

    Unique identifier of the object.

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

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
  • name string max length: 500 required

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

    Example: "Frontdesk"
  • status string required

    The status of the reader object gives information about the current state of the reader.

    Possible values:

    • unknown - The reader status is unknown.
    • processing - The reader is created and waits for the physical device to confirm the pairing.
    • paired - The reader is paired with a merchant account and can be used with SumUp APIs.
    • expired - The pairing is expired and no longer usable with the account. The resource needs to get recreated.
    Example: "paired"
  • device object required

    Information about the underlying physical device.

     Show attributes
     Close
    Attributes
    • identifier string required

      A unique identifier of the physical device (e.g. serial number).

      Example: "U1DT3NA00-CN"
    • model string required
      Options:  solo virtual-solo

      Identifier of the model of the device.

      Example: "solo"
  • metadata object max properties: 64

    Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

     Show attributes
     Close
    Attributes
    Example: {}
  • created_at string date-time required

    The timestamp of when the reader was created.

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

    The timestamp of when the reader was last updated.

    Example: "2023-01-20T15:16:17Z"
PATCH /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X PATCH \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.update("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.UpdateAsync(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
    new UpdateReaderBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().updateReader(
  "MK10CL2A",
  "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  UpdateReaderBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.readers.update("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", UpdateReaderBody(


))
client := sumup.NewClient()


result, err := client.Readers.Update(context.Background(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", readers.UpdateReaderBody{


})
use sumup::Client;


let client = Client::default();


let result = client.readers().update("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", sumup::UpdateReaderBody{}).await;
Update a Reader response
{
  "id": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65",
  "name": "Frontdesk",
  "status": "paired",
  "device": {
    "identifier": "U1DT3NA00-CN",
    "model": "solo"
  },
  "metadata": {},
  "created_at": "2023-01-18T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Readers

Delete a reader

Delete a reader.

Required scopes: readers.write
Required permissions: readers_delete

Path Parameters

  • merchant_code string required

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • id string min length: 30max length: 30 required

    The unique identifier of the reader.

    Example: "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
DELETE /v0.1/merchants/{merchant_code}/readers/{id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.delete("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.DeleteAsync(
    "MK10CL2A",
    "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().deleteReader(
  "MK10CL2A",
  "rdr_3MSAFM23CK82VSTT4BN6RWSQ65"
);
from sumup import Sumup


client = Sumup()


result = client.readers.delete("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
client := sumup.NewClient()


result, err := client.Readers.Delete(context.Background(), "MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65")
use sumup::Client;


let client = Client::default();


let result = client.readers().delete("MK10CL2A", "rdr_3MSAFM23CK82VSTT4BN6RWSQ65").await;
Readers

Get a Reader Status

Provides the last known status for a Reader.

This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state).

Supported States

  • IDLE – Reader ready for next transaction
  • SELECTING_TIP – Waiting for tip input
  • WAITING_FOR_CARD – Awaiting card insert/tap
  • WAITING_FOR_PIN – Waiting for PIN entry
  • WAITING_FOR_SIGNATURE – Waiting for customer signature
  • UPDATING_FIRMWARE – Firmware update in progress

Device Status

  • ONLINE – Device connected and operational
  • OFFLINE – Device disconnected (last state persisted)

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

Required scopes: readers.read
Required permissions: readers_view

Path Parameters

  • merchant_code string required

    Merchant Code

  • reader_id string required

    The unique identifier of the Reader

StatusResponse

  • data object required
     Show attributes
     Close
    Attributes
    • battery_level number minimum: 0maximum: 100

      Battery level percentage

      Example: 10.5
    • battery_temperature integer

      Battery temperature in Celsius

      Example: 35
    • connection_type string
      Options:  btle edge gprs lte umts usb Wi-Fi

      Type of connection used by the device

      Example: "Wi-Fi"
    • firmware_version string

      Firmware version of the device

      Example: "3.3.3.21"
    • last_activity string date-time

      Timestamp of the last activity from the device

      Example: "2025-09-25T15:20:00Z"
    • state string
      Options:  IDLE SELECTING_TIP WAITING_FOR_CARD WAITING_FOR_PIN WAITING_FOR_SIGNATURE UPDATING_FIRMWARE

      Latest state of the device

      Example: "IDLE"
    • status string required
      Options:  ONLINE OFFLINE

      Status of a device

      Example: "ONLINE"
GET /v0.1/merchants/{merchant_code}/readers/{reader_id}/status 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/status \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.getStatus("merchant_code", "reader_id", "Accept", "Content-Type", "Authorization");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.GetStatusAsync(
    "merchant_code",
    "reader_id",
    "Accept",
    "Content-Type",
    "Authorization"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().getReaderStatus(
  "merchant_code",
  "reader_id",
  "Accept",
  "Content-Type",
  "Authorization"
);
from sumup import Sumup


client = Sumup()


result = client.readers.get_status("merchant_code", "reader_id", "Accept", "Content-Type", "Authorization")
client := sumup.NewClient()


result, err := client.Readers.GetStatus(context.Background(), "merchant_code", "reader_id", "Accept", "Content-Type", "Authorization")
use sumup::Client;


let client = Client::default();


let result = client.readers().get_status("merchant_code", "reader_id").await;
Get a Reader Status response
{
  "data": {
    "battery_level": 10,
    "battery_temperature": 35,
    "connection_type": "Wi-Fi",
    "firmware_version": "3.3.3.21",
    "last_activity": "2025-09-25T15:20:00Z",
    "state": "IDLE",
    "status": "ONLINE"
  }
}
Readers

Create a Reader Checkout

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

Required scopes: readers.write
Required permissions: readers_checkout_create

Path Parameters

  • merchant_code string required

    Merchant Code

  • reader_id string required

    The unique identifier of the Reader

CreateReaderCheckoutRequest

  • affiliate object nullable

    Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction.

     Show attributes
     Close
    Affiliate
    • 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: "19e12390-72cf-4f9f-80b5-b0c8a67fa43f"
    • 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 associated with the transaction.

       Show attributes
       Close
      Attributes
      Example: {"custom_key_1":"custom_value_1","custom_key_2":"custom_value_2"}
  • 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 minimum: 1nullable

    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.

    Omit if the merchant country does support installments. Otherwise, the checkout will be rejected.

    Example: 1
  • return_url string uri

    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
  • tip_timeout integer minimum: 30maximum: 120default: 30

    Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds.

    It can only be set if tip_rates is provided.

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

    Example: 30
  • total_amount object required

    Amount structure.

    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
    Money
    • currency string required

      Currency ISO 4217 code

      Example: "EUR"
    • minor_unit integer minimum: 0 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 minimum: 0 required

      Integer value of the amount.

      Example: 1000
    Example: {"currency":"EUR","minor_unit":2,"value":1000}

CreateReaderCheckoutResponse

  • data object required
     Show attributes
     Close
    Attributes
    • client_transaction_id string required

      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: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "total_amount": {
      "currency": "EUR",
      "minor_unit": 2,
      "value": 5033
    }
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.createCheckout("merchant_code", "reader_id", {
  total_amount: {
    currency: "EUR",
    minor_unit: 2,
    value: 5033,
  },
});
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.CreateCheckoutAsync(
    "merchant_code",
    "reader_id",
    new CreateReaderCheckoutRequest
    {
        TotalAmount = new Money
        {
            Currency = "EUR",
            MinorUnit = 2,
            Value = 5033,
        },
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().createReaderCheckout(
  "merchant_code",
  "reader_id",
  CreateReaderCheckoutRequest.builder()
    .totalAmount(Money.builder()
        .currency("EUR")
        .minorUnit(2)
        .value(5033)
        .build())
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.readers.create_checkout("merchant_code", "reader_id", CreateReaderCheckoutBody(
  total_amount=Money(
    currency="EUR",
    minor_unit=2,
    value=5033,
  ),
))
client := sumup.NewClient()


result, err := client.Readers.CreateCheckout(context.Background(), "merchant_code", "reader_id", readers.CreateReaderCheckoutBody{
  TotalAmount: readers.Money{
    Currency: "EUR",
    MinorUnit: 2,
    Value: 5033,
  },
})
use sumup::Client;


let client = Client::default();


let result = client.readers().create_checkout("merchant_code", "reader_id", sumup::CreateReaderCheckoutBody{
  total_amount: sumup::Money {
    currency: "EUR".to_string(),
    minor_unit: 2,
    value: 5033,
  },
}).await;
Create a Reader Checkout response
{
  "data": {
    "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
Readers

Terminate a Reader Checkout

Terminate a Reader Checkout stops the current transaction on the target device.

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

There are some caveats when using this endpoint:

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

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

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

Required scopes: readers.write
Required permissions: readers_checkout_create

Path Parameters

  • merchant_code string required

    Merchant Code

  • reader_id string required

    The unique identifier of the Reader

POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.readers.terminateCheckout("merchant_code", "reader_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Readers.TerminateCheckoutAsync(
    "merchant_code",
    "reader_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.readers().createReaderTerminate(
  "merchant_code",
  "reader_id"
);
from sumup import Sumup


client = Sumup()


result = client.readers.terminate_checkout("merchant_code", "reader_id")
client := sumup.NewClient()


result, err := client.Readers.TerminateCheckout(context.Background(), "merchant_code", "reader_id")
use sumup::Client;


let client = Client::default();


let result = client.readers().terminate_checkout("merchant_code", "reader_id").await;

Merchant

Manage merchant profile.

The Merchant Account object

Details of the merchant account.

Merchant Account

  • account object

    Profile information.

     Show attributes
     Close
    Attributes
    • username string

      Username of the user profile.

    • type string
      Options:  normal operator

      The role of the user.

  • personal_profile object

    Account's personal profile.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the user

    • last_name string

      Last name of the user

    • date_of_birth string

      Date of birth

    • mobile_phone string

      Mobile phone number

    • address object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1 string

        Address line 1

      • address_line2 string

        Address line 2

      • city string

        City

      • country string

        Country ISO 3166-1 code

      • region_id number

        Country region id

      • region_name string

        Region name

      • region_code string

        Region code

      • post_code string

        Postal code

      • landline string

        Landline number

      • first_name string

        undefined

      • last_name string

        undefined

      • company string

        undefined

      • country_details object

        Country Details

         Show attributes
         Close
        Attributes
        • currency string

          Currency ISO 4217 code

        • iso_code string

          Country ISO code

        • en_name string

          Country EN name

        • native_name string

          Country native name

      • timeoffset_details object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code string

          Postal code

        • offset number

          UTC offset

        • dst boolean

          Daylight Saving Time

      • state_id string

        undefined

    • complete boolean
  • merchant_profile object

    Account's merchant profile

     Show attributes
     Close
    Attributes
    • merchant_code string

      Unique identifying code of the merchant profile

      Example: "MH4H92C7"
    • company_name string

      Company name

    • website string

      Website

    • legal_type object

      Id of the legal type of the merchant profile

       Show attributes
       Close
      Attributes
      • id number

        Unique id

      • full_description string

        Legal type description

      • description string

        Legal type short description

      • sole_trader boolean

        Sole trader legal type if true

    • merchant_category_code string

      Merchant category code

    • mobile_phone string

      Mobile phone number

    • company_registration_number string

      Company registration number

    • vat_id string

      Vat ID

    • permanent_certificate_access_code string

      Permanent certificate access code &#40;Portugal&#41;

    • nature_and_purpose string

      Nature and purpose of the business

    • address object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1 string

        Address line 1

      • address_line2 string

        Address line 2

      • city string

        City

      • country string

        Country ISO 3166-1 code

      • region_id number

        Country region id

      • region_name string

        Region name

      • region_code string

        Region code

      • post_code string

        Postal code

      • landline string

        Landline number

      • first_name string

        undefined

      • last_name string

        undefined

      • company string

        undefined

      • country_details object

        Country Details

         Show attributes
         Close
        Attributes
        • currency string

          Currency ISO 4217 code

        • iso_code string

          Country ISO code

        • en_name string

          Country EN name

        • native_name string

          Country native name

      • timeoffset_details object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code string

          Postal code

        • offset number

          UTC offset

        • dst boolean

          Daylight Saving Time

      • state_id string

        undefined

    • business_owners []object

      Business owners information.

    • doing_business_as object

      Doing Business As information

       Show attributes
       Close
      Attributes
      • business_name string

        Doing business as name

      • company_registration_number string

        Doing business as company registration number

      • vat_id string

        Doing business as VAT ID

      • website string

        Doing business as website

      • email string

        Doing business as email

      • address object
         Show attributes
         Close
        Attributes
        • address_line1 string

          Address line 1

        • address_line2 string

          Address line 2

        • city string

          City

        • country string

          Country ISO 3166-1 code

        • region_id number

          Country region ID

        • region_name string

          Country region name

        • post_code string

          Postal code

    • settings object

      Merchant settings &#40;like &quot;payout_type&quot;, &quot;payout_period&quot;&#41;

       Show attributes
       Close
      Attributes
      • tax_enabled boolean

        Whether to show tax in receipts &#40;saved per transaction&#41;

      • payout_type string

        Payout type

      • payout_period string

        Payout frequency

      • payout_on_demand_available boolean

        Whether merchant can edit payouts on demand

      • payout_on_demand boolean

        Whether merchant will receive payouts on demand

      • printers_enabled boolean

        Whether to show printers in mobile app

      • payout_instrument string

        Payout Instrument

      • moto_payment string
        Options:  UNAVAILABLE ENFORCED ON OFF

        Whether merchant can make MOTO payments

      • stone_merchant_code string

        Stone merchant code

      • daily_payout_email boolean

        Whether merchant will receive daily payout emails

      • monthly_payout_email boolean

        Whether merchant will receive monthly payout emails

      • gross_settlement boolean

        Whether merchant has gross settlement enabled

    • vat_rates object

      Merchant VAT rates

       Show attributes
       Close
      Attributes
      • id number

        Internal ID

      • description string

        Description

      • rate number

        Rate

      • ordering number

        Ordering

      • country string

        Country ISO code

    • locale string

      Merchant locale &#40;for internal usage only&#41;

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

        Bank code

      • branch_code string

        Branch code

      • swift string

        SWIFT code

      • account_number string

        Account number

      • iban string

        IBAN

      • account_type string

        Type of the account

      • account_category string

        Account category - business or personal

      • account_holder_name string
      • status string

        Status in the verification process

      • primary boolean

        The primary bank account is the one used for payouts

      • created_at string

        Creation date of the bank account

      • bank_name string

        Bank name

    • extdev boolean

      True if the merchant is extdev

    • payout_zone_migrated boolean

      True if the payout zone of this merchant is migrated

    • country string

      Merchant country code formatted according to ISO3166-1 alpha-2 &#40;for internal usage only&#41;

  • app_settings object

    Mobile app settings

     Show attributes
     Close
    Attributes
    • checkout_preference string

      Checkout preference

    • include_vat boolean

      Include vat.

    • manual_entry_tutorial boolean

      Manual entry tutorial.

    • mobile_payment_tutorial boolean

      Mobile payment tutorial.

    • tax_enabled boolean

      Tax enabled.

    • mobile_payment string

      Mobile payment.

    • reader_payment string

      Reader payment.

    • cash_payment string

      Cash payment.

    • advanced_mode string

      Advanced mode.

    • expected_max_transaction_amount number

      Expected max transaction amount.

    • manual_entry string

      Manual entry.

    • terminal_mode_tutorial boolean

      Terminal mode tutorial.

    • tipping string

      Tipping.

    • tip_rates []number

      Tip rates.

       Show attributes
       Close
      Attributes
    • barcode_scanner string

      Barcode scanner.

    • referral string

      Referral.

  • permissions object

    User permissions

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean

      Create MOTO payments

    • full_transaction_history_view boolean

      Can view full merchant transaction history

    • refund_transactions boolean

      Refund transactions

    • create_referral boolean

      Create referral

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

Retrieve a profileDeprecated

Returns user profile information.

Required scopes: user.profile user.profile_readonly

Query Parameters

  • include[] []string
    Options:  settings doing_business_as bank_accounts app_settings country_details

    A list of additional information you want to receive for the user. By default only personal and merchant profile information will be returned.

Merchant Account

  • account object

    Profile information.

     Show attributes
     Close
    Attributes
    • username string

      Username of the user profile.

    • type string
      Options:  normal operator

      The role of the user.

  • personal_profile object

    Account's personal profile.

     Show attributes
     Close
    Attributes
    • first_name string

      First name of the user

    • last_name string

      Last name of the user

    • date_of_birth string

      Date of birth

    • mobile_phone string

      Mobile phone number

    • address object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1 string

        Address line 1

      • address_line2 string

        Address line 2

      • city string

        City

      • country string

        Country ISO 3166-1 code

      • region_id number

        Country region id

      • region_name string

        Region name

      • region_code string

        Region code

      • post_code string

        Postal code

      • landline string

        Landline number

      • first_name string

        undefined

      • last_name string

        undefined

      • company string

        undefined

      • country_details object

        Country Details

         Show attributes
         Close
        Attributes
        • currency string

          Currency ISO 4217 code

        • iso_code string

          Country ISO code

        • en_name string

          Country EN name

        • native_name string

          Country native name

      • timeoffset_details object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code string

          Postal code

        • offset number

          UTC offset

        • dst boolean

          Daylight Saving Time

      • state_id string

        undefined

    • complete boolean
  • merchant_profile object

    Account's merchant profile

     Show attributes
     Close
    Attributes
    • merchant_code string

      Unique identifying code of the merchant profile

      Example: "MH4H92C7"
    • company_name string

      Company name

    • website string

      Website

    • legal_type object

      Id of the legal type of the merchant profile

       Show attributes
       Close
      Attributes
      • id number

        Unique id

      • full_description string

        Legal type description

      • description string

        Legal type short description

      • sole_trader boolean

        Sole trader legal type if true

    • merchant_category_code string

      Merchant category code

    • mobile_phone string

      Mobile phone number

    • company_registration_number string

      Company registration number

    • vat_id string

      Vat ID

    • permanent_certificate_access_code string

      Permanent certificate access code &#40;Portugal&#41;

    • nature_and_purpose string

      Nature and purpose of the business

    • address object

      Details of the registered address.

       Show attributes
       Close
      Attributes
      • address_line1 string

        Address line 1

      • address_line2 string

        Address line 2

      • city string

        City

      • country string

        Country ISO 3166-1 code

      • region_id number

        Country region id

      • region_name string

        Region name

      • region_code string

        Region code

      • post_code string

        Postal code

      • landline string

        Landline number

      • first_name string

        undefined

      • last_name string

        undefined

      • company string

        undefined

      • country_details object

        Country Details

         Show attributes
         Close
        Attributes
        • currency string

          Currency ISO 4217 code

        • iso_code string

          Country ISO code

        • en_name string

          Country EN name

        • native_name string

          Country native name

      • timeoffset_details object

        TimeOffset Details

         Show attributes
         Close
        Attributes
        • post_code string

          Postal code

        • offset number

          UTC offset

        • dst boolean

          Daylight Saving Time

      • state_id string

        undefined

    • business_owners []object

      Business owners information.

    • doing_business_as object

      Doing Business As information

       Show attributes
       Close
      Attributes
      • business_name string

        Doing business as name

      • company_registration_number string

        Doing business as company registration number

      • vat_id string

        Doing business as VAT ID

      • website string

        Doing business as website

      • email string

        Doing business as email

      • address object
         Show attributes
         Close
        Attributes
        • address_line1 string

          Address line 1

        • address_line2 string

          Address line 2

        • city string

          City

        • country string

          Country ISO 3166-1 code

        • region_id number

          Country region ID

        • region_name string

          Country region name

        • post_code string

          Postal code

    • settings object

      Merchant settings &#40;like &quot;payout_type&quot;, &quot;payout_period&quot;&#41;

       Show attributes
       Close
      Attributes
      • tax_enabled boolean

        Whether to show tax in receipts &#40;saved per transaction&#41;

      • payout_type string

        Payout type

      • payout_period string

        Payout frequency

      • payout_on_demand_available boolean

        Whether merchant can edit payouts on demand

      • payout_on_demand boolean

        Whether merchant will receive payouts on demand

      • printers_enabled boolean

        Whether to show printers in mobile app

      • payout_instrument string

        Payout Instrument

      • moto_payment string
        Options:  UNAVAILABLE ENFORCED ON OFF

        Whether merchant can make MOTO payments

      • stone_merchant_code string

        Stone merchant code

      • daily_payout_email boolean

        Whether merchant will receive daily payout emails

      • monthly_payout_email boolean

        Whether merchant will receive monthly payout emails

      • gross_settlement boolean

        Whether merchant has gross settlement enabled

    • vat_rates object

      Merchant VAT rates

       Show attributes
       Close
      Attributes
      • id number

        Internal ID

      • description string

        Description

      • rate number

        Rate

      • ordering number

        Ordering

      • country string

        Country ISO code

    • locale string

      Merchant locale &#40;for internal usage only&#41;

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

        Bank code

      • branch_code string

        Branch code

      • swift string

        SWIFT code

      • account_number string

        Account number

      • iban string

        IBAN

      • account_type string

        Type of the account

      • account_category string

        Account category - business or personal

      • account_holder_name string
      • status string

        Status in the verification process

      • primary boolean

        The primary bank account is the one used for payouts

      • created_at string

        Creation date of the bank account

      • bank_name string

        Bank name

    • extdev boolean

      True if the merchant is extdev

    • payout_zone_migrated boolean

      True if the payout zone of this merchant is migrated

    • country string

      Merchant country code formatted according to ISO3166-1 alpha-2 &#40;for internal usage only&#41;

  • app_settings object

    Mobile app settings

     Show attributes
     Close
    Attributes
    • checkout_preference string

      Checkout preference

    • include_vat boolean

      Include vat.

    • manual_entry_tutorial boolean

      Manual entry tutorial.

    • mobile_payment_tutorial boolean

      Mobile payment tutorial.

    • tax_enabled boolean

      Tax enabled.

    • mobile_payment string

      Mobile payment.

    • reader_payment string

      Reader payment.

    • cash_payment string

      Cash payment.

    • advanced_mode string

      Advanced mode.

    • expected_max_transaction_amount number

      Expected max transaction amount.

    • manual_entry string

      Manual entry.

    • terminal_mode_tutorial boolean

      Terminal mode tutorial.

    • tipping string

      Tipping.

    • tip_rates []number

      Tip rates.

       Show attributes
       Close
      Attributes
    • barcode_scanner string

      Barcode scanner.

    • referral string

      Referral.

  • permissions object

    User permissions

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean

      Create MOTO payments

    • full_transaction_history_view boolean

      Can view full merchant transaction history

    • refund_transactions boolean

      Refund transactions

    • create_referral boolean

      Create referral

GET /v0.1/me 
curl https://api.sumup.com/v0.1/me \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchant.get();
using SumUp;


var client = new SumUpClient();


var result = await client.Merchant.GetAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchant().getAccount();
from sumup import Sumup


client = Sumup()


result = client.merchant.get()
client := sumup.NewClient()


result, err := client.Merchant.Get(context.Background())
use sumup::Client;


let client = Client::default();


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

Retrieve a personal profileDeprecated

Retrieves personal profile data.

Required scopes: user.profile user.profile_readonly

Response 200

  • first_name string

    First name of the user

  • last_name string

    Last name of the user

  • date_of_birth string

    Date of birth

  • mobile_phone string

    Mobile phone number

  • address object

    Details of the registered address.

     Show attributes
     Close
    Attributes
    • address_line1 string

      Address line 1

    • address_line2 string

      Address line 2

    • city string

      City

    • country string

      Country ISO 3166-1 code

    • region_id number

      Country region id

    • region_name string

      Region name

    • region_code string

      Region code

    • post_code string

      Postal code

    • landline string

      Landline number

    • first_name string

      undefined

    • last_name string

      undefined

    • company string

      undefined

    • country_details object

      Country Details

       Show attributes
       Close
      Attributes
      • currency string

        Currency ISO 4217 code

      • iso_code string

        Country ISO code

      • en_name string

        Country EN name

      • native_name string

        Country native name

    • timeoffset_details object

      TimeOffset Details

       Show attributes
       Close
      Attributes
      • post_code string

        Postal code

      • offset number

        UTC offset

      • dst boolean

        Daylight Saving Time

    • state_id string

      undefined

  • complete boolean
GET /v0.1/me/personal-profile 
curl https://api.sumup.com/v0.1/me/personal-profile \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchant.getPersonalProfile();
using SumUp;


var client = new SumUpClient();


var result = await client.Merchant.GetPersonalProfileAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchant().getPersonalProfile();
from sumup import Sumup


client = Sumup()


result = client.merchant.get_personal_profile()
client := sumup.NewClient()


result, err := client.Merchant.GetPersonalProfile(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.merchant().get_personal_profile().await;
Retrieve a personal profile response
{
  "first_name": null,
  "last_name": null,
  "date_of_birth": null,
  "mobile_phone": null,
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "region_id": null,
    "region_name": null,
    "region_code": null,
    "post_code": null,
    "landline": null,
    "first_name": null,
    "last_name": null,
    "company": null,
    "country_details": {
      "currency": null,
      "iso_code": null,
      "en_name": null,
      "native_name": null
    },
    "timeoffset_details": {
      "post_code": null,
      "offset": null,
      "dst": null
    },
    "state_id": null
  },
  "complete": null
}
Merchant

Retrieve a merchant profileDeprecated

Retrieves merchant profile data.

Required scopes: user.profile user.profile_readonly

Response 200

  • merchant_code string

    Unique identifying code of the merchant profile

    Example: "MH4H92C7"
  • company_name string

    Company name

  • website string

    Website

  • legal_type object

    Id of the legal type of the merchant profile

     Show attributes
     Close
    Attributes
    • id number

      Unique id

    • full_description string

      Legal type description

    • description string

      Legal type short description

    • sole_trader boolean

      Sole trader legal type if true

  • merchant_category_code string

    Merchant category code

  • mobile_phone string

    Mobile phone number

  • company_registration_number string

    Company registration number

  • vat_id string

    Vat ID

  • permanent_certificate_access_code string

    Permanent certificate access code &#40;Portugal&#41;

  • nature_and_purpose string

    Nature and purpose of the business

  • address object

    Details of the registered address.

     Show attributes
     Close
    Attributes
    • address_line1 string

      Address line 1

    • address_line2 string

      Address line 2

    • city string

      City

    • country string

      Country ISO 3166-1 code

    • region_id number

      Country region id

    • region_name string

      Region name

    • region_code string

      Region code

    • post_code string

      Postal code

    • landline string

      Landline number

    • first_name string

      undefined

    • last_name string

      undefined

    • company string

      undefined

    • country_details object

      Country Details

       Show attributes
       Close
      Attributes
      • currency string

        Currency ISO 4217 code

      • iso_code string

        Country ISO code

      • en_name string

        Country EN name

      • native_name string

        Country native name

    • timeoffset_details object

      TimeOffset Details

       Show attributes
       Close
      Attributes
      • post_code string

        Postal code

      • offset number

        UTC offset

      • dst boolean

        Daylight Saving Time

    • state_id string

      undefined

  • business_owners []object

    Business owners information.

  • doing_business_as object

    Doing Business As information

     Show attributes
     Close
    Attributes
    • business_name string

      Doing business as name

    • company_registration_number string

      Doing business as company registration number

    • vat_id string

      Doing business as VAT ID

    • website string

      Doing business as website

    • email string

      Doing business as email

    • address object
       Show attributes
       Close
      Attributes
      • address_line1 string

        Address line 1

      • address_line2 string

        Address line 2

      • city string

        City

      • country string

        Country ISO 3166-1 code

      • region_id number

        Country region ID

      • region_name string

        Country region name

      • post_code string

        Postal code

  • settings object

    Merchant settings &#40;like &quot;payout_type&quot;, &quot;payout_period&quot;&#41;

     Show attributes
     Close
    Attributes
    • tax_enabled boolean

      Whether to show tax in receipts &#40;saved per transaction&#41;

    • payout_type string

      Payout type

    • payout_period string

      Payout frequency

    • payout_on_demand_available boolean

      Whether merchant can edit payouts on demand

    • payout_on_demand boolean

      Whether merchant will receive payouts on demand

    • printers_enabled boolean

      Whether to show printers in mobile app

    • payout_instrument string

      Payout Instrument

    • moto_payment string
      Options:  UNAVAILABLE ENFORCED ON OFF

      Whether merchant can make MOTO payments

    • stone_merchant_code string

      Stone merchant code

    • daily_payout_email boolean

      Whether merchant will receive daily payout emails

    • monthly_payout_email boolean

      Whether merchant will receive monthly payout emails

    • gross_settlement boolean

      Whether merchant has gross settlement enabled

  • vat_rates object

    Merchant VAT rates

     Show attributes
     Close
    Attributes
    • id number

      Internal ID

    • description string

      Description

    • rate number

      Rate

    • ordering number

      Ordering

    • country string

      Country ISO code

  • locale string

    Merchant locale &#40;for internal usage only&#41;

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

      Bank code

    • branch_code string

      Branch code

    • swift string

      SWIFT code

    • account_number string

      Account number

    • iban string

      IBAN

    • account_type string

      Type of the account

    • account_category string

      Account category - business or personal

    • account_holder_name string
    • status string

      Status in the verification process

    • primary boolean

      The primary bank account is the one used for payouts

    • created_at string

      Creation date of the bank account

    • bank_name string

      Bank name

  • extdev boolean

    True if the merchant is extdev

  • payout_zone_migrated boolean

    True if the payout zone of this merchant is migrated

  • country string

    Merchant country code formatted according to ISO3166-1 alpha-2 &#40;for internal usage only&#41;

GET /v0.1/me/merchant-profile 
curl https://api.sumup.com/v0.1/me/merchant-profile \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchant.getMerchantProfile();
using SumUp;


var client = new SumUpClient();


var result = await client.Merchant.GetMerchantProfileAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchant().getMerchantProfile();
from sumup import Sumup


client = Sumup()


result = client.merchant.get_merchant_profile()
client := sumup.NewClient()


result, err := client.Merchant.GetMerchantProfile(context.Background())
use sumup::Client;


let client = Client::default();


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

Retrieve DBADeprecated

Retrieves Doing Business As profile.

Required scopes: user.profile user.profile_readonly

Response 200

  • business_name string

    Doing business as name

  • company_registration_number string

    Doing business as company registration number

  • vat_id string

    Doing business as VAT ID

  • website string

    Doing business as website

  • email string

    Doing business as email

  • address object
     Show attributes
     Close
    Attributes
    • address_line1 string

      Address line 1

    • address_line2 string

      Address line 2

    • city string

      City

    • country string

      Country ISO 3166-1 code

    • region_id number

      Country region ID

    • region_name string

      Country region name

    • post_code string

      Postal code

GET /v0.1/me/merchant-profile/doing-business-as 
curl https://api.sumup.com/v0.1/me/merchant-profile/doing-business-as \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.merchant.getDoingBusinessAs();
using SumUp;


var client = new SumUpClient();


var result = await client.Merchant.GetDoingBusinessAsAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.merchant().getDoingBusinessAs();
from sumup import Sumup


client = Sumup()


result = client.merchant.get_doing_business_as()
client := sumup.NewClient()


result, err := client.Merchant.GetDoingBusinessAs(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.merchant().get_doing_business_as().await;
Retrieve DBA response
{
  "business_name": null,
  "company_registration_number": null,
  "vat_id": null,
  "website": null,
  "email": null,
  "address": {
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "country": null,
    "region_id": null,
    "region_name": null,
    "post_code": null
  }
}

Subaccounts

Endpoints for managing merchant sub-accounts (operators).

The object

Operator account for a merchant.

Attributes

  • id integer required
  • username string required
    Example: "operator1@mydomain.com"
  • nickname string nullable
    Example: "Operator 1"
  • disabled boolean required
  • created_at string date-time required

    The timestamp of when the operator was created.

  • updated_at string date-time required

    The timestamp of when the operator was last updated.

  • permissions object required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean required
    • create_referral boolean required
    • full_transaction_history_view boolean required
    • refund_transactions boolean required
    • admin boolean required
  • account_type string required
    Options:  operator normal
The object
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

List operatorsDeprecated

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

Required permissions: members_list

Query Parameters

  • query string

    Search query used to filter users that match given query term.

    Current implementation allow querying only over the email address. All operators whos email address contains the query string are returned.

  • include_primary boolean

    If true the list of operators will include also the primary user.

Response 200

[]object
 Show attributes
 Close
Attributes
  • id integer required
  • username string required
    Example: "operator1@mydomain.com"
  • nickname string nullable
    Example: "Operator 1"
  • disabled boolean required
  • created_at string date-time required

    The timestamp of when the operator was created.

  • updated_at string date-time required

    The timestamp of when the operator was last updated.

  • permissions object required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean required
    • create_referral boolean required
    • full_transaction_history_view boolean required
    • refund_transactions boolean required
    • admin boolean required
  • account_type string required
    Options:  operator normal
GET /v0.1/me/accounts 
curl https://api.sumup.com/v0.1/me/accounts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.subaccounts.listSubAccounts();
using SumUp;


var client = new SumUpClient();


var result = await client.Subaccounts.ListSubAccountsAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.subaccounts().listSubAccounts();
from sumup import Sumup


client = Sumup()


result = client.subaccounts.list_sub_accounts()
client := sumup.NewClient()


result, err := client.Subaccounts.ListSubAccounts(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().list_sub_accounts(sumup::ListSubAccountsParams{
    query: Some("query".to_string()),
    include_primary: Some("include_primary".to_string()),
}).await;
List operators response
[
  {
    "id": 0,
    "username": "operator1@mydomain.com",
    "nickname": "Operator 1",
    "disabled": false,
    "created_at": "",
    "updated_at": "",
    "permissions": {
      "create_moto_payments": false,
      "create_referral": false,
      "full_transaction_history_view": false,
      "refund_transactions": false,
      "admin": false
    },
    "account_type": ""
  }
]
Subaccounts

Create an operatorDeprecated

Creates new operator for currently authorized users' merchant.

Required permissions: members_update

Body Parameters

  • username string email required
    Example: "operator1@mydomain.com"
  • password string min length: 8 required
    Example: "correct horse batter staple"
  • nickname string
    Example: "Operator 1"
  • permissions object
     Show attributes
     Close
    Attributes
    • create_moto_payments boolean
    • create_referral boolean
    • full_transaction_history_view boolean
    • refund_transactions boolean

Response 200

  • id integer required
  • username string required
    Example: "operator1@mydomain.com"
  • nickname string nullable
    Example: "Operator 1"
  • disabled boolean required
  • created_at string date-time required

    The timestamp of when the operator was created.

  • updated_at string date-time required

    The timestamp of when the operator was last updated.

  • permissions object required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean required
    • create_referral boolean required
    • full_transaction_history_view boolean required
    • refund_transactions boolean required
    • admin boolean required
  • account_type string required
    Options:  operator normal
POST /v0.1/me/accounts 
curl https://api.sumup.com/v0.1/me/accounts \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "username": "operator1@mydomain.com",
    "password": "correct horse batter staple"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.subaccounts.createSubAccount({
  username: "operator1@mydomain.com",
  password: "correct horse batter staple",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Subaccounts.CreateSubAccountAsync(
    new CreateSubAccountBody
    {
        Username = "operator1@mydomain.com",
        Password = "correct horse batter staple",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.subaccounts().createSubAccount(
  CreateSubAccountBody.builder()
    .username("operator1@mydomain.com")
    .password("correct horse batter staple")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.subaccounts.create_sub_account(CreateSubAccountBody(
  username="operator1@mydomain.com",
  password="correct horse batter staple",
))
client := sumup.NewClient()


result, err := client.Subaccounts.CreateSubAccount(context.Background(), subaccounts.CreateSubAccountBody{
  Username: "operator1@mydomain.com",
  Password: "correct horse batter staple",
})
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().create_sub_account(sumup::CreateSubAccountBody{
  username: "operator1@mydomain.com".to_string(),
  password: "correct horse batter staple".to_string(),
}).await;
Create an operator response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

Retrieve an operatorDeprecated

Returns specific operator.

Required permissions: members_view

Path Parameters

  • operator_id integer required

    The unique identifier for the operator.

Response 200

  • id integer required
  • username string required
    Example: "operator1@mydomain.com"
  • nickname string nullable
    Example: "Operator 1"
  • disabled boolean required
  • created_at string date-time required

    The timestamp of when the operator was created.

  • updated_at string date-time required

    The timestamp of when the operator was last updated.

  • permissions object required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean required
    • create_referral boolean required
    • full_transaction_history_view boolean required
    • refund_transactions boolean required
    • admin boolean required
  • account_type string required
    Options:  operator normal
GET /v0.1/me/accounts/{operator_id} 
curl https://api.sumup.com/v0.1/me/accounts/{operator_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.subaccounts.compatGetOperator("operator_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Subaccounts.CompatGetOperatorAsync(
    "operator_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.subaccounts().compatGetOperator(
  "operator_id"
);
from sumup import Sumup


client = Sumup()


result = client.subaccounts.compat_get_operator("operator_id")
client := sumup.NewClient()


result, err := client.Subaccounts.CompatGetOperator(context.Background(), "operator_id")
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().compat_get_operator("operator_id").await;
Retrieve an operator response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

Update an operatorDeprecated

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

Required permissions: members_update

Path Parameters

  • operator_id integer required

    The unique identifier for the operator.

Body Parameters

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

Response 200

  • id integer required
  • username string required
    Example: "operator1@mydomain.com"
  • nickname string nullable
    Example: "Operator 1"
  • disabled boolean required
  • created_at string date-time required

    The timestamp of when the operator was created.

  • updated_at string date-time required

    The timestamp of when the operator was last updated.

  • permissions object required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean required
    • create_referral boolean required
    • full_transaction_history_view boolean required
    • refund_transactions boolean required
    • admin boolean required
  • account_type string required
    Options:  operator normal
PUT /v0.1/me/accounts/{operator_id} 
curl https://api.sumup.com/v0.1/me/accounts/{operator_id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{}'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.subaccounts.updateSubAccount("operator_id", {


});
using SumUp;


var client = new SumUpClient();


var result = await client.Subaccounts.UpdateSubAccountAsync(
    "operator_id",
    new UpdateSubAccountBody
    {


    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.subaccounts().updateSubAccount(
  "operator_id",
  UpdateSubAccountBody.builder()


    .build()
);
from sumup import Sumup


client = Sumup()


result = client.subaccounts.update_sub_account("operator_id", UpdateSubAccountBody(


))
client := sumup.NewClient()


result, err := client.Subaccounts.UpdateSubAccount(context.Background(), "operator_id", subaccounts.UpdateSubAccountBody{


})
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().update_sub_account("operator_id", sumup::UpdateSubAccountBody{}).await;
Update an operator response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}
Subaccounts

Disable an operator.Deprecated

Disable the specified operator for the merchant account.

Required permissions: members_delete

Path Parameters

  • operator_id integer required

    The unique identifier for the operator.

Response 200

  • id integer required
  • username string required
    Example: "operator1@mydomain.com"
  • nickname string nullable
    Example: "Operator 1"
  • disabled boolean required
  • created_at string date-time required

    The timestamp of when the operator was created.

  • updated_at string date-time required

    The timestamp of when the operator was last updated.

  • permissions object required

    Permissions assigned to an operator or user.

     Show attributes
     Close
    Attributes
    • create_moto_payments boolean required
    • create_referral boolean required
    • full_transaction_history_view boolean required
    • refund_transactions boolean required
    • admin boolean required
  • account_type string required
    Options:  operator normal
DELETE /v0.1/me/accounts/{operator_id} 
curl https://api.sumup.com/v0.1/me/accounts/{operator_id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.subaccounts.deactivateSubAccount("operator_id");
using SumUp;


var client = new SumUpClient();


var result = await client.Subaccounts.DeactivateSubAccountAsync(
    "operator_id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.subaccounts().deactivateSubAccount(
  "operator_id"
);
from sumup import Sumup


client = Sumup()


result = client.subaccounts.deactivate_sub_account("operator_id")
client := sumup.NewClient()


result, err := client.Subaccounts.DeactivateSubAccount(context.Background(), "operator_id")
use sumup::Client;


let client = Client::default();


let result = client.subaccounts().deactivate_sub_account("operator_id").await;
Disable an operator. response
{
  "id": 0,
  "username": "operator1@mydomain.com",
  "nickname": "Operator 1",
  "disabled": false,
  "created_at": "",
  "updated_at": "",
  "permissions": {
    "create_moto_payments": false,
    "create_referral": false,
    "full_transaction_history_view": false,
    "refund_transactions": false,
    "admin": false
  },
  "account_type": ""
}