SumUp Merchants API
Merchant account represents a single business entity at SumUp.
OpenAPI Specification
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
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sumup/refs/heads/main/openapi/sumup-merchants-api-openapi.yml