Merchants | SumUp Developer

Merchant account represents a single business entity at SumUp.

The Merchant object

merchant_codestringRead only
Short unique identifier for the merchant.

Example: "MK01A8C2"
organization_idstring
ID of the organization the merchant belongs to (if any).

Example: "G0UZPVAX"
business_typestring
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
companyobjectdocs
Information about the company or business. This is legal information that is used for verification.
Show attributes
Close
Attributes
- namestringmin length: 1, max length: 150
  The company's legal name.
  
  Example: "Gin & Doughnuts Bar GmbH"
- merchant_category_codestringpattern: ^[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_typestringmin length: 4, max 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.
- addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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_addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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[]CompanyIdentifier
  A list of country-specific company identifiers.
  
  Show attributes
  Close
  Attributes
  refstringrequired
  The unique reference for the company identifier type as defined in the country SDK.
  
  valuestringrequiredmax length: 100
  The company identifier value.
- phone_numberstringmax length: 16
  A publicly available phone number in E.164 format.
  
  Example: "+420123456789"
- websitestringmax length: 255
  HTTP(S) URL of the company's website.
- attributesobject
  Object attributes that are modifiable only by SumUp applications.
  
  Example: {}
countrystringmin length: 2, max length: 2, pattern: ^[A-Z]{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_profileobject
Business information about the merchant. This information will be visible to the merchant's customers.
Show attributes
Close
Attributes
- namestringmin length: 1, max length: 150
  The customer-facing business name.
  
  Example: "Example Coffee"
- dynamic_descriptorstringmin length: 1, max length: 30, pattern: ^[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).
  
  Example: "Example Coffee"
- websitestringmax length: 255
  The business's publicly available website.
  
  Example: "https://example.com"
- emailstringmax length: 255
  A publicly available email address.
  
  Example: "contact@example.com"
- phone_numberstringmax length: 16
  A publicly available phone number in E.164 format.
  
  Example: "+420123456789"
- addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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"}
- brandingobject
  Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.
  
  Show attributes
  Close
  Attributes
  iconstringformat: uri
  An icon for the merchant. Must be square.
  
  logostringformat: 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.
  
  herostringformat: uri
  Data-URL encoded hero image for the merchant business.
  
  primary_colorstring
  A hex color value representing the primary branding color of this merchant (your brand color).
  
  primary_color_fgstring
  A hex color value representing the color of the text displayed on branding color of this merchant.
  
  secondary_colorstring
  A hex color value representing the secondary branding color of this merchant (accent color used for buttons).
  
  secondary_color_fgstring
  A hex color value representing the color of the text displayed on secondary branding color of this merchant.
  
  background_colorstring
  A hex color value representing the preferred background color of this merchant.
avatarstringformat: uri
A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see merchant.business_profile.branding.
aliasstring
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_currencystringmin length: 3, max length: 3, Read only
Three-letter ISO currency code representing the default currency for the account.

Example: "EUR"
default_localestringmin length: 2, max 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"
sandboxboolean
True if the merchant is a sandbox for testing.
metaobject
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.

Example: {}
classicobject
Show attributes
Close
Attributes
- idintegerrequireddeprecated
  Classic (serial) merchant ID.
  
  Example: 1234
versionstring
The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.
change_statusstringRead 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_atstringformat: date-time, Read only
The date and time when the resource was created. This is a string as defined in RFC 3339, section 5.6.
updated_atstringformat: date-time, Read only
The date and time when the resource was last updated. This is a string as defined in RFC 3339, section 5.6.

1
{
2
  "merchant_code": "MK01A8C2",
3
  "organization_id": "G0UZPVAX",
4
  "business_type": null,
5
  "company": {
6
    "name": "Gin & Doughnuts Bar GmbH",
7
    "merchant_category_code": "1532",
8
    "legal_type": "de.freiberufler",
9
    "address": {
10
      "street_address": [
11
        "Paul-Linke-Ufer 39-40",
12
        "2. Hinterhof"
13
      ],
14
      "post_code": "10999",
15
      "city": "Berlin",
16
      "country": "DE"
17
    },
18
    "trading_address": {
19
      "street_address": [
20
        "Paul-Linke-Ufer 39-40",
21
        "2. Hinterhof"
22
      ],
23
      "post_code": "10999",
24
      "city": "Berlin",
25
      "country": "DE"
26
    },
27
    "identifiers": [
28
      {
29
        "ref": "de.gmbh",
30
        "value": "HRB 123456"
31
      }
32
    ],
33
    "phone_number": "+420123456789",
34
    "website": "https://www.sumup.com",
35
    "attributes": {}
36
  },
37
  "country": "BR",
38
  "business_profile": {
39
    "name": "Example Coffee",
40
    "dynamic_descriptor": "Example Coffee",
41
    "website": "https://example.com",
42
    "email": "contact@example.com",
43
    "phone_number": "+420123456789",
44
    "address": {
45
      "street_address": [
46
        "Paul-Linke-Ufer 39-40",
47
        "2. Hinterhof"
48
      ],
49
      "post_code": "10999",
50
      "city": "Berlin",
51
      "country": "DE"
52
    },
53
    "branding": {
54
      "icon": null,
55
      "logo": null,
56
      "hero": null,
57
      "primary_color": "#FF4B3A",
58
      "primary_color_fg": "#FF4B3A",
59
      "secondary_color": "#FF4B3A",
60
      "secondary_color_fg": "#FF4B3A",
61
      "background_color": "#FF4B3A"
62
    }
63
  },
64
  "avatar": null,
65
  "alias": null,
66
  "default_currency": "EUR",
67
  "default_locale": "de-DE",
68
  "sandbox": null,
69
  "meta": {},
70
  "classic": {
71
    "id": 1234
72
  },
73
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
74
  "change_status": null,
75
  "created_at": "2021-08-31T12:00:00Z",
76
  "updated_at": "2021-08-31T12:00:00Z"
77
}

Merchants

Retrieve a Merchant

GET/v1/merchants/{merchant_code}

Retrieve a merchant.

Required scopes:user.profileuser.profile_readonly

Required permissions:merchant_read

Path Parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"

Query Parameters

versionstring
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

Returns a Merchant for a valid identifier. See Merchant object.

merchant_codestringRead only
Short unique identifier for the merchant.

Example: "MK01A8C2"
organization_idstring
ID of the organization the merchant belongs to (if any).

Example: "G0UZPVAX"
business_typestring
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
companyobjectdocs
Information about the company or business. This is legal information that is used for verification.
Show attributes
Close
Attributes
- namestringmin length: 1, max length: 150
  The company's legal name.
  
  Example: "Gin & Doughnuts Bar GmbH"
- merchant_category_codestringpattern: ^[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_typestringmin length: 4, max 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.
- addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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_addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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[]CompanyIdentifier
  A list of country-specific company identifiers.
  
  Show attributes
  Close
  Attributes
  refstringrequired
  The unique reference for the company identifier type as defined in the country SDK.
  
  valuestringrequiredmax length: 100
  The company identifier value.
- phone_numberstringmax length: 16
  A publicly available phone number in E.164 format.
  
  Example: "+420123456789"
- websitestringmax length: 255
  HTTP(S) URL of the company's website.
- attributesobject
  Object attributes that are modifiable only by SumUp applications.
  
  Example: {}
countrystringmin length: 2, max length: 2, pattern: ^[A-Z]{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_profileobject
Business information about the merchant. This information will be visible to the merchant's customers.
Show attributes
Close
Attributes
- namestringmin length: 1, max length: 150
  The customer-facing business name.
  
  Example: "Example Coffee"
- dynamic_descriptorstringmin length: 1, max length: 30, pattern: ^[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).
  
  Example: "Example Coffee"
- websitestringmax length: 255
  The business's publicly available website.
  
  Example: "https://example.com"
- emailstringmax length: 255
  A publicly available email address.
  
  Example: "contact@example.com"
- phone_numberstringmax length: 16
  A publicly available phone number in E.164 format.
  
  Example: "+420123456789"
- addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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"}
- brandingobject
  Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.
  
  Show attributes
  Close
  Attributes
  iconstringformat: uri
  An icon for the merchant. Must be square.
  
  logostringformat: 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.
  
  herostringformat: uri
  Data-URL encoded hero image for the merchant business.
  
  primary_colorstring
  A hex color value representing the primary branding color of this merchant (your brand color).
  
  primary_color_fgstring
  A hex color value representing the color of the text displayed on branding color of this merchant.
  
  secondary_colorstring
  A hex color value representing the secondary branding color of this merchant (accent color used for buttons).
  
  secondary_color_fgstring
  A hex color value representing the color of the text displayed on secondary branding color of this merchant.
  
  background_colorstring
  A hex color value representing the preferred background color of this merchant.
avatarstringformat: uri
A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see merchant.business_profile.branding.
aliasstring
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_currencystringmin length: 3, max length: 3, Read only
Three-letter ISO currency code representing the default currency for the account.

Example: "EUR"
default_localestringmin length: 2, max 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"
sandboxboolean
True if the merchant is a sandbox for testing.
metaobject
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.

Example: {}
classicobject
Show attributes
Close
Attributes
- idintegerrequireddeprecated
  Classic (serial) merchant ID.
  
  Example: 1234
versionstring
The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.
change_statusstringRead 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_atstringformat: date-time, Read only
The date and time when the resource was created. This is a string as defined in RFC 3339, section 5.6.
updated_atstringformat: date-time, Read only
The date and time when the resource was last updated. This is a string as defined in RFC 3339, section 5.6.

1
curl https://api.sumup.com/v1/merchants/{merchant_code} \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.merchants.get("MK10CL2A");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Merchants.GetAsync(
6
    "MK10CL2A"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.merchants().getMerchant(
6
  "MK10CL2A"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.merchants.get("MK10CL2A")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->merchants->get('MK10CL2A');

1
client := sumup.NewClient()
2

3
result, err := client.Merchants.Get(context.Background(), "MK10CL2A")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.merchants().get("MK10CL2A", sumup::GetMerchantParams{
6
    version: Some("version".to_string()),
7
}).await;

1
{
2
  "merchant_code": "MK01A8C2",
3
  "organization_id": "G0UZPVAX",
4
  "business_type": null,
5
  "company": {
6
    "name": "Gin & Doughnuts Bar GmbH",
7
    "merchant_category_code": "1532",
8
    "legal_type": "de.freiberufler",
9
    "address": {
10
      "street_address": [
11
        "Paul-Linke-Ufer 39-40",
12
        "2. Hinterhof"
13
      ],
14
      "post_code": "10999",
15
      "city": "Berlin",
16
      "country": "DE"
17
    },
18
    "trading_address": {
19
      "street_address": [
20
        "Paul-Linke-Ufer 39-40",
21
        "2. Hinterhof"
22
      ],
23
      "post_code": "10999",
24
      "city": "Berlin",
25
      "country": "DE"
26
    },
27
    "identifiers": [
28
      {
29
        "ref": "de.gmbh",
30
        "value": "HRB 123456"
31
      }
32
    ],
33
    "phone_number": "+420123456789",
34
    "website": "https://www.sumup.com",
35
    "attributes": {}
36
  },
37
  "country": "BR",
38
  "business_profile": {
39
    "name": "Example Coffee",
40
    "dynamic_descriptor": "Example Coffee",
41
    "website": "https://example.com",
42
    "email": "contact@example.com",
43
    "phone_number": "+420123456789",
44
    "address": {
45
      "street_address": [
46
        "Paul-Linke-Ufer 39-40",
47
        "2. Hinterhof"
48
      ],
49
      "post_code": "10999",
50
      "city": "Berlin",
51
      "country": "DE"
52
    },
53
    "branding": {
54
      "icon": null,
55
      "logo": null,
56
      "hero": null,
57
      "primary_color": "#FF4B3A",
58
      "primary_color_fg": "#FF4B3A",
59
      "secondary_color": "#FF4B3A",
60
      "secondary_color_fg": "#FF4B3A",
61
      "background_color": "#FF4B3A"
62
    }
63
  },
64
  "avatar": null,
65
  "alias": null,
66
  "default_currency": "EUR",
67
  "default_locale": "de-DE",
68
  "sandbox": null,
69
  "meta": {},
70
  "classic": {
71
    "id": 1234
72
  },
73
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
74
  "change_status": null,
75
  "created_at": "2021-08-31T12:00:00Z",
76
  "updated_at": "2021-08-31T12:00:00Z"
77
}

Error 404

Content-Type: application/problem+json

The requested Merchant does not exist.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Error 404

1
{
2
  "type": "https://developer.sumup.com/problem/not-found",
3
  "title": "Requested resource couldn't be found.",
4
  "status": 404,
5
  "detail": "The requested resource doesn't exist or does not belong to you.",
6
  "instance": null
7
}

Merchants

List Persons

GET/v1/merchants/{merchant_code}/persons

Returns a list of persons related to the merchant.

Required scopes:user.profileuser.profile_readonly

Required permissions:persons_read

Path Parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"

Query Parameters

versionstring
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

Returns a list of persons for a valid merchant identifier.

items[]Personrequired
Show attributes
Close
Attributes
- idstringRead only
  The unique identifier for the person. This is a typeid.
- user_idstring
  A corresponding identity user ID for the person, if they have a user account.
- birthdatestringformat: 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_namestringmax length: 60
  The first name(s) of the individual.
  
  Example: "James Herrald"
- family_namestringmax length: 60
  The last name(s) of the individual.
  
  Example: "Bond"
- middle_namestringmax 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_numberstringmax length: 16
  A publicly available phone number in E.164 format.
  
  Example: "+420123456789"
- relationships[]stringmin items: 1, max 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.
- ownershipobject
  Show attributes
  Close
  Attributes
  shareintegerrequiredminimum: 25000, maximum: 100000
  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
- addressobjectdocs
  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[]stringmax items: 2
  The first line of the address.
  
  post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
  citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
  provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstringmax length: 60
  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"
  statestringmax length: 60
  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"
  neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestringmax length: 60
  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"
  departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystringmax length: 60
  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"
  districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestringmax length: 10
  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[]PersonalIdentifiermax items: 32
  A list of country-specific personal identifiers.
  
  Show attributes
  Close
  Attributes
  refstringrequiredmax length: 32
  The unique reference for the personal identifier type.
  
  Example: "br.cpf"
  valuestringrequiredmax length: 128
  The company identifier value.
  
  Example: "847.060.136-90"
- citizenshipstringmin length: 2, max length: 2, pattern: ^[A-Z]{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"
- nationalitystringnullable
  The persons nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard.
- country_of_residencestringmin length: 2, max length: 2, nullable
  An ISO3166-1 alpha-2 country code representing the country where the person resides.
- versionstring
  The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.
- change_statusstringRead 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.

1
curl https://api.sumup.com/v1/merchants/{merchant_code}/persons \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.merchants.listPersons("MK10CL2A");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Merchants.ListPersonsAsync(
6
    "MK10CL2A"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.merchants().listPersons(
6
  "MK10CL2A"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.merchants.list_persons("MK10CL2A")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->merchants->listPersons('MK10CL2A');

1
client := sumup.NewClient()
2

3
result, err := client.Merchants.ListPersons(context.Background(), "MK10CL2A")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.merchants().list_persons("MK10CL2A", sumup::ListPersonsParams{
6
    version: Some("version".to_string()),
7
}).await;

1
{
2
  "items": [
3
    {
4
      "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
5
      "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
6
      "birthdate": "1980-01-12",
7
      "given_name": "James Herrald",
8
      "family_name": "Bond",
9
      "middle_name": "Maria Sophie",
10
      "phone_number": "+420123456789",
11
      "relationships": [
12
        "representative"
13
      ],
14
      "ownership": {
15
        "share": 50000
16
      },
17
      "address": {
18
        "street_address": [
19
          "Paul-Linke-Ufer 39-40",
20
          "2. Hinterhof"
21
        ],
22
        "post_code": "10999",
23
        "city": "Berlin",
24
        "country": "DE"
25
      },
26
      "identifiers": [
27
        {
28
          "ref": "br.cpf",
29
          "value": "847.060.136-90"
30
        }
31
      ],
32
      "citizenship": "BR",
33
      "nationality": null,
34
      "country_of_residence": null,
35
      "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
36
      "change_status": null
37
    }
38
  ]
39
}

Error 404

Content-Type: application/problem+json

The requested Merchant does not exist.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Error 404

1
{
2
  "type": "https://developer.sumup.com/problem/not-found",
3
  "title": "Requested resource couldn't be found.",
4
  "status": 404,
5
  "detail": "The requested resource doesn't exist or does not belong to you.",
6
  "instance": null
7
}

Merchants

Retrieve a Person

GET/v1/merchants/{merchant_code}/persons/{person_id}

Returns a single person related to the merchant.

Required scopes:user.profileuser.profile_readonly

Required permissions:persons_read

Path Parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"
person_idstringrequired
Person ID

Example: "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z"

Query Parameters

versionstring
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

Returns a Person for a valid identifier.

idstringRead only
The unique identifier for the person. This is a typeid.
user_idstring
A corresponding identity user ID for the person, if they have a user account.
birthdatestringformat: 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_namestringmax length: 60
The first name(s) of the individual.

Example: "James Herrald"
family_namestringmax length: 60
The last name(s) of the individual.

Example: "Bond"
middle_namestringmax 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_numberstringmax length: 16
A publicly available phone number in E.164 format.

Example: "+420123456789"
relationships[]stringmin items: 1, max 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.
ownershipobject
Show attributes
Close
Attributes
- shareintegerrequiredminimum: 25000, maximum: 100000
  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
addressobjectdocs
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[]stringmax items: 2
  The first line of the address.
- post_codestringmax length: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
- countrystringrequiredmin length: 2, max length: 2, pattern: ^[A-Z]{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"
- citystringmax length: 60
  The city of the address.
  
  Example: "Berlin"
- provincestringmax length: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
- regionstringmax length: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
- countystringmax length: 60
  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_communitystringmax length: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
- post_townstringmax length: 60
  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"
- statestringmax length: 60
  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"
- neighborhoodstringmax length: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
- communestringmax length: 60
  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"
- departmentstringmax length: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
- municipalitystringmax length: 60
  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"
- districtstringmax length: 60
  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_codestringmax length: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
- eircodestringmax length: 10
  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[]PersonalIdentifiermax items: 32
A list of country-specific personal identifiers.
Show attributes
Close
Attributes
- refstringrequiredmax length: 32
  The unique reference for the personal identifier type.
  
  Example: "br.cpf"
- valuestringrequiredmax length: 128
  The company identifier value.
  
  Example: "847.060.136-90"
citizenshipstringmin length: 2, max length: 2, pattern: ^[A-Z]{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"
nationalitystringnullable
The persons nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard.
country_of_residencestringmin length: 2, max length: 2, nullable
An ISO3166-1 alpha-2 country code representing the country where the person resides.
versionstring
The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.
change_statusstringRead 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.

1
curl https://api.sumup.com/v1/merchants/{merchant_code}/persons/{person_id} \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.merchants.getPerson("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Merchants.GetPersonAsync(
6
    "MK10CL2A",
7
    "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z"
8
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.merchants().getPerson(
6
  "MK10CL2A",
7
  "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z"
8
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.merchants.get_person("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->merchants->getPerson('MK10CL2A', 'pers_5AKFHN2KSK8D3TS79DJE3P3A2Z');

1
client := sumup.NewClient()
2

3
result, err := client.Merchants.GetPerson(context.Background(), "MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.merchants().get_person("MK10CL2A", "pers_5AKFHN2KSK8D3TS79DJE3P3A2Z", sumup::GetPersonParams{
6
    version: Some("version".to_string()),
7
}).await;

1
{
2
  "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
3
  "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
4
  "birthdate": "1980-01-12",
5
  "given_name": "James Herrald",
6
  "family_name": "Bond",
7
  "middle_name": "Maria Sophie",
8
  "phone_number": "+420123456789",
9
  "relationships": [
10
    "representative"
11
  ],
12
  "ownership": {
13
    "share": 50000
14
  },
15
  "address": {
16
    "street_address": [
17
      "Paul-Linke-Ufer 39-40",
18
      "2. Hinterhof"
19
    ],
20
    "post_code": "10999",
21
    "city": "Berlin",
22
    "country": "DE"
23
  },
24
  "identifiers": [
25
    {
26
      "ref": "br.cpf",
27
      "value": "847.060.136-90"
28
    }
29
  ],
30
  "citizenship": "BR",
31
  "nationality": null,
32
  "country_of_residence": null,
33
  "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
34
  "change_status": null
35
}

Error 404

Content-Type: application/problem+json

The requested Person does not exist.

typestringrequiredformat: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Error 404

1
{
2
  "type": "https://developer.sumup.com/problem/not-found",
3
  "title": "Requested resource couldn't be found.",
4
  "status": 404,
5
  "detail": "The requested resource doesn't exist or does not belong to you.",
6
  "instance": null
7
}