openapi: 3.0.1 info: title: SumUp REST Checkouts Merchants API version: 1.0.0 description: 'SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status). 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](https://me.sumup.com/settings/developer). To use the sandbox when interacting with SumUp APIs [create an API](https://me.sumup.com/settings/api-keys) key and use it for [authentication](https://developer.sumup.com/api/authentication).' license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.sumup.com description: Production server tags: - name: Merchants description: Merchant account represents a single business entity at SumUp. x-core-objects: - $ref: '#/components/schemas/Merchant' paths: /v1/merchants/{merchant_code}: get: operationId: GetMerchant summary: Retrieve a Merchant description: Retrieve a merchant. parameters: - name: version in: query description: '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. ' schema: type: string examples: - latest - name: merchant_code in: path description: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A responses: '200': description: Returns a Merchant for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Merchant' '404': description: The requested Merchant does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Merchant documentation url: https://developer.sumup.com/tools/models/merchant security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: get x-permissions: - merchant_read x-scopes: - user.profile - user.profile_readonly /v1/merchants/{merchant_code}/persons: get: operationId: ListPersons summary: List Persons description: Returns a list of persons related to the merchant. parameters: - name: version in: query description: '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. ' schema: type: string examples: - latest - name: merchant_code in: path description: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A responses: '200': description: Returns a list of persons for a valid merchant identifier. content: application/json: schema: $ref: '#/components/schemas/ListPersonsResponseBody' '404': description: The requested Merchant does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Persons documentation url: https://developer.sumup.com/tools/models/merchant#persons security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: list_persons x-permissions: - persons_read x-scopes: - user.profile - user.profile_readonly /v1/merchants/{merchant_code}/persons/{person_id}: get: operationId: GetPerson summary: Retrieve a Person description: Returns a single person related to the merchant. parameters: - name: version in: query description: '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. ' schema: type: string examples: - latest - name: merchant_code in: path description: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - name: person_id in: path description: Person ID required: true schema: type: string example: pers_5AKFHN2KSK8D3TS79DJE3P3A2Z x-go-type: merchants.PersonID x-go-type-import: path: github.com/sumup/merchants/internal/domain/merchants responses: '200': description: Returns a Person for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Person' '404': description: The requested Person does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Persons documentation url: https://developer.sumup.com/tools/models/merchant#persons security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: get_person x-permissions: - persons_read x-scopes: - user.profile - user.profile_readonly components: schemas: Branding: description: Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products. type: object properties: icon: description: 'An icon for the merchant. Must be square. ' type: string format: uri logo: description: '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. ' type: string format: uri hero: description: 'Data-URL encoded hero image for the merchant business. ' type: string format: uri primary_color: description: 'A hex color value representing the primary branding color of this merchant (your brand color). ' type: string examples: - '#FF4B3A' - '#0072C6' - '#F68B20' primary_color_fg: description: 'A hex color value representing the color of the text displayed on branding color of this merchant. ' type: string examples: - '#FF4B3A' - '#0072C6' - '#F68B20' secondary_color: description: 'A hex color value representing the secondary branding color of this merchant (accent color used for buttons). ' type: string examples: - '#FF4B3A' - '#0072C6' - '#F68B20' secondary_color_fg: description: 'A hex color value representing the color of the text displayed on secondary branding color of this merchant. ' type: string examples: - '#FF4B3A' - '#0072C6' - '#F68B20' background_color: description: 'A hex color value representing the preferred background color of this merchant. ' type: string examples: - '#FF4B3A' - '#0072C6' - '#F68B20' Meta: description: '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.' type: object example: {} additionalProperties: type: string maxLength: 256 Version: description: 'The version of the resource. The version reflects a specific change submitted to the API via one of the `PATCH` endpoints. ' type: string examples: - chng_01HS0KG3MPVEVWW85E3KNXH55J CompanyIdentifier: type: object properties: ref: description: 'The unique reference for the company identifier type as defined in the country SDK. ' type: string examples: - de.gmbh value: description: 'The company identifier value. ' type: string examples: - HRB 123456 maxLength: 100 examples: - ref: de.gmbh value: HRB 123456 externalDocs: description: Company identifier documentation url: https://developer.sumup.com/tools/glossary/merchant#company-identifiers required: - ref - value CompanyIdentifiers: description: 'A list of country-specific company identifiers. ' type: array items: $ref: '#/components/schemas/CompanyIdentifier' Company: description: 'Information about the company or business. This is legal information that is used for verification. ' type: object properties: name: description: The company's legal name. type: string example: Gin & Doughnuts Bar GmbH maxLength: 150 minLength: 1 merchant_category_code: description: '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. ' type: string example: '1532' pattern: ^[0-9]{4}$ legal_type: $ref: '#/components/schemas/LegalType' address: $ref: '#/components/schemas/Address' trading_address: $ref: '#/components/schemas/Address' identifiers: $ref: '#/components/schemas/CompanyIdentifiers' phone_number: $ref: '#/components/schemas/PhoneNumber' website: description: 'HTTP(S) URL of the company''s website. ' type: string format: uri examples: - https://www.sumup.com maxLength: 255 nullable: true attributes: $ref: '#/components/schemas/Attributes' externalDocs: description: Company documentation url: https://developer.sumup.com/tools/glossary/merchant#company PhoneNumber: description: 'A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. ' type: string example: '+420123456789' maxLength: 16 ChangeStatus: description: '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. ' type: string readOnly: true Ownership: type: object properties: share: description: 'The percent of ownership shares held by the person expressed in percent mille (1/100000). Only persons with the relationship `owner` can have ownership. ' type: integer format: int32 example: 50000 maximum: 100000 minimum: 25000 required: - share Merchant: allOf: - type: object required: - merchant_code - country - default_currency - default_locale properties: merchant_code: description: Short unique identifier for the merchant. type: string example: MK01A8C2 readOnly: true organization_id: description: ID of the organization the merchant belongs to (if any). type: string example: G0UZPVAX business_type: description: '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 ' type: string company: $ref: '#/components/schemas/Company' country: $ref: '#/components/schemas/CountryCode' business_profile: $ref: '#/components/schemas/BusinessProfile' avatar: description: 'A user-facing small-format logo for use in dashboards and other user-facing applications. For customer-facing branding see `merchant.business_profile.branding`. ' type: string format: uri alias: description: '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`. ' type: string default_currency: description: 'Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account. ' type: string example: EUR maxLength: 3 minLength: 3 readOnly: true default_locale: description: '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.' type: string example: de-DE maxLength: 5 minLength: 2 sandbox: description: True if the merchant is a sandbox for testing. type: boolean example: false meta: $ref: '#/components/schemas/Meta' classic: $ref: '#/components/schemas/ClassicMerchantIdentifiers' version: $ref: '#/components/schemas/Version' change_status: $ref: '#/components/schemas/ChangeStatus' - $ref: '#/components/schemas/Timestamps' externalDocs: description: Merchant documentation url: https://developer.sumup.com/tools/glossary/merchant title: Merchant ListPersonsResponseBody: type: object properties: items: type: array items: $ref: '#/components/schemas/Person' required: - items Person: allOf: - $ref: '#/components/schemas/BasePerson' BasePerson: description: 'Base schema for a person associated with a merchant. This can be a legal representative, business owner (ultimate beneficial owner), or an officer. A legal representative is the person who registered the merchant with SumUp. They should always have a `user_id`. ' type: object properties: id: description: 'The unique identifier for the person. This is a [typeid](https://github.com/sumup/typeid). ' type: string examples: - pers_2EGQ057R6C8J791RVCG5NWAEAB readOnly: true user_id: description: 'A corresponding identity user ID for the person, if they have a user account. ' type: string examples: - ef263f37-8701-4181-9758-acddbb778ee9 birthdate: description: 'The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. ' type: string format: date example: 1980-01-12 given_name: description: The first name(s) of the individual. type: string example: James Herrald maxLength: 60 family_name: description: The last name(s) of the individual. type: string example: Bond maxLength: 60 middle_name: description: '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. ' type: string example: Maria Sophie maxLength: 60 phone_number: $ref: '#/components/schemas/PhoneNumber' relationships: description: '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`. ' type: array items: type: string description: '* `representative`: The person is the primary contact for SumUp and has full administrative power over the merchant account. * `owner`: The person is a business owner. If this value is set, the `ownership_percent` should be set as well. * `officer`: The person is an officer at the company. ' examples: - representative - owner - officer maxItems: 1 minItems: 1 ownership: $ref: '#/components/schemas/Ownership' address: $ref: '#/components/schemas/Address' identifiers: description: 'A list of country-specific personal identifiers. ' type: array items: $ref: '#/components/schemas/PersonalIdentifier' maxItems: 5 citizenship: $ref: '#/components/schemas/CountryCode' nationality: description: 'The persons nationality. May be an [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, but legacy data may not conform to this standard. ' type: string nullable: true country_of_residence: description: 'An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code representing the country where the person resides. ' type: string maxLength: 2 minLength: 2 nullable: true version: $ref: '#/components/schemas/Version' change_status: $ref: '#/components/schemas/ChangeStatus' externalDocs: description: Person documentation url: https://developer.sumup.com/tools/glossary/merchant#persons required: - id Address: description: '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.' type: object properties: street_address: type: array items: type: string description: The first line of the address. maxLength: 100 example: - Paul-Linke-Ufer 39-40 - 2. Hinterhof maxItems: 2 minItems: 1 post_code: description: 'The postal code (aka. zip code) of the address. ' type: string example: '10999' maxLength: 10 country: $ref: '#/components/schemas/CountryCode' city: description: 'The city of the address. ' type: string example: Berlin maxLength: 60 province: description: 'The province where the address is located. This may not be relevant in some countries. ' type: string example: Ontario maxLength: 60 region: description: 'The region where the address is located. This may not be relevant in some countries. ' type: string example: Baden-Wuerttemberg maxLength: 60 county: description: '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. ' type: string example: Dublin maxLength: 60 autonomous_community: description: 'In Spain, an autonomous community is the first sub-national level of political and administrative division. ' type: string example: Catalonia maxLength: 60 post_town: description: '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. ' type: string example: London maxLength: 60 state: description: '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. ' type: string example: California maxLength: 60 neighborhood: description: 'Locality level of the address. Used in countries such as Brazil or Chile. ' type: string example: Copacabana maxLength: 60 commune: description: '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. ' type: string example: Providencia maxLength: 60 department: description: 'A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia. ' type: string example: Antioquia maxLength: 60 municipality: description: '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. ' type: string example: Medellin maxLength: 60 district: description: 'A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal. ' type: string example: Lisbon maxLength: 60 zip_code: description: 'A US system of postal codes used by the United States Postal Service (USPS). ' type: string example: '94103' maxLength: 10 eircode: description: 'A postal address in Ireland. ' type: string example: D02 X285 maxLength: 10 examples: - street_address: - Paul-Linke-Ufer 39-40 - 2. Hinterhof post_code: '10999' city: Berlin country: DE - street_address: - 156 Avenida Vida Nova - Apto 2 city: Taboão da Serra post_code: '06764045' state: SP neighborhood: Jardim Maria Rosa country: BR externalDocs: description: Address documentation url: https://developer.sumup.com/tools/glossary/merchant#addresses required: - country BusinessProfile: description: 'Business information about the merchant. This information will be visible to the merchant''s customers. ' type: object properties: name: description: The customer-facing business name. type: string example: Example Coffee maxLength: 150 minLength: 1 dynamic_descriptor: description: '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). ' type: string example: Example Coffee maxLength: 30 minLength: 1 pattern: ^[a-zA-Z0-9 \-+\'_.]{0,30}$ website: description: The business's publicly available website. type: string format: uri example: https://example.com maxLength: 255 email: description: A publicly available email address. type: string example: contact@example.com maxLength: 255 phone_number: $ref: '#/components/schemas/PhoneNumber' address: $ref: '#/components/schemas/Address' branding: $ref: '#/components/schemas/Branding' Problem: description: 'A RFC 9457 problem details object. Additional properties specific to the problem type may be present.' type: object properties: type: description: A URI reference that identifies the problem type. type: string format: uri example: https://developer.sumup.com/problem/not-found title: description: A short, human-readable summary of the problem type. type: string example: Requested resource couldn't be found. status: description: The HTTP status code generated by the origin server for this occurrence of the problem. type: integer example: 404 detail: description: A human-readable explanation specific to this occurrence of the problem. type: string example: The requested resource doesn't exist or does not belong to you. instance: description: A URI reference that identifies the specific occurrence of the problem. type: string format: uri additionalProperties: true required: - type title: Problem PersonalIdentifier: type: object properties: ref: description: 'The unique reference for the personal identifier type as defined in the country SDK. ' type: string examples: - br.cpf value: description: 'The company identifier value. ' type: string examples: - 847.060.136-90 maxLength: 30 examples: - ref: br.cpf value: 847.060.136-90 required: - ref - value CountryCode: description: '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. ' type: string examples: - AR - AT - AU - BE - BG - BR - CH - CL - CO - CY - CZ - DE - DK - EE - ES - FI - FR - GB - GR - HU - IE - IT - LT - LU - LV - MT - MX - NL - false - PE - PL - PT - RO - SE - SI - SK - US maxLength: 2 minLength: 2 Timestamps: type: object properties: created_at: description: '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). ' type: string format: date-time examples: - 2021-08-31 12:00:00+00:00 readOnly: true updated_at: description: '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). ' type: string format: date-time examples: - 2021-08-31 12:00:00+00:00 readOnly: true required: - created_at - updated_at ClassicMerchantIdentifiers: type: object properties: id: description: Classic (serial) merchant ID. type: integer format: int64 example: 1234 deprecated: true required: - id Attributes: description: Object attributes that are modifiable only by SumUp applications. type: object example: {} additionalProperties: true LegalType: description: '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. ' type: string examples: - de.freiberufler - br.ltda - gb.partnership - bg.private_limited_company externalDocs: description: The country SDK documentation for legal types. url: https://developer.sumup.com/tools/glossary/merchant#legal-types maxLength: 64 minLength: 4 securitySchemes: apiKey: description: API keys allow you easily interact with SumUp APIs. API keys are static tokens. You can create API keys from the [Dashboard](https://me.sumup.com/settings/api-keys) type: http scheme: Bearer oauth2: type: oauth2 description: 'SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users. To integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications). To maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.' flows: authorizationCode: authorizationUrl: https://api.sumup.com/authorize tokenUrl: https://api.sumup.com/token refreshUrl: https://api.sumup.com/token scopes: payments: Make payments by creating and processing checkouts. transactions.history: View transactions and transaction history. user.profile_readonly: View user profile details. user.profile: View and manage your user profile. user.app-settings: View and manage the SumUp mobile application settings. payment_instruments: Manage customers and their payment instruments. user.payout-settings: View and manage your payout settings. user.subaccounts: View and manage the user profile details of your employees. clientCredentials: tokenUrl: https://api.sumup.com/token scopes: payments: Make payments by creating and processing checkouts. transactions.history: View transactions and transaction history. user.profile_readonly: View user profile details. user.profile: View and manage your user profile. user.app-settings: View and manage the SumUp mobile application settings. payment_instruments: Manage customers and their payment instruments. user.payout-settings: View and manage your payout settings. user.subaccounts: View and manage the user profile details of your employee.