--- title: "Merchant" image: "https://developer.sumup.com/og/index.png" --- > Documentation Index > Fetch the complete documentation index at: https://developer.sumup.com/llms.txt > Use this file to discover all available pages before exploring further. Path: SumUp REST API ## Fields - `merchant_code` (`Merchant.merchant_code`; string, required) — Short unique identifier for the merchant. - example `"MK01A8C2"` - `country` (`Merchant.country`; string, required) — An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-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. - minLength 2; maxLength 2; pattern `^[A-Z]{2}$`; example `"BR"` - `default_currency` (`Merchant.default_currency`; string, required) — Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account. - minLength 3; maxLength 3; example `"EUR"` - `default_locale` (`Merchant.default_locale`; string, required) — Merchant's default locale, represented as a BCP47 [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646) language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1](https://www.iso.org/iso-639-language-code) language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1](https://www.iso.org/iso-3166-country-codes.html) 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. - minLength 2; maxLength 5; example `"de-DE"` - `created_at` (`Merchant.created_at`; string, required) — The date and time when the resource was created. This is a string as defined in [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). - format `date-time`; example `"2021-08-31T12:00:00Z"` - `updated_at` (`Merchant.updated_at`; string, required) — The date and time when the resource was last updated. This is a string as defined in [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). - format `date-time`; example `"2021-08-31T12:00:00Z"` - `organization_id` (`Merchant.organization_id`; string, optional) — ID of the organization the merchant belongs to (if any). - example `"G0UZPVAX"` - `business_type` (`Merchant.business_type`; string, optional) — 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` (`Merchant.company`; object, optional) — Information about the company or business. This is legal information that is used for verification. - `name` (`Merchant.company.name`; string, optional) — The company's legal name. - minLength 1; maxLength 150; example `"Gin & Doughnuts Bar GmbH"` - `merchant_category_code` (`Merchant.company.merchant_category_code`; string, optional) — The merchant category code for the account as specified by [ISO18245](https://www.iso.org/standard/33365.html). MCCs are used to classify businesses based on the goods or services they provide. - pattern `^[0-9]{4}$`; example `"1532"` - `legal_type` (`Merchant.company.legal_type`; string, optional) — 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. - minLength 4; maxLength 64; pattern `^[a-z]{2}\.[a-z_]+$`; example `"de.freiberufler"` - `address` (`Merchant.company.address`; object, optional) — 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. - example `{"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}` - `country` (`Merchant.company.address.country`; string, required) — An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-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. - minLength 2; maxLength 2; pattern `^[A-Z]{2}$`; example `"BR"` - `street_address` (`Merchant.company.address.street_address`; array, optional) - maxLength 100; example `["Paul-Linke-Ufer 39-40","2. Hinterhof"]` - `post_code` (`Merchant.company.address.post_code`; string, optional) — The postal code (aka. zip code) of the address. - maxLength 10; example `"10999"` - `city` (`Merchant.company.address.city`; string, optional) — The city of the address. - maxLength 60; example `"Berlin"` - `province` (`Merchant.company.address.province`; string, optional) — The province where the address is located. This may not be relevant in some countries. - maxLength 60; example `"Berlin"` - `region` (`Merchant.company.address.region`; string, optional) — The region where the address is located. This may not be relevant in some countries. - maxLength 60; example `"Baden Wuerttemberg"` - `county` (`Merchant.company.address.county`; string, optional) — 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. - maxLength 60; example `"Dublin County"` - `autonomous_community` (`Merchant.company.address.autonomous_community`; string, optional) — In Spain, an autonomous community is the first sub-national level of political and administrative division. - maxLength 60; example `"Catalonia"` - `post_town` (`Merchant.company.address.post_town`; string, optional) — 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. - maxLength 60; example `"London"` - `state` (`Merchant.company.address.state`; string, optional) — 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. - maxLength 60; example `"California"` - `neighborhood` (`Merchant.company.address.neighborhood`; string, optional) — Locality level of the address. Used in countries such as Brazil or Chile. - maxLength 60; example `"Copacabana"` - `commune` (`Merchant.company.address.commune`; string, optional) — 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. - maxLength 60; example `"Providencia"` - `department` (`Merchant.company.address.department`; string, optional) — A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia. - maxLength 60; example `"Antioquia"` - `municipality` (`Merchant.company.address.municipality`; string, optional) — 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. - maxLength 60; example `"Medellín"` - `district` (`Merchant.company.address.district`; string, optional) — A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal. - maxLength 60; example `"Lisbon District"` - `zip_code` (`Merchant.company.address.zip_code`; string, optional) — A US system of postal codes used by the United States Postal Service (USPS). - maxLength 10; example `"94103"` - `eircode` (`Merchant.company.address.eircode`; string, optional) — A postal address in Ireland. - maxLength 10; example `"D02 X285"` - `trading_address` (`Merchant.company.trading_address`; object, optional) — 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. - example `{"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}` - `country` (`Merchant.company.trading_address.country`; string, required) — An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-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. - minLength 2; maxLength 2; pattern `^[A-Z]{2}$`; example `"BR"` - `street_address` (`Merchant.company.trading_address.street_address`; array, optional) - maxLength 100; example `["Paul-Linke-Ufer 39-40","2. Hinterhof"]` - `post_code` (`Merchant.company.trading_address.post_code`; string, optional) — The postal code (aka. zip code) of the address. - maxLength 10; example `"10999"` - `city` (`Merchant.company.trading_address.city`; string, optional) — The city of the address. - maxLength 60; example `"Berlin"` - `province` (`Merchant.company.trading_address.province`; string, optional) — The province where the address is located. This may not be relevant in some countries. - maxLength 60; example `"Berlin"` - `region` (`Merchant.company.trading_address.region`; string, optional) — The region where the address is located. This may not be relevant in some countries. - maxLength 60; example `"Baden Wuerttemberg"` - `county` (`Merchant.company.trading_address.county`; string, optional) — 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. - maxLength 60; example `"Dublin County"` - `autonomous_community` (`Merchant.company.trading_address.autonomous_community`; string, optional) — In Spain, an autonomous community is the first sub-national level of political and administrative division. - maxLength 60; example `"Catalonia"` - `post_town` (`Merchant.company.trading_address.post_town`; string, optional) — 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. - maxLength 60; example `"London"` - `state` (`Merchant.company.trading_address.state`; string, optional) — 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. - maxLength 60; example `"California"` - `neighborhood` (`Merchant.company.trading_address.neighborhood`; string, optional) — Locality level of the address. Used in countries such as Brazil or Chile. - maxLength 60; example `"Copacabana"` - `commune` (`Merchant.company.trading_address.commune`; string, optional) — 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. - maxLength 60; example `"Providencia"` - `department` (`Merchant.company.trading_address.department`; string, optional) — A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia. - maxLength 60; example `"Antioquia"` - `municipality` (`Merchant.company.trading_address.municipality`; string, optional) — 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. - maxLength 60; example `"Medellín"` - `district` (`Merchant.company.trading_address.district`; string, optional) — A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal. - maxLength 60; example `"Lisbon District"` - `zip_code` (`Merchant.company.trading_address.zip_code`; string, optional) — A US system of postal codes used by the United States Postal Service (USPS). - maxLength 10; example `"94103"` - `eircode` (`Merchant.company.trading_address.eircode`; string, optional) — A postal address in Ireland. - maxLength 10; example `"D02 X285"` - `identifiers` (`Merchant.company.identifiers`; array, optional) — A list of country-specific company identifiers. - `ref` (`Merchant.company.identifiers.ref`; string, required) — The unique reference for the company identifier type as defined in the country SDK. - pattern `^[a-z]{2}\.[a-z_]+$`; example `"de.gmbh"` - `value` (`Merchant.company.identifiers.value`; string, required) — The company identifier value. - minLength 1; maxLength 100; example `"HRB 123456"` - `phone_number` (`Merchant.company.phone_number`; string, optional) — A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. - maxLength 16; example `"+420123456789"` - `website` (`Merchant.company.website`; string, optional) — HTTP(S) URL of the company's website. - minLength 1; maxLength 255; example `"https://www.sumup.com"` - `attributes` (`Merchant.company.attributes`; object, optional) — Object attributes that are modifiable only by SumUp applications. - example `{}` - `business_profile` (`Merchant.business_profile`; object, optional) — Business information about the merchant. This information will be visible to the merchant's customers. - `name` (`Merchant.business_profile.name`; string, optional) — The customer-facing business name. - minLength 1; maxLength 150; example `"Example Coffee"` - `dynamic_descriptor` (`Merchant.business_profile.dynamic_descriptor`; string, optional) — 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). - minLength 1; maxLength 30; pattern `^[a-zA-Z0-9 +'_.-]+$`; example `"Example Coffee"` - `website` (`Merchant.business_profile.website`; string, optional) — The business's publicly available website. - minLength 1; maxLength 255; example `"https://example.com"` - `email` (`Merchant.business_profile.email`; string, optional) — A publicly available email address. - minLength 1; maxLength 255; example `"contact@example.com"` - `phone_number` (`Merchant.business_profile.phone_number`; string, optional) — A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. - maxLength 16; example `"+420123456789"` - `address` (`Merchant.business_profile.address`; object, optional) — 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. - example `{"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}` - `country` (`Merchant.business_profile.address.country`; string, required) — An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-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. - minLength 2; maxLength 2; pattern `^[A-Z]{2}$`; example `"BR"` - `street_address` (`Merchant.business_profile.address.street_address`; array, optional) - maxLength 100; example `["Paul-Linke-Ufer 39-40","2. Hinterhof"]` - `post_code` (`Merchant.business_profile.address.post_code`; string, optional) — The postal code (aka. zip code) of the address. - maxLength 10; example `"10999"` - `city` (`Merchant.business_profile.address.city`; string, optional) — The city of the address. - maxLength 60; example `"Berlin"` - `province` (`Merchant.business_profile.address.province`; string, optional) — The province where the address is located. This may not be relevant in some countries. - maxLength 60; example `"Berlin"` - `region` (`Merchant.business_profile.address.region`; string, optional) — The region where the address is located. This may not be relevant in some countries. - maxLength 60; example `"Baden Wuerttemberg"` - `county` (`Merchant.business_profile.address.county`; string, optional) — 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. - maxLength 60; example `"Dublin County"` - `autonomous_community` (`Merchant.business_profile.address.autonomous_community`; string, optional) — In Spain, an autonomous community is the first sub-national level of political and administrative division. - maxLength 60; example `"Catalonia"` - `post_town` (`Merchant.business_profile.address.post_town`; string, optional) — 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. - maxLength 60; example `"London"` - `state` (`Merchant.business_profile.address.state`; string, optional) — 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. - maxLength 60; example `"California"` - `neighborhood` (`Merchant.business_profile.address.neighborhood`; string, optional) — Locality level of the address. Used in countries such as Brazil or Chile. - maxLength 60; example `"Copacabana"` - `commune` (`Merchant.business_profile.address.commune`; string, optional) — 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. - maxLength 60; example `"Providencia"` - `department` (`Merchant.business_profile.address.department`; string, optional) — A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia. - maxLength 60; example `"Antioquia"` - `municipality` (`Merchant.business_profile.address.municipality`; string, optional) — 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. - maxLength 60; example `"Medellín"` - `district` (`Merchant.business_profile.address.district`; string, optional) — A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal. - maxLength 60; example `"Lisbon District"` - `zip_code` (`Merchant.business_profile.address.zip_code`; string, optional) — A US system of postal codes used by the United States Postal Service (USPS). - maxLength 10; example `"94103"` - `eircode` (`Merchant.business_profile.address.eircode`; string, optional) — A postal address in Ireland. - maxLength 10; example `"D02 X285"` - `branding` (`Merchant.business_profile.branding`; object, optional) — Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products. - `footer_text` (`Merchant.business_profile.branding.footer_text`; string, optional) — Footer text rendered on receipts and other customer-facing products. - minLength 1; maxLength 500; example `"Thanks for shopping with us."` - `icon` (`Merchant.business_profile.branding.icon`; string, optional) — An icon for the merchant. Must be square. - format `uri` - `logo` (`Merchant.business_profile.branding.logo`; string, optional) — 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. - format `uri` - `hero` (`Merchant.business_profile.branding.hero`; string, optional) — Data-URL encoded hero image for the merchant business. - format `uri` - `primary_color` (`Merchant.business_profile.branding.primary_color`; string, optional) — A hex color value representing the primary branding color of this merchant (your brand color). - example `"#FF4B3A"` - `primary_color_fg` (`Merchant.business_profile.branding.primary_color_fg`; string, optional) — A hex color value representing the color of the text displayed on branding color of this merchant. - example `"#FF4B3A"` - `secondary_color` (`Merchant.business_profile.branding.secondary_color`; string, optional) — A hex color value representing the secondary branding color of this merchant (accent color used for buttons). - example `"#FF4B3A"` - `secondary_color_fg` (`Merchant.business_profile.branding.secondary_color_fg`; string, optional) — A hex color value representing the color of the text displayed on secondary branding color of this merchant. - example `"#FF4B3A"` - `background_color` (`Merchant.business_profile.branding.background_color`; string, optional) — A hex color value representing the preferred background color of this merchant. - example `"#FF4B3A"` - `avatar` (`Merchant.avatar`; string, optional) — A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see `merchant.business_profile.branding`. - format `uri` - `alias` (`Merchant.alias`; string, optional) — 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`. - `sandbox` (`Merchant.sandbox`; boolean, optional) — True if the merchant is a sandbox for testing. - example `false` - `meta` (`Merchant.meta`; map, optional) — 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 `{}` - `classic` (`Merchant.classic`; object, optional) - `id` (`Merchant.classic.id`; integer, required, deprecated) — Classic (serial) merchant ID. - format `int64`; example `1234` - `version` (`Merchant.version`; string, optional) — The version of the resource. The version reflects a specific change submitted to the API via one of the `PATCH` endpoints. - example `"chng_01HS0KG3MPVEVWW85E3KNXH55J"` - `change_status` (`Merchant.change_status`; string, optional) — 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. Source: https://developer.sumup.com/api/schemas/Merchant/index.md