openapi: 3.0.1 info: title: SumUp REST 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 paths: '/v0.1/merchants/{merchant_code}/payment-methods': get: operationId: GetPaymentMethods summary: Get available payment methods description: Get payment methods available for the given merchant to use with a checkout. parameters: - name: merchant_code in: path description: The SumUp merchant code. required: true schema: type: string example: MH4H92C7 - name: amount in: query description: 'The amount for which the payment methods should be eligible, in major units. Note that currency must also be provided when filtering by amount.' required: false schema: type: number example: 9.99 - name: currency in: query description: The currency for which the payment methods should be eligible. required: false schema: type: string example: EUR responses: '200': description: Available payment methods content: application/json: schema: type: object properties: available_payment_methods: type: array items: type: object required: - id properties: id: description: The ID of the payment method. type: string example: qr_code_pix examples: success: description: Available payment methods value: available_payment_methods: - id: apple_pay - id: blik '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/DetailsError' examples: Invalid_Parameter: description: One or more of the parameters are invalid. value: failed_constraints: - message: Currency must also be specified when filtering by amount reference: currency status: 400 title: Bad Request '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED security: - apiKey: [] - oauth2: - payments tags: - Checkouts x-codegen: method_name: list_available_payment_methods x-scopes: - payments /v0.1/checkouts: post: operationId: CreateCheckout summary: Create a checkout description: | Creates a new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout. For 3DS checkouts, add the `redirect_url` parameter to your request body schema. Follow by processing a checkout to charge the provided payment instrument. requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CheckoutCreateRequest' examples: Checkout: description: Standard request body for creating a checkout value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase id: 2b79757a-de87-4a2e-90e4-b17c947c730d status: PAID date: '2020-02-29T10:56:56+00:00' merchant_name: John Doe LTD redirect_url: 'https://sumup.com' Checkout3DS: description: Create a 3DS checkout value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase return_url: 'http://example.com/' customer_id: 831ff8d4cd5958ab5670 redirect_url: 'https://mysite.com/completed_purchase' CheckoutAPM: description: Create an Alternative Payment Method checkout value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 redirect_url: 'https://mysite.com/completed_purchase' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Checkout' examples: Checkout: description: Standard response body for a successfully created checkout value: checkout_reference: 8ea25ec3-3293-40e9-a165-6d7f3b3073c5 amount: 10.1 currency: EUR merchant_code: MH4H92C7 merchant_country: DE description: My Checkout return_url: 'http://example.com' id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent status: active merchant_code: MH4H92C7 transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '012345' internal_id: 0 Checkout3DS: description: Response body for a successfully created 3DS checkout value: checkout_reference: 8ea25ec3-3293-40e9-a165-6d7f3b3073c5 amount: 10.1 currency: EUR description: My Checkout return_url: 'http://example.com' id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 redirect_url: 'https://mysite.com/completed_purchase' transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '012345' internal_id: 0 CheckoutAPM: description: 'Response body for APMs, including Blik, iDeal, ...' value: checkout_reference: 8ea25ec3-3293-40e9-a165-6d7f3b3073c5 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: My Checkout return_url: 'http://example.com' id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING date: '2021-06-29T11:08:36.000+00:00' merchant_name: My company merchant_country: DE redirect_url: 'https://sumup.com' purpose: CHECKOUT transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '012345' internal_id: 0 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorExtended' examples: Missing_Parameter: description: A required parameter is missing. value: message: Validation error error_code: MISSING param: merchant_code '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have the required permission for making this request. value: error_message: checkout_payments_not_allowed error_code: FORBIDDEN status_code: '403' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: Existing_Checkout: description: A resource with the specified parameters already exists on the server. value: error_code: DUPLICATED_CHECKOUT message: Checkout with this checkout reference and pay to email already exists security: - apiKey: [] - oauth2: - payments tags: - Checkouts x-codegen: method_name: create x-scopes: - payments get: operationId: ListCheckouts summary: List checkouts description: Lists created checkout resources according to the applied `checkout_reference`. parameters: - name: checkout_reference in: query description: Filters the list of checkout resources by the unique ID of the checkout. required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/CheckoutSuccess' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED security: - apiKey: [] - oauth2: - payments tags: - Checkouts x-codegen: method_name: list x-scopes: - payments '/v0.1/checkouts/{id}': parameters: - name: id in: path description: Unique ID of the checkout resource. required: true schema: type: string get: operationId: GetCheckout summary: Retrieve a checkout description: Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found security: - apiKey: [] - oauth2: - payments tags: - Checkouts x-codegen: method_name: get x-scopes: - payments put: operationId: ProcessCheckout summary: Process a checkout description: | Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the `Create a checkout` endpoint. Follow this request with `Retrieve a checkout` to confirm its status. requestBody: description: Details of the payment instrument for processing the checkout. content: application/json: schema: $ref: '#/components/schemas/ProcessCheckout' examples: ProcessCard: description: Process a checkout with a card value: payment_type: card installments: 1 mandate: type: recurrent user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36' user_ip: 172.217.169.174 card: type: VISA name: John Doe number: '1234567890123456' expiry_year: '2023' expiry_month: '01' cvv: '123' zip_code: '12345' last_4_digits: '3456' ProcessToken: description: Process a checkout with a token value: payment_type: card installments: 1 token: ba85dfee-c3cf-48a6-84f5-d7d761fbba50 customer_id: MEDKHDTI ProcessBoleto: description: Process a checkout with Boleto value: payment_type: boleto personal_details: email: user@example.com first_name: John last_name: Doe tax_id: 423.378.593-47 address: country: BR city: São Paulo line1: 'Rua Gilberto Sabino, 215' state: SP postal_code: 05425-020 ProcessiDeal: description: Process a checkout with iDeal value: payment_type: ideal personal_details: email: user@example.com first_name: John last_name: Doe address: country: NL ProcessBancontact: description: Process a checkout with Bancontact value: payment_type: bancontact personal_details: email: user@example.com first_name: John last_name: Doe address: country: BE responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' examples: CheckoutSuccessCard: description: Successfully processed checkout with a card value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase return_url: 'http://example.com' id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent status: active merchant_code: MH4H92C7 transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '053201' internal_id: 1763892018 transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 CheckoutSuccessToken: description: Successfully processed checkout with a token value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase with token id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: '2020-02-29T10:56:56+00:00' transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_name: Sample Merchant redirect_url: 'https://mysite.com/completed_purchase' customer_id: 831ff8d4cd5958ab5670 payment_instrument: token: e76d7e5c-9375-4fac-a7e7-b19dc5302fbc transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '053201' internal_id: 1763892018 CheckoutSuccessBoleto: description: Successfully processed checkout with Boleto value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: BRL merchant_code: MH4H92C7 description: Boleto checkout id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: '2021-07-06T12:34:02.000+00:00' merchant_name: Sample shop boleto: barcode: '34191090081790614310603072340007886840000000200' url: 'https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto' redirect_url: 'https://website.com' purpose: CHECKOUT transactions: - id: debd2986-9852-4e86-8a8e-7ea9c87dd679 transaction_code: TEN3E696NP merchant_code: MH4H92C9 amount: 10.1 vat_amount: 6 tip_amount: 3 currency: BRL timestamp: '2021-07-06T12:34:16.460+00:00' status: PENDING payment_type: BOLETO entry_mode: BOLETO installments_count: 1 internal_id: 1763892018 CheckoutSuccessiDeal: description: Successfully processed checkout with iDeal value: next_step: url: 'https://r3.girogate.de/ti/simideal' method: GET payload: tx: '961473700' rs: ILnaUeQTKJ184fVrjGILrLjePX9E4rmz cs: c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 full: 'https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5' mechanism: - browser CheckoutSuccessBancontact: description: Successfully processed checkout with Bancontact value: next_step: url: 'https://r3.girogate.de/ti/simbcmc' method: GET payload: tx: '624788471' rs: 5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB cs: 697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc full: 'https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc' mechanism: - browser '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/CheckoutAccepted' '400': description: Bad Request content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorExtended' - type: array description: List of error messages. items: $ref: '#/components/schemas/ErrorExtended' examples: Invalid_Parameter: description: A required parameter has an invalid value. value: message: Validation error error_code: INVALID param: card.expiry_year Multiple_Invalid_Parameters: description: Multiple required parameters have invalid values. value: - error_code: INVALID message: Validation error param: card.name - error_code: INVALID message: Validation error param: card.number - error_code: INVALID message: Validation error param: card.expiry_year '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: Checkout_Processed: description: The identified checkout resource is already processed. value: error_code: CHECKOUT_PROCESSED message: Checkout is already processed security: - apiKey: [] - oauth2: [] tags: - Checkouts x-codegen: method_name: process x-scopes: [] delete: operationId: DeactivateCheckout summary: Deactivate a checkout description: Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Checkout' example: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 id: 817340ce-f1d9-4609-b90a-6152f8ee267j amount: 2 currency: EUR merchant_code: MH4H92C7 description: Deletion example purpose: CHECKOUT status: EXPIRED date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' merchant_name: Sample Merchant transactions: [] '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: Checkout_Processed: description: The identified checkout resource is already processed. value: error_code: CHECKOUT_PROCESSED message: Checkout is already processed security: - apiKey: [] - oauth2: - payments tags: - Checkouts x-codegen: method_name: deactivate x-scopes: - payments /v0.1/customers: post: operationId: CreateCustomer summary: Create a customer description: Creates a new saved customer resource which you can later manipulate and save payment instruments to. requestBody: description: Details of the customer. content: application/json: schema: $ref: '#/components/schemas/Customer' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: Existing_Customer: description: A resource with the specified identifier already exists on the server. value: message: Customer already exists error_code: CUSTOMER_ALREADY_EXISTS security: - apiKey: [] - oauth2: - payment_instruments tags: - Customers x-codegen: method_name: create x-scopes: - payment_instruments '/v0.1/customers/{customer_id}': parameters: - name: customer_id in: path description: Unique ID of the saved customer resource. required: true schema: type: string get: operationId: GetCustomer summary: Retrieve a customer description: 'Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation.' responses: '200': description: Created content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found security: - apiKey: [] - oauth2: - payment_instruments tags: - Customers x-codegen: method_name: get x-scopes: - payment_instruments put: operationId: UpdateCustomer summary: Update a customer description: | Updates an identified saved customer resource's personal details. The request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values. requestBody: description: '' content: application/json: schema: type: object properties: personal_details: $ref: '#/components/schemas/PersonalDetails' responses: '200': description: Created content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found security: - apiKey: [] - oauth2: - payment_instruments tags: - Customers x-codegen: method_name: update x-scopes: - payment_instruments '/v0.1/customers/{customer_id}/payment-instruments': parameters: - name: customer_id in: path description: Unique ID of the saved customer resource. required: true schema: type: string get: operationId: ListPaymentInstruments summary: List payment instruments description: Lists all payment instrument resources that are saved for an identified customer. responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/PaymentInstrumentResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found security: - apiKey: [] - oauth2: - payment_instruments tags: - Customers x-codegen: method_name: list_payment_instruments x-scopes: - payment_instruments '/v0.1/customers/{customer_id}/payment-instruments/{token}': parameters: - name: customer_id in: path description: Unique ID of the saved customer resource. required: true schema: type: string - name: token in: path description: Unique token identifying the card saved as a payment instrument resource. required: true schema: type: string delete: operationId: DeactivatePaymentInstrument summary: Deactivate a payment instrument description: Deactivates an identified card payment instrument resource for a customer. responses: '204': description: No Content '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found security: - apiKey: [] - oauth2: - payment_instruments tags: - Customers x-codegen: method_name: deactivate_payment_instrument x-scopes: - payment_instruments '/v0.1/me/refund/{txn_id}': parameters: - name: txn_id in: path description: Unique ID of the transaction. required: true schema: type: string post: operationId: RefundTransaction summary: Refund a transaction description: Refunds an identified transaction either in full or partially. requestBody: description: '' content: application/json: schema: description: Optional amount for partial refunds of transactions. type: object properties: amount: description: 'Amount to be refunded. Eligible amount can''t exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.' type: number format: float responses: '204': description: No Content '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: Transaction_Not_Refundable: description: The state of the identified transaction resource does not permit the requested operation. value: error_code: CONFLICT message: The transaction is not refundable in its current state security: - apiKey: [] - oauth2: - payments tags: - Transactions x-codegen: method_name: refund x-scopes: - payments '/v2.1/merchants/{merchant_code}/transactions': get: operationId: GetTransactionV2.1 summary: Retrieve a transaction description: | Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and *one* of following parameters is required: * `id` * `internal_id` * `transaction_code` * `foreign_transaction_id` * `client_transaction_id` parameters: - name: merchant_code in: path required: true schema: type: string example: MH4H92C7 - name: id in: query description: Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource). required: false schema: type: string - name: internal_id in: query description: Retrieves the transaction resource with the specified internal transaction ID (the `internal_id` parameter in the transaction resource). required: false schema: type: string - name: transaction_code in: query description: Retrieves the transaction resource with the specified transaction code. required: false schema: type: string - name: foreign_transaction_id in: query description: External/foreign transaction id (passed by clients). schema: type: string - name: client_transaction_id in: query description: Client transaction id. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TransactionFull' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found security: - apiKey: [] - oauth2: - transactions.history tags: - Transactions x-codegen: method_name: get x-scopes: - transactions.history /v0.1/me/transactions: get: operationId: GetTransaction summary: Retrieve a transaction description: | Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and *one* of following parameters is required: * `id` * `internal_id` * `transaction_code` * `foreign_transaction_id` * `client_transaction_id` parameters: - name: id in: query description: Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource). required: false schema: type: string - name: internal_id in: query description: Retrieves the transaction resource with the specified internal transaction ID (the `internal_id` parameter in the transaction resource). required: false schema: type: string - name: transaction_code in: query description: Retrieves the transaction resource with the specified transaction code. required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TransactionFull' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found deprecated: true security: - apiKey: [] - oauth2: - transactions.history tags: - Transactions x-codegen: method_name: get_deprecated x-scopes: - transactions.history '/v2.1/merchants/{merchant_code}/transactions/history': get: operationId: ListTransactionsV2.1 summary: List transactions description: Lists detailed history of all transactions associated with the merchant profile. parameters: - name: merchant_code in: path required: true schema: type: string example: MH4H92C7 - name: transaction_code in: query description: Retrieves the transaction resource with the specified transaction code. required: false schema: type: string - name: order in: query description: Specifies the order in which the returned results are displayed. schema: type: string default: ascending enum: - ascending - descending - name: limit in: query description: 'Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.' schema: type: integer - name: users in: query description: Filters the returned results by user email. required: false schema: type: array items: type: string format: email - name: statuses in: query description: Filters the returned results by the specified list of final statuses of the transactions. required: false schema: type: array items: type: string enum: - SUCCESSFUL - CANCELLED - FAILED - REFUNDED - CHARGE_BACK - name: payment_types in: query description: Filters the returned results by the specified list of payment types used for the transactions. required: false schema: type: array items: type: string enum: - CASH - POS - ECOM - BALANCE - MOTO - BOLETO - UNKNOWN - name: types in: query description: Filters the returned results by the specified list of transaction types. required: false schema: type: array items: type: string enum: - PAYMENT - REFUND - CHARGE_BACK - name: changes_since in: query description: 'Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time - name: newest_time in: query description: 'Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time - name: newest_ref in: query description: Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request). required: false schema: type: string - name: oldest_time in: query description: 'Filters the results by the creation time of resources and returns only transactions that are created *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time - name: oldest_ref in: query description: Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *greater* than the specified value. This parameters supersedes the `oldest_time` parameter (if both are provided in the request). required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/TransactionHistory' links: type: array items: $ref: '#/components/schemas/Link' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED security: - apiKey: [] - oauth2: - transactions.history tags: - Transactions x-codegen: method_name: list x-scopes: - transactions.history /v0.1/me/transactions/history: get: operationId: ListTransactions summary: List transactions description: Lists detailed history of all transactions associated with the merchant profile. parameters: - name: transaction_code in: query description: Retrieves the transaction resource with the specified transaction code. required: false schema: type: string - name: order in: query description: Specifies the order in which the returned results are displayed. schema: type: string default: ascending enum: - ascending - descending - name: limit in: query description: 'Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.' schema: type: integer - name: users in: query description: Filters the returned results by user email. required: false schema: type: array items: type: string format: email - name: statuses in: query description: Filters the returned results by the specified list of final statuses of the transactions. required: false schema: type: array items: type: string enum: - SUCCESSFUL - CANCELLED - FAILED - REFUNDED - CHARGE_BACK - name: payment_types in: query description: Filters the returned results by the specified list of payment types used for the transactions. required: false schema: type: array items: type: string enum: - CASH - POS - ECOM - BALANCE - MOTO - BOLETO - UNKNOWN - name: types in: query description: Filters the returned results by the specified list of transaction types. required: false schema: type: array items: type: string enum: - PAYMENT - REFUND - CHARGE_BACK - name: changes_since in: query description: 'Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time - name: newest_time in: query description: 'Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time - name: newest_ref in: query description: Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request). required: false schema: type: string - name: oldest_time in: query description: 'Filters the results by the creation time of resources and returns only transactions that are created *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time - name: oldest_ref in: query description: Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *greater* than the specified value. This parameters supersedes the `oldest_time` parameter (if both are provided in the request). required: false schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/TransactionHistory' links: type: array items: $ref: '#/components/schemas/Link' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED deprecated: true security: - apiKey: [] - oauth2: - transactions.history tags: - Transactions x-codegen: method_name: list_deprecated x-scopes: - transactions.history /v0.1/me: get: operationId: GetAccount summary: Retrieve a profile description: Returns user profile information. parameters: - name: 'include[]' in: query description: A list of additional information you want to receive for the user. By default only personal and merchant profile information will be returned. required: false schema: type: array items: type: string enum: - settings - doing_business_as - bank_accounts - app_settings - country_details responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MerchantAccount' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED deprecated: true security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchant x-codegen: method_name: get x-deprecation-notice: 'The _Retrieve a profile_ endpoint is deprecated, please use the `Merchant` object instead (see [Merchants](https://developer.sumup.com/api/merchants)).' x-scopes: - user.profile - user.profile_readonly '/v1.0/merchants/{merchant_code}/payouts': get: operationId: ListPayoutsV1 summary: List payouts description: Lists ordered payouts for the merchant profile. parameters: - name: merchant_code in: path required: true schema: type: string example: MH4H92C7 - name: start_date in: query description: 'Start date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: true schema: type: string format: date - name: end_date in: query description: 'End date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: true schema: type: string format: date - name: format in: query required: false schema: type: string enum: - json - csv - name: limit in: query required: false schema: type: integer - name: order in: query required: false schema: type: string enum: - desc - asc responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FinancialPayouts' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Payouts x-codegen: method_name: list x-scopes: - user.profile - user.profile_readonly /v0.1/me/financials/payouts: get: operationId: ListPayouts summary: List payouts description: Lists ordered payouts for the merchant profile. parameters: - name: start_date in: query description: 'Start date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: true schema: type: string format: date - name: end_date in: query description: 'End date (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: true schema: type: string format: date - name: format in: query required: false schema: type: string enum: - json - csv - name: limit in: query required: false schema: type: integer - name: order in: query required: false schema: type: string enum: - desc - asc responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FinancialPayouts' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED deprecated: true security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Payouts x-codegen: method_name: list_deprecated x-scopes: - user.profile - user.profile_readonly /v0.1/me/personal-profile: get: operationId: GetPersonalProfile summary: Retrieve a personal profile description: Retrieves personal profile data. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PersonalProfileLegacy' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED deprecated: true security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchant x-codegen: method_name: get_personal_profile x-deprecation-notice: 'The _Retrieve a personal profile_ endpoint is deprecated, please use the `persons` field of the `Merchant` object instead. (see [Merchants](https://developer.sumup.com/api/merchants)).' x-scopes: - user.profile - user.profile_readonly /v0.1/me/merchant-profile: get: operationId: GetMerchantProfile summary: Retrieve a merchant profile description: Retrieves merchant profile data. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MerchantProfileLegacy' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' deprecated: true security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchant x-codegen: method_name: get_merchant_profile x-deprecation-notice: 'The _Retrieve a merchant profile_ endpoint is deprecated, please use the `Merchant` object instead (see [Merchants](https://developer.sumup.com/api/merchants)).' x-scopes: - user.profile - user.profile_readonly /v0.1/me/merchant-profile/doing-business-as: get: operationId: GetDoingBusinessAs summary: Retrieve DBA description: Retrieves Doing Business As profile. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DoingBusinessAsLegacy' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED deprecated: true security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchant x-codegen: method_name: get_doing_business_as x-deprecation-notice: 'The _Retrieve DBA_ endpoint is deprecated, please use the `business_profile` field of the `Merchant` object instead (see [Merchants](https://developer.sumup.com/api/merchants)).' x-scopes: - user.profile - user.profile_readonly '/v1.1/receipts/{id}': get: operationId: GetReceipt summary: Retrieve receipt details description: Retrieves receipt specific data for a transaction. parameters: - name: id in: path description: 'SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD.' required: true schema: type: string - name: mid in: query description: Merchant code. required: true schema: type: string - name: tx_event_id in: query description: The ID of the transaction event (refund). required: false schema: type: integer responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED security: - apiKey: [] - oauth2: [] tags: - Receipts x-codegen: method_name: get x-scopes: [] /v0.1/me/accounts: get: operationId: ListSubAccounts summary: List operators description: Returns list of operators for currently authorized user's merchant. parameters: - name: query in: query description: |- Search query used to filter users that match given query term. Current implementation allow querying only over the email address. All operators whos email address contains the query string are returned. schema: type: string - name: include_primary in: query description: If true the list of operators will include also the primary user. schema: type: boolean responses: '200': description: List of operators. content: application/json: schema: type: array items: $ref: '#/components/schemas/Operator' deprecated: true security: - apiKey: [] - oauth2: [] tags: - Subaccounts x-deprecation-notice: 'Subaccounts API is deprecated, to list users in your merchant account please use [List members](https://developer.sumup.com/api/members/list) instead.' x-permissions: - members_list x-scopes: [] post: operationId: CreateSubAccount summary: Create an operator description: Creates new operator for currently authorized users' merchant. requestBody: required: true content: application/json: schema: type: object properties: username: type: string format: email example: operator1@mydomain.com password: type: string example: correct horse batter staple minLength: 8 nickname: type: string example: Operator 1 permissions: type: object properties: create_moto_payments: type: boolean create_referral: type: boolean full_transaction_history_view: type: boolean refund_transactions: type: boolean required: - username - password responses: '200': description: Newly created operator. content: application/json: schema: $ref: '#/components/schemas/Operator' '403': description: Error response for compat API calls. content: application/json: schema: $ref: '#/components/schemas/CompatError' deprecated: true security: - apiKey: [] - oauth2: [] tags: - Subaccounts x-deprecation-notice: 'Subaccounts API is deprecated, to create a user in your merchant account please use [Create member](https://developer.sumup.com/api/members/create) instead.' x-permissions: - members_update x-scopes: [] '/v0.1/me/accounts/{operator_id}': get: operationId: CompatGetOperator summary: Retrieve an operator description: Returns specific operator. parameters: - name: operator_id in: path description: The unique identifier for the operator. required: true schema: type: integer format: int32 responses: '200': description: Information about the requested operator. content: application/json: schema: $ref: '#/components/schemas/Operator' deprecated: true security: - apiKey: [] - oauth2: [] tags: - Subaccounts x-deprecation-notice: 'Subaccounts API is deprecated, to get a user that''s a member of your merchant account please use [Get member](https://developer.sumup.com/api/members/get) instead.' x-permissions: - members_view x-scopes: [] put: operationId: UpdateSubAccount summary: Update an operator description: Updates operator. If the operator was disabled and their password is updated they will be unblocked. parameters: - name: operator_id in: path description: The unique identifier for the operator. required: true schema: type: integer format: int32 requestBody: required: true content: application/json: schema: type: object properties: password: type: string example: correct horse batter staple minLength: 8 username: type: string format: email maxLength: 256 disabled: type: boolean nickname: type: string example: Operator 1 permissions: type: object properties: create_moto_payments: type: boolean create_referral: type: boolean full_transaction_history_view: type: boolean refund_transactions: type: boolean responses: '200': description: Updated operator. content: application/json: schema: $ref: '#/components/schemas/Operator' '400': description: Invalid Operators' email or password was already used. content: application/json: schema: $ref: '#/components/schemas/CompatError' deprecated: true security: - apiKey: [] - oauth2: [] tags: - Subaccounts x-deprecation-notice: 'Subaccounts API is deprecated, to update a user that''s a member of your merchant account please use [Update member](https://developer.sumup.com/api/members/update) instead.' x-permissions: - members_update x-scopes: [] delete: operationId: DeactivateSubAccount summary: Disable an operator. description: Disable the specified operator for the merchant account. parameters: - name: operator_id in: path description: The unique identifier for the operator. required: true schema: type: integer format: int32 responses: '200': description: Operator successfully disabled. content: application/json: schema: $ref: '#/components/schemas/Operator' deprecated: true security: - apiKey: [] - oauth2: [] tags: - Subaccounts x-deprecation-notice: 'Subaccounts API is deprecated, to remove a user that''s a member of your merchant account please use [Delete member](https://developer.sumup.com/api/members/delete) instead.' x-permissions: - members_delete x-scopes: [] /v0.1/memberships: get: operationId: ListMemberships summary: List memberships description: List memberships of the current user. parameters: - name: offset in: query description: Offset of the first member to return. schema: type: integer example: 0 default: 0 minimum: 0 - name: limit in: query description: Maximum number of members to return. schema: type: integer example: 10 default: 10 maximum: 25 minimum: 1 - name: kind in: query description: Filter memberships by resource kind. schema: $ref: '#/components/schemas/ResourceType' - name: status in: query description: Filter the returned memberships by the membership status. schema: $ref: '#/components/schemas/MembershipStatus' - name: resource.type in: query description: Filter memberships by resource kind. schema: $ref: '#/components/schemas/ResourceType' - name: resource.attributes.sandbox in: query description: Filter memberships by the sandbox status of the resource the membership is in. schema: type: boolean - name: resource.name in: query description: Filter memberships by the name of the resource the membership is in. schema: type: string responses: '200': description: Returns a list of Membership objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Membership' total_count: type: integer example: 3 required: - total_count - items security: - apiKey: [] - oauth2: [] tags: - Memberships x-codegen: method_name: list x-scopes: [] '/v0.1/merchants/{merchant_code}/members': get: operationId: ListMerchantMembers summary: List members description: Lists merchant members. parameters: - name: offset in: query description: Offset of the first member to return. schema: type: integer example: 0 default: 0 minimum: 0 - name: limit in: query description: Maximum number of members to return. schema: type: integer example: 10 default: 10 maximum: 25 minimum: 1 - name: scroll in: query description: Indicates to skip count query. schema: type: boolean example: true default: false x-document: false - name: email in: query description: Filter the returned members by email address prefix. schema: type: string example: user - name: user.id in: query description: Search for a member by user id. schema: type: string format: uuid example: 245b2ead-85bf-45ff-856f-311a88a5d454 - name: status in: query description: Filter the returned members by the membership status. schema: $ref: '#/components/schemas/MembershipStatus' - name: roles in: query description: Filter the returned members by role. schema: type: array items: type: string example: - role_employee - role_accountant explode: true style: form - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC responses: '200': description: Returns a list of Member objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Member' total_count: type: integer example: 3 required: - items '404': description: Merchant not found. security: - apiKey: [] - oauth2: [] tags: - Members x-codegen: method_name: list x-permissions: - relation: merchant_read object_type: merchant object_id_param: merchant_code x-scopes: [] post: operationId: CreateMerchantMember summary: Create a member description: Create a merchant member. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC requestBody: required: true content: application/json: schema: type: object properties: is_managed_user: description: 'True if the user is managed by the merchant. In this case, we''ll created a virtual user with the provided password and nickname.' type: boolean email: description: Email address of the member to add. type: string format: email password: description: 'Password of the member to add. Only used if `is_managed_user` is true. In the case of service accounts, the password is not used and can not be defined by the caller.' type: string format: password minLength: 8 nickname: description: Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only. type: string example: Test User roles: description: List of roles to assign to the new member. type: array items: type: string metadata: $ref: '#/components/schemas/Metadata' attributes: $ref: '#/components/schemas/Attributes' example: email: karl.berg@example.com roles: - role_employee required: - email - roles responses: '201': description: Returns the Member object if the creation succeeded. content: application/json: schema: $ref: '#/components/schemas/Member' '400': description: Invalid request. '404': description: Merchant not found. '429': description: Too many invitations sent to that user. The limit is 10 requests per 5 minutes and the Retry-After header is set to the number of minutes until the reset of the limit. security: - apiKey: [] - oauth2: [] tags: - Members x-codegen: method_name: create x-permissions: - relation: members_create object_type: merchant object_id_param: merchant_code x-scopes: [] '/v0.1/merchants/{merchant_code}/members/{member_id}': get: operationId: GetMerchantMember summary: Retrieve a member description: Retrieve a merchant member. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC - name: member_id in: path description: The ID of the member to retrieve. required: true schema: type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP responses: '200': description: Returns the Member object for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Member' '404': description: Merchant or member not found. security: - apiKey: [] - oauth2: [] tags: - Members x-codegen: method_name: get x-permissions: - relation: members_view object_type: merchant object_id_param: merchant_code x-scopes: [] put: operationId: UpdateMerchantMember summary: Update a member description: Update the merchant member. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC - name: member_id in: path description: The ID of the member to retrieve. required: true schema: type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP requestBody: required: true content: application/json: schema: type: object properties: roles: type: array items: type: string metadata: $ref: '#/components/schemas/Metadata' attributes: $ref: '#/components/schemas/Attributes' user: description: Allows you to update user data of managed users. type: object properties: nickname: description: User's preferred name. Used for display purposes only. type: string example: Test User password: description: Password of the member to add. Only used if `is_managed_user` is true. type: string format: password minLength: 8 example: Update member's role: roles: - role_manager Update managed user: user: nickname: New Employee Name responses: '200': description: Returns the updated Member object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Member' '400': description: Cannot set password or nickname for an invited user. '403': description: Cannot change password for managed user. Password was already used before. '404': description: Merchant or member not found. '409': description: Cannot update member as some data conflict with existing members. security: - apiKey: [] - oauth2: [] tags: - Members x-codegen: method_name: update x-permissions: - relation: members_update object_type: merchant object_id_param: merchant_code x-scopes: [] delete: operationId: DeleteMerchantMember summary: Delete a member description: Deletes a merchant member. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC - name: member_id in: path description: The ID of the member to retrieve. required: true schema: type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP responses: '200': description: Returns an empty response if the deletion succeeded. '404': description: Merchant or member not found. security: - apiKey: [] - oauth2: [] tags: - Members x-codegen: method_name: delete x-permissions: - relation: members_delete object_type: merchant object_id_param: merchant_code x-scopes: [] '/v0.1/merchants/{merchant_code}/roles': get: operationId: ListMerchantRoles summary: List roles description: List merchant's custom roles. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC responses: '200': description: Returns a list of Role objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Role' required: - items '404': description: Merchant not found. security: - apiKey: [] - oauth2: [] tags: - Roles x-codegen: method_name: list x-permissions: - relation: roles_list object_type: merchant object_id_param: merchant_code x-scopes: [] post: operationId: CreateMerchantRole summary: Create a role description: Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC requestBody: required: true content: application/json: schema: type: object properties: name: description: User-defined name of the role. type: string example: Senior Shop Manager II permissions: description: User's permissions. type: array items: type: string example: - catalog_access - taxes_access - members_access maxItems: 100 metadata: $ref: '#/components/schemas/Metadata' description: description: User-defined description of the role. type: string example: Manges the shop and the employees. required: - name - permissions responses: '201': description: Returns the Role object after successful custom role creation. content: application/json: schema: $ref: '#/components/schemas/Role' '400': description: Invalid request. '404': description: Merchant not found. security: - apiKey: [] - oauth2: [] tags: - Roles x-codegen: method_name: create x-permissions: - relation: roles_create object_type: merchant object_id_param: merchant_code x-scopes: [] '/v0.1/merchants/{merchant_code}/roles/{role_id}': get: operationId: GetMerchantRole summary: Retrieve a role description: Retrieve a custom role by ID. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC - name: role_id in: path description: The ID of the role to retrieve. required: true schema: type: string example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP responses: '200': description: Returns the Role object for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Role' '404': description: Merchant or role not found. security: - apiKey: [] - oauth2: [] tags: - Roles x-codegen: method_name: get x-permissions: - relation: roles_view object_type: merchant object_id_param: merchant_code x-scopes: [] delete: operationId: DeleteMerchantRole summary: Delete a role description: Delete a custom role. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC - name: role_id in: path description: The ID of the role to retrieve. required: true schema: type: string example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP responses: '200': description: Returns an empty response if the role deletion succeeded. '400': description: Invalid request. '404': description: Merchant not found. security: - apiKey: [] - oauth2: [] tags: - Roles x-codegen: method_name: delete x-permissions: - relation: roles_delete object_type: merchant object_id_param: merchant_code x-scopes: [] patch: operationId: UpdateMerchantRole summary: Update a role description: Update a custom role. parameters: - name: merchant_code in: path description: Merchant code. required: true schema: type: string example: MC0X0ABC - name: role_id in: path description: The ID of the role to retrieve. required: true schema: type: string example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP requestBody: required: true content: application/json: schema: type: object properties: name: description: User-defined name of the role. type: string example: Senior Shop Manager II permissions: description: User's permissions. type: array items: type: string example: - catalog_access - taxes_access - members_access maxItems: 100 description: description: User-defined description of the role. type: string example: Manges the shop and the employees. example: name: Senior Shop Manager III permissions: - catalog_edit - taxes_access - members_edit responses: '200': description: Returns the updated Role object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Role' '400': description: Invalid request. '404': description: Merchant not found. security: - apiKey: [] - oauth2: [] tags: - Roles x-codegen: method_name: update x-permissions: - relation: roles_update object_type: merchant object_id_param: merchant_code x-scopes: [] '/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: | No user with the specified ID exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryClient' code: $ref: '#/components/schemas/ErrorCodeNotFound' 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: | No user with the specified ID exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryClient' code: $ref: '#/components/schemas/ErrorCodeNotFound' '500': description: | An internal server error occurred. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryServer' code: $ref: '#/components/schemas/ErrorCodeInternalServerError' 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: | No user with the specified ID exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryClient' code: $ref: '#/components/schemas/ErrorCodeNotFound' '500': description: | An internal server error occurred. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryServer' code: $ref: '#/components/schemas/ErrorCodeInternalServerError' 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 '/v0.1/merchants/{merchant_code}/readers': get: operationId: ListReaders summary: List Readers description: List all readers of the merchant. parameters: - name: merchant_code in: path description: Unique identifier of the merchant account. required: true schema: type: string example: MC0X0ABC responses: '200': description: Returns a list Reader objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Reader' required: - items security: - apiKey: [] - oauth2: - readers.read tags: - Readers x-codegen: method_name: list x-permissions: - relation: readers_list object_type: merchant object_id_param: merchant_code x-scopes: - readers.read post: operationId: CreateReader summary: Create a Reader description: Create a new Reader for the merchant account. parameters: - name: merchant_code in: path description: Unique identifier of the merchant account. required: true schema: type: string example: MC0X0ABC requestBody: required: true content: application/json: schema: type: object properties: pairing_code: $ref: '#/components/schemas/ReaderPairingCode' name: $ref: '#/components/schemas/ReaderName' meta: $ref: '#/components/schemas/Meta' required: - pairing_code - name responses: '201': description: Returns the Reader object if the creation succeeded. content: application/json: schema: $ref: '#/components/schemas/Reader' examples: created: summary: A reader that waits for the physical device to acknowledge the pairing. value: id: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 name: Frontdesk status: processing device: identifier: U1DT3NA00-CN model: solo created_at: '2023-05-09T14:50:20.214Z' updated_at: '2023-05-09T14:52:58.714Z' links: UpdateReaderByID: operationId: UpdateReader parameters: id: $response.body#/id description: Update the reader object. This can be used to set a name after using this endpoint to verify the pairing code. DeleteReaderByID: operationId: DeleteReader parameters: id: $response.body#/id description: Delete the reader. security: - apiKey: [] - oauth2: - readers.write tags: - Readers x-codegen: method_name: create x-permissions: - relation: readers_create object_type: merchant object_id_param: merchant_code x-scopes: - readers.write '/v0.1/merchants/{merchant_code}/readers/{id}': get: operationId: GetReader summary: Retrieve a Reader description: Retrieve a Reader. parameters: - name: If-Modified-Since in: header description: |- Return the reader only if it has been modified after the specified timestamp given in the headers. Timestamps are accepted in the following formats: - HTTP Standard: [IMF format (RFC 5322)](https://www.rfc-editor.org/rfc/rfc5322#section-3.3), sometimes also referred to as [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231#section-7.1.1.1). - RFC 3339: Used for timestamps in JSON payloads on this API. required: false schema: type: string oneOf: - format: httpdate type: string example: 'Tue, 03 May 2022 14:46:44 GMT' - format: date-time type: string example: '2023-05-30T10:38:01+00:00' - name: merchant_code in: path description: Unique identifier of the merchant account. required: true schema: type: string example: MC0X0ABC - name: id in: path description: The unique identifier of the reader. required: true schema: $ref: '#/components/schemas/ReaderID' responses: '200': description: Returns a Reader object for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Reader' '404': description: The requested Reader resource does not exists. security: - apiKey: [] - oauth2: - readers.read tags: - Readers x-codegen: method_name: get x-permissions: - relation: readers_view object_type: merchant object_id_param: merchant_code x-scopes: - readers.read delete: operationId: DeleteReader summary: Delete a reader description: Delete a reader. parameters: - name: merchant_code in: path description: Unique identifier of the merchant account. required: true schema: type: string example: MC0X0ABC - name: id in: path description: The unique identifier of the reader. required: true schema: $ref: '#/components/schemas/ReaderID' responses: '200': description: Returns an empty response if the deletion succeeded. security: - apiKey: [] - oauth2: - readers.write tags: - Readers x-permissions: - relation: readers_delete object_type: merchant object_id_param: merchant_code x-scopes: - readers.write patch: operationId: UpdateReader summary: Update a Reader description: Update a Reader. parameters: - name: merchant_code in: path description: Unique identifier of the merchant account. required: true schema: type: string example: MC0X0ABC - name: id in: path description: The unique identifier of the reader. required: true schema: $ref: '#/components/schemas/ReaderID' requestBody: required: true content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/ReaderName' meta: $ref: '#/components/schemas/Meta' responses: '200': description: Returns the updated Reader object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Reader' '403': description: The reader is not linked to the merchant account. security: - apiKey: [] - oauth2: - readers.write tags: - Readers x-codegen: method_name: update x-permissions: - relation: readers_update object_type: merchant object_id_param: merchant_code x-scopes: - readers.write '/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout': post: operationId: CreateReaderCheckout summary: Create a Reader Checkout description: | Creates a Checkout for a Reader. This process is asynchronous and the actual transaction may take some time to be stared on the device. There are some caveats when using this endpoint: * The target device must be online, otherwise checkout won't be accepted * After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected. **Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher. parameters: - name: merchant_code in: path description: Merchant Code required: true schema: type: string x-struct: null x-validate: null example: MC0X0ABC - name: reader_id in: path description: The unique identifier of the Reader required: true schema: type: string x-struct: null x-validate: null example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 requestBody: description: A checkout initial attributes required: true content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutRequest' responses: '201': description: The Checkout got successfully created for the given reader. content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutResponse' '400': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' '422': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutUnprocessableEntity' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' '504': description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' callbacks: ReaderCheckoutStatusChange: '{$request.body#/return_url}': post: requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReaderCheckoutStatusChange' responses: '200': description: | Your server returns this code if it accepts the callback. If the server returns any other code, the callback will be retried up to 5 times with exponential backoff. security: - apiKey: [] - oauth2: - readers.write tags: - Readers x-codegen: method_name: create_checkout x-permissions: - readers_checkout_create x-scopes: - readers.write '/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate': post: operationId: CreateReaderTerminate summary: Terminate a Reader Checkout description: | Terminate a Reader Checkout stops the current transaction on the target device. This process is asynchronous and the actual termination may take some time to be performed on the device. There are some caveats when using this endpoint: * The target device must be online, otherwise terminate won't be accepted * The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc. * There is no confirmation of the termination. If a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL. **Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher. parameters: - name: merchant_code in: path description: Merchant Code required: true schema: type: string x-struct: null x-validate: null example: MC0X0ABC - name: reader_id in: path description: The unique identifier of the Reader required: true schema: type: string x-struct: null x-validate: null example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 requestBody: description: A checkout initial attributes required: false content: application/json: {} responses: '202': description: The Terminate action was successfully dispatched for the given reader. content: application/json: {} '400': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateError' '422': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateUnprocessableEntity' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateError' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateError' '504': description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateError' security: - apiKey: [] - oauth2: - readers.write tags: - Readers x-codegen: method_name: terminate_checkout x-permissions: - readers_checkout_create x-scopes: - readers.write components: parameters: ChangesSinceFilter: name: changes_since in: query description: 'Filters the results by the latest modification time of resources and returns only transactions that are modified *at or after* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time CheckoutID: name: id in: path required: true description: Unique ID of the checkout resource. schema: type: string CheckoutReference: name: checkout_reference in: query description: Filters the list of checkout resources by the unique ID of the checkout. required: false schema: type: string CustomerID: name: customer_id in: path required: true description: Unique ID of the saved customer resource. schema: type: string GeoCoordinatesFilter: name: geo_coordinates in: query description: | Filters the results by the geographical coordinates of the location where the transaction is made (as retrieved from the terminal device) and returns only results that fall within the specified rectangular area. The accepted format is a comma-separated list of coordinate points that form a rectangle defined by the following parameters: * `southwest_lng` (for the longitude value of the southwestern edge of the rectangle) * `southwest_lat` (for the latitude value of the southwestern edge of the rectangle) * `northeast_lng` (for the longitude value of the northeastern edge of the rectangle) * `northeast_lat` (for the latitude value of the northeastern edge of the rectangle) required: false schema: type: string LimitFilter: name: limit in: query description: 'Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results.' schema: type: integer NewestRefFilter: name: newest_ref in: query description: Filters the results by the reference ID of transaction events and returns only transactions with events whose IDs are *smaller* than the specified value. This parameters supersedes the `newest_time` parameter (if both are provided in the request). required: false schema: type: string NewestTimeFilter: name: newest_time in: query description: 'Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format).' required: false schema: type: string format: date-time OrderFilter: name: order in: query description: Specifies the order in which the returned results are displayed. schema: type: string default: ascending enum: - ascending - descending PaymentTypesFilter: name: payment_types in: query description: Filters the returned results by the specified list of payment types used for the transactions. required: false schema: type: array items: type: string enum: - CASH - POS - ECOM - BALANCE - MOTO - BOLETO - UNKNOWN ReadersFilter: name: readers in: query description: Filters the returned results by the specified list of serial numbers of the terminal readers used for the transactions. required: false schema: type: array items: type: string StatusesFilter: name: statuses in: query description: Filters the returned results by the specified list of final statuses of the transactions. required: false schema: type: array items: type: string enum: - SUCCESSFUL - CANCELLED - FAILED - REFUNDED - CHARGE_BACK Token: name: token in: path required: true description: Unique token identifying the card saved as a payment instrument resource. schema: type: string TransactionCode: name: transaction_code in: query description: Retrieves the transaction resource with the specified transaction code. required: false schema: type: string TransactionID: name: id in: query description: Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource). required: false schema: type: string TxnID: in: path name: txn_id required: true description: Unique ID of the transaction. schema: type: string TypesFilter: name: types in: query description: Filters the returned results by the specified list of transaction types. required: false schema: type: array items: type: string enum: - PAYMENT - REFUND - CHARGE_BACK UsersFilter: name: users in: query description: Filters the returned results by user email. required: false schema: type: array items: type: string format: email schemas: AccountLegacy: description: Profile information. type: object properties: username: description: Username of the user profile. type: string type: description: The role of the user. type: string enum: - normal - operator AddressLegacy: description: Profile's personal address information. type: object properties: city: description: City name from the address. type: string example: Berlin country: description: 'Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).' type: string example: DE line_1: description: First line of the address with details of the street name and number. type: string example: Sample street line_2: description: 'Second line of the address with details of the building, unit, apartment, and floor numbers.' type: string example: ap. 5 postal_code: description: Postal code from the address. type: string example: '10115' state: description: State name or abbreviation from the address. type: string example: Berlin AddressWithDetails: description: Details of the registered address. type: object properties: address_line1: description: Address line 1 type: string address_line2: description: Address line 2 type: string city: description: City type: string country: description: Country ISO 3166-1 code type: string region_id: description: Country region id type: number region_name: description: Region name type: string region_code: description: Region code type: string post_code: description: Postal code type: string landline: description: Landline number type: string first_name: description: undefined type: string last_name: description: undefined type: string company: description: undefined type: string country_details: $ref: '#/components/schemas/CountryDetails' timeoffset_details: $ref: '#/components/schemas/TimeoffsetDetails' state_id: description: undefined type: string AppSettings: description: Mobile app settings type: object properties: checkout_preference: description: Checkout preference type: string include_vat: description: Include vat. type: boolean manual_entry_tutorial: description: Manual entry tutorial. type: boolean mobile_payment_tutorial: description: Mobile payment tutorial. type: boolean tax_enabled: description: Tax enabled. type: boolean mobile_payment: description: Mobile payment. type: string reader_payment: description: Reader payment. type: string cash_payment: description: Cash payment. type: string advanced_mode: description: Advanced mode. type: string expected_max_transaction_amount: description: Expected max transaction amount. type: number manual_entry: description: Manual entry. type: string terminal_mode_tutorial: description: Terminal mode tutorial. type: boolean tipping: description: Tipping. type: string tip_rates: description: Tip rates. type: array items: type: number format: float barcode_scanner: description: Barcode scanner. type: string referral: description: Referral. type: string BankAccount: type: object properties: bank_code: description: Bank code type: string branch_code: description: Branch code type: string swift: description: SWIFT code type: string account_number: description: Account number type: string iban: description: IBAN type: string account_type: description: Type of the account type: string account_category: description: Account category - business or personal type: string account_holder_name: type: string status: description: Status in the verification process type: string primary: description: The primary bank account is the one used for payouts type: boolean created_at: description: Creation date of the bank account type: string bank_name: description: Bank name type: string BusinessOwners: description: Business owners information. type: array items: type: object properties: first_name: description: BO's first name type: string last_name: description: BO's last name of the user type: string date_of_birth: description: Date of birth type: string mobile_phone: description: Mobile phone number type: string landline: description: BO's Landline type: string ownership: description: Ownership percentage type: number Card: description: __Required when payment type is `card`.__ Details of the payment card. type: object properties: name: description: Name of the cardholder as it appears on the payment card. type: string example: FIRSTNAME LASTNAME writeOnly: true number: description: Number of the payment card (without spaces). type: string example: '1234567890123456' writeOnly: true expiry_year: description: Year from the expiration time of the payment card. Accepted formats are `YY` and `YYYY`. type: string example: '2023' maxLength: 4 minLength: 2 writeOnly: true expiry_month: description: Month from the expiration time of the payment card. Accepted format is `MM`. type: string enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' - '08' - '09' - '10' - '11' - '12' writeOnly: true cvv: description: Three or four-digit card verification value (security code) of the payment card. type: string example: '123' maxLength: 4 minLength: 3 writeOnly: true zip_code: description: Required five-digit ZIP code. Applicable only to merchant users in the USA. type: string example: '12345' maxLength: 5 minLength: 5 writeOnly: true last_4_digits: description: Last 4 digits of the payment card number. type: string example: '3456' maxLength: 4 minLength: 4 readOnly: true type: description: Issuing card network of the payment card. type: string enum: - AMEX - CUP - DINERS - DISCOVER - ELO - ELV - HIPERCARD - JCB - MAESTRO - MASTERCARD - VISA - VISA_ELECTRON - VISA_VPAY - UNKNOWN readOnly: true required: - name - number - expiry_month - expiry_year - cvv - last_4_digits - type CardResponse: description: Details of the payment card. type: object properties: last_4_digits: description: Last 4 digits of the payment card number. type: string example: '3456' maxLength: 4 minLength: 4 readOnly: true type: description: Issuing card network of the payment card. type: string enum: - AMEX - CUP - DINERS - DISCOVER - ELO - ELV - HIPERCARD - JCB - MAESTRO - MASTERCARD - VISA - VISA_ELECTRON - VISA_VPAY - UNKNOWN readOnly: true Checkout: description: Details of the payment checkout. type: object properties: checkout_reference: description: Unique ID of the payment checkout specified by the client application when creating the checkout resource. type: string maxLength: 90 amount: description: Amount of the payment. type: number format: float example: 10.1 currency: $ref: '#/components/schemas/Currency' merchant_code: description: Unique identifying code of the merchant profile. type: string example: MH4H92C7 description: description: 'Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.' type: string return_url: description: URL to which the SumUp platform sends the processing status of the payment checkout. type: string format: uri id: description: Unique ID of the checkout resource. type: string example: 4e425463-3e1b-431d-83fa-1e51c2925e99 readOnly: true status: description: Current status of the checkout. type: string enum: - PENDING - FAILED - PAID date: description: 'Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.' type: string format: date-time example: '2020-02-29T10:56:56+00:00' valid_until: description: 'Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.' type: string format: date-time example: '2020-02-29T10:56:56+00:00' nullable: true customer_id: description: 'Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.' type: string example: 831ff8d4cd5958ab5670 mandate: $ref: '#/components/schemas/MandateResponse' transactions: description: List of transactions related to the payment. type: array items: allOf: - $ref: '#/components/schemas/TransactionBase' - $ref: '#/components/schemas/TransactionCheckoutInfo' uniqueItems: true title: Checkout CheckoutCreateRequest: description: Details of the payment checkout. type: object properties: checkout_reference: description: Unique ID of the payment checkout specified by the client application when creating the checkout resource. type: string maxLength: 90 amount: description: Amount of the payment. type: number format: float currency: $ref: '#/components/schemas/Currency' merchant_code: description: Unique identifying code of the merchant profile. type: string example: MH4H92C7 description: description: 'Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.' type: string return_url: description: URL to which the SumUp platform sends the processing status of the payment checkout. type: string format: uri customer_id: description: 'Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referenced customer.' type: string purpose: description: Purpose of the checkout. type: string default: CHECKOUT enum: - CHECKOUT - SETUP_RECURRING_PAYMENT id: description: Unique ID of the checkout resource. type: string readOnly: true status: description: Current status of the checkout. type: string enum: - PENDING - FAILED - PAID readOnly: true date: description: 'Date and time of the creation of the payment checkout. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.' type: string format: date-time example: '2020-02-29T10:56:56+00:00' readOnly: true valid_until: description: 'Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.' type: string format: date-time example: '2020-02-29T10:56:56+00:00' nullable: true transactions: description: List of transactions related to the payment. type: array items: allOf: - $ref: '#/components/schemas/TransactionBase' - $ref: '#/components/schemas/TransactionCheckoutInfo' readOnly: true uniqueItems: true redirect_url: description: '__Required__ for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and __recommended__ for card payments. Refers to a url where the end user is redirected once the payment processing completes. If not specified, the [Payment Widget](https://developer.sumup.com/online-payments/tools/card-widget) renders [3DS challenge](https://developer.sumup.com/online-payments/features/3ds) within an iframe instead of performing a full-page redirect.' type: string example: 'https://mysite.com/completed_purchase' required: - checkout_reference - amount - currency - merchant_code ProcessCheckout: description: Details of the payment instrument for processing the checkout. type: object properties: payment_type: description: Describes the payment method used to attempt processing type: string enum: - card - boleto - ideal - blik - bancontact installments: description: Number of installments for deferred payments. Available only to merchant users in Brazil. type: integer maximum: 12 minimum: 1 mandate: $ref: '#/components/schemas/MandatePayload' card: $ref: '#/components/schemas/Card' token: description: __Required when using a tokenized card to process a checkout.__ Unique token identifying the saved payment card for a customer. type: string customer_id: description: __Required when `token` is provided.__ Unique ID of the customer. type: string personal_details: $ref: '#/components/schemas/PersonalDetails' required: - payment_type CheckoutSuccess: allOf: - $ref: '#/components/schemas/Checkout' - type: object properties: transaction_code: description: Transaction code of the successful transaction with which the payment for the checkout is completed. type: string example: TEENSK4W2K readOnly: true transaction_id: description: Transaction ID of the successful transaction with which the payment for the checkout is completed. type: string example: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 readOnly: true merchant_name: description: Name of the merchant type: string example: Sample Merchant redirect_url: description: Refers to a url where the end user is redirected once the payment processing completes. type: string example: 'https://mysite.com/completed_purchase' payment_instrument: description: Object containing token information for the specified payment instrument type: object properties: token: description: Token value type: string example: e76d7e5c-9375-4fac-a7e7-b19dc5302fbc CheckoutAccepted: description: 3DS Response type: object properties: next_step: description: Required action processing 3D Secure payments. type: object properties: url: description: Where the end user is redirected. type: string example: 'https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A' method: description: Method used to complete the redirect. type: string example: POST redirect_url: description: Refers to a url where the end user is redirected once the payment processing completes. type: string example: 'https://mysite.com/completed_purchase' mechanism: description: Indicates allowed mechanisms for redirecting an end user. If both values are provided to ensure a redirect takes place in either. type: array items: type: string enum: - iframe - browser payload: description: Contains parameters essential for form redirection. Number of object keys and their content can vary. type: object properties: PaReq: example: eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw== MD: example: b1a536c0-29b9-11eb-adc1-0242ac120002 TermUrl: example: 'https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment' Customer: type: object properties: customer_id: description: Unique ID of the customer. type: string example: 831ff8d4cd5958ab5670 personal_details: $ref: '#/components/schemas/PersonalDetails' required: - customer_id title: Customer CountryDetails: description: Country Details type: object properties: currency: description: Currency ISO 4217 code type: string iso_code: description: Country ISO code type: string en_name: description: Country EN name type: string native_name: description: Country native name type: string DoingBusinessAsLegacy: description: Doing Business As information type: object properties: business_name: description: Doing business as name type: string company_registration_number: description: Doing business as company registration number type: string vat_id: description: Doing business as VAT ID type: string website: description: Doing business as website type: string email: description: Doing business as email type: string address: type: object properties: address_line1: description: Address line 1 type: string address_line2: description: Address line 2 type: string city: description: City type: string country: description: Country ISO 3166-1 code type: string region_id: description: Country region ID type: number region_name: description: Country region name type: string post_code: description: Postal code type: string Error: description: Error message structure. type: object properties: message: description: Short description of the error. type: string error_code: description: Platform code for the error. type: string ErrorExtended: allOf: - $ref: '#/components/schemas/Error' - type: object properties: param: description: 'Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, `card.name` refers to the `name` parameter embedded in the `card` object.' type: string ErrorForbidden: description: Error message for forbidden requests. type: object properties: error_message: description: Short description of the error. type: string error_code: description: Platform code for the error. type: string status_code: description: HTTP status code for the error. type: string DetailsError: description: Error message structure. type: object properties: title: description: Short title of the error. type: string details: description: Details of the error. type: string status: description: The status code. type: number failed_constraints: type: array items: type: object properties: message: type: string reference: type: string Event: type: object properties: id: $ref: '#/components/schemas/EventID' transaction_id: $ref: '#/components/schemas/TransactionID' type: $ref: '#/components/schemas/EventType' status: $ref: '#/components/schemas/EventStatus' amount: $ref: '#/components/schemas/AmountEvent' timestamp: $ref: '#/components/schemas/TimestampEvent' fee_amount: description: Amount of the fee related to the event. type: number format: float installment_number: description: Consecutive number of the installment. type: integer deducted_amount: description: Amount deducted for the event. type: number format: float deducted_fee_amount: description: Amount of the fee deducted for the event. type: number format: float FinancialPayouts: type: array items: type: object properties: amount: type: number format: float currency: type: string date: type: string format: date fee: type: number format: float id: type: integer reference: type: string status: type: string enum: - SUCCESSFUL - FAILED transaction_code: type: string type: type: string enum: - PAYOUT - CHARGE_BACK_DEDUCTION - REFUND_DEDUCTION - DD_RETURN_DEDUCTION - BALANCE_DEDUCTION title: Financial Payouts LegalTypeLegacy: description: Id of the legal type of the merchant profile type: object properties: id: description: Unique id type: number full_description: description: Legal type description type: string description: description: Legal type short description type: string sole_trader: description: Sole trader legal type if true type: boolean Link: description: Details of a link to a related resource. type: object properties: rel: description: Specifies the relation to the current resource. type: string href: description: URL for accessing the related resource. type: string format: uri type: description: Specifies the media type of the related resource. type: string MandatePayload: description: Mandate is passed when a card is to be tokenized type: object properties: type: description: Indicates the mandate type type: string enum: - recurrent user_agent: description: Operating system and web client used by the end-user type: string user_ip: description: IP address of the end user. Supports IPv4 and IPv6 type: string example: type: recurrent user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36' user_ip: 172.217.169.174 required: - type - user_agent MandateResponse: description: Created mandate type: object properties: type: description: Indicates the mandate type type: string status: description: Mandate status type: string merchant_code: description: Merchant code which has the mandate type: string example: MH4H92C7 example: type: recurrent status: active merchant_code: MH4H92C7 MerchantAccount: description: Details of the merchant account. type: object properties: account: $ref: '#/components/schemas/AccountLegacy' personal_profile: $ref: '#/components/schemas/PersonalProfileLegacy' merchant_profile: $ref: '#/components/schemas/MerchantProfileLegacy' app_settings: $ref: '#/components/schemas/AppSettings' permissions: $ref: '#/components/schemas/PermissionsLegacy' title: Merchant Account MerchantProfileLegacy: description: Account's merchant profile type: object properties: merchant_code: description: Unique identifying code of the merchant profile type: string example: MH4H92C7 company_name: description: Company name type: string website: description: Website type: string legal_type: $ref: '#/components/schemas/LegalTypeLegacy' merchant_category_code: description: Merchant category code type: string mobile_phone: description: Mobile phone number type: string company_registration_number: description: Company registration number type: string vat_id: description: Vat ID type: string permanent_certificate_access_code: description: Permanent certificate access code (Portugal) type: string nature_and_purpose: description: Nature and purpose of the business type: string address: $ref: '#/components/schemas/AddressWithDetails' business_owners: $ref: '#/components/schemas/BusinessOwners' doing_business_as: $ref: '#/components/schemas/DoingBusinessAsLegacy' settings: $ref: '#/components/schemas/MerchantSettings' vat_rates: $ref: '#/components/schemas/VatRates' locale: description: Merchant locale (for internal usage only) type: string bank_accounts: type: array items: $ref: '#/components/schemas/BankAccount' extdev: description: True if the merchant is extdev type: boolean payout_zone_migrated: description: True if the payout zone of this merchant is migrated type: boolean country: description: 'Merchant country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (for internal usage only)' type: string MerchantSettings: description: 'Merchant settings (like \"payout_type\", \"payout_period\")' type: object properties: tax_enabled: description: Whether to show tax in receipts (saved per transaction) type: boolean payout_type: description: Payout type type: string payout_period: description: Payout frequency type: string payout_on_demand_available: description: Whether merchant can edit payouts on demand type: boolean payout_on_demand: description: Whether merchant will receive payouts on demand type: boolean printers_enabled: description: Whether to show printers in mobile app type: boolean payout_instrument: description: Payout Instrument type: string moto_payment: description: Whether merchant can make MOTO payments type: string enum: - UNAVAILABLE - ENFORCED - 'ON' - 'OFF' stone_merchant_code: description: Stone merchant code type: string daily_payout_email: description: Whether merchant will receive daily payout emails type: boolean monthly_payout_email: description: Whether merchant will receive monthly payout emails type: boolean gross_settlement: description: Whether merchant has gross settlement enabled type: boolean PaymentInstrumentResponse: description: Payment Instrument Response type: object properties: token: description: Unique token identifying the saved payment card for a customer. type: string readOnly: true active: description: 'Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a `DELETE` request to the resource endpoint.' type: boolean default: true readOnly: true type: description: Type of the payment instrument. type: string enum: - card card: description: Details of the payment card. type: object properties: last_4_digits: description: Last 4 digits of the payment card number. type: string example: '3456' maxLength: 4 minLength: 4 readOnly: true type: description: Issuing card network of the payment card. type: string enum: - AMEX - CUP - DINERS - DISCOVER - ELO - ELV - HIPERCARD - JCB - MAESTRO - MASTERCARD - VISA - VISA_ELECTRON - VISA_VPAY - UNKNOWN readOnly: true mandate: $ref: '#/components/schemas/MandateResponse' created_at: description: 'Creation date of payment instrument. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.' type: string format: date-time example: token: bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3 active: true type: card mandate: type: recurrent status: active merchant_code: MH4H92C7 card: last_4_digits: '0001' type: VISA created_at: '2021-03-30T10:06:07.000+00:00' PermissionsLegacy: description: User permissions type: object properties: create_moto_payments: description: Create MOTO payments type: boolean full_transaction_history_view: description: Can view full merchant transaction history type: boolean refund_transactions: description: Refund transactions type: boolean create_referral: description: Create referral type: boolean PersonalDetails: description: Personal details for the customer. type: object properties: first_name: description: First name of the customer. type: string example: John last_name: description: Last name of the customer. type: string example: Doe email: description: Email address of the customer. type: string example: user@example.com phone: description: Phone number of the customer. type: string example: '+491635559723' birth_date: description: Date of birth of the customer. type: string format: date example: '1993-12-31' tax_id: description: An identification number user for tax purposes (e.g. CPF) type: string example: 423.378.593-47 maxLength: 255 address: $ref: '#/components/schemas/AddressLegacy' PersonalProfileLegacy: description: Account's personal profile. type: object properties: first_name: description: First name of the user type: string last_name: description: Last name of the user type: string date_of_birth: description: Date of birth type: string mobile_phone: description: Mobile phone number type: string address: $ref: '#/components/schemas/AddressWithDetails' complete: type: boolean Product: description: Details of the product for which the payment is made. type: object properties: name: description: Name of the product from the merchant's catalog. type: string price: description: Price of the product without VAT. type: number format: float vat_rate: description: VAT rate applicable to the product. type: number format: float single_vat_amount: description: 'Amount of the VAT for a single product item (calculated as the product of `price` and `vat_rate`, i.e. `single_vat_amount = price * vat_rate`).' type: number format: float price_with_vat: description: Price of a single product item with VAT. type: number format: float vat_amount: description: 'Total VAT amount for the purchase (calculated as the product of `single_vat_amount` and `quantity`, i.e. `vat_amount = single_vat_amount * quantity`).' type: number format: float quantity: description: Number of product items for the purchase. type: number total_price: description: 'Total price of the product items without VAT (calculated as the product of `price` and `quantity`, i.e. `total_price = price * quantity`).' type: number format: float total_with_vat: description: 'Total price of the product items including VAT (calculated as the product of `price_with_vat` and `quantity`, i.e. `total_with_vat = price_with_vat * quantity`).' type: number format: float Receipt: type: object properties: transaction_data: $ref: '#/components/schemas/ReceiptTransaction' merchant_data: $ref: '#/components/schemas/ReceiptMerchantData' emv_data: type: object acquirer_data: type: object properties: tid: type: string authorization_code: type: string return_code: type: string local_time: type: string title: Receipt ReceiptEvent: type: object properties: id: $ref: '#/components/schemas/EventID' transaction_id: $ref: '#/components/schemas/TransactionID' type: $ref: '#/components/schemas/EventType' status: $ref: '#/components/schemas/EventStatus' amount: $ref: '#/components/schemas/AmountEvent' timestamp: $ref: '#/components/schemas/TimestampEvent' receipt_no: type: string ReceiptCard: type: object properties: last_4_digits: description: Card last 4 digits. type: string type: description: Card Scheme. type: string ReceiptMerchantData: description: Receipt merchant data type: object properties: merchant_profile: type: object properties: merchant_code: type: string example: MH4H92C7 business_name: type: string email: type: string address: type: object properties: address_line1: type: string city: type: string country: type: string country_en_name: type: string country_native_name: type: string post_code: type: string landline: type: string locale: type: string ReceiptTransaction: description: Transaction information. type: object properties: transaction_code: description: Transaction code. type: string amount: description: Transaction amount. type: string vat_amount: description: Transaction VAT amount. type: string tip_amount: description: Tip amount (included in transaction amount). type: string currency: description: Transaction currency. type: string timestamp: description: Time created at. type: string format: date-time status: description: Transaction processing status. type: string payment_type: description: Transaction type. type: string entry_mode: description: Transaction entry mode. type: string verification_method: description: Cardholder verification method. type: string card: $ref: '#/components/schemas/ReceiptCard' installments_count: description: Number of installments. type: integer products: description: Products type: array items: type: object properties: name: description: Product name. type: string description: description: Product description. type: string price: description: Product price. type: number format: float quantity: description: Product quantity. type: integer total_price: description: Quantity x product price. type: number format: float vat_rates: description: Vat rates. type: array items: type: object properties: gross: description: Gross type: number format: float net: description: Net type: number format: float rate: description: Rate type: number format: float vat: description: Vat type: number format: float events: description: Events type: array items: $ref: '#/components/schemas/ReceiptEvent' receipt_no: description: Receipt number type: string TimeoffsetDetails: description: TimeOffset Details type: object properties: post_code: description: Postal code type: string offset: description: UTC offset type: number dst: description: Daylight Saving Time type: boolean TransactionEvent: description: Details of a transaction event. type: object properties: id: $ref: '#/components/schemas/EventID' event_type: $ref: '#/components/schemas/EventType' status: $ref: '#/components/schemas/EventStatus' amount: $ref: '#/components/schemas/AmountEvent' due_date: description: Date when the transaction event is due to occur. type: string format: date date: description: Date when the transaction event occurred. type: string format: date installment_number: description: 'Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`.' type: integer timestamp: $ref: '#/components/schemas/TimestampEvent' TransactionBase: description: Details of the transaction. type: object properties: id: description: Unique ID of the transaction. type: string example: 6b425463-3e1b-431d-83fa-1e51c2925e99 transaction_code: description: Transaction code returned by the acquirer/processing entity after processing the transaction. type: string example: TEENSK4W2K amount: description: Total amount of the transaction. type: number format: float example: 10.1 currency: $ref: '#/components/schemas/Currency' timestamp: description: 'Date and time of the creation of the transaction. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.' type: string format: date-time example: '2020-02-29T10:56:56.876Z' status: description: Current status of the transaction. type: string enum: - SUCCESSFUL - CANCELLED - FAILED - PENDING payment_type: description: Payment type used for the transaction. type: string enum: - ECOM - RECURRING - BOLETO - POS installments_count: description: Current number of the installment for deferred payments. type: integer minimum: 1 TransactionCheckoutInfo: type: object properties: merchant_code: description: Unique code of the registered merchant to whom the payment is made. type: string example: MH4H92C7 vat_amount: description: Amount of the applicable VAT (out of the total transaction amount). type: number format: float example: 6 tip_amount: description: Amount of the tip (out of the total transaction amount). type: number format: float example: 3 entry_mode: description: Entry mode of the payment details. type: string enum: - CUSTOMER_ENTRY - BOLETO auth_code: description: Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. type: string example: '053201' internal_id: description: Internal unique ID of the transaction on the SumUp platform. type: integer example: 1763892018 TransactionMixinHistory: type: object properties: product_summary: description: Short description of the payment. The value is taken from the `description` property of the related checkout resource. type: string payouts_total: description: Total number of payouts to the registered user specified in the `user` property. type: integer payouts_received: description: Number of payouts that are made to the registered user specified in the `user` property. type: integer payout_plan: description: Payout plan of the registered user at the time when the transaction was made. type: string enum: - SINGLE_PAYMENT - TRUE_INSTALLMENT - ACCELERATED_INSTALLMENT TransactionHistory: allOf: - $ref: '#/components/schemas/TransactionBase' - $ref: '#/components/schemas/TransactionMixinHistory' - type: object properties: transaction_id: $ref: '#/components/schemas/TransactionID' client_transaction_id: description: Client-specific ID of the transaction. type: string user: description: Email address of the registered user (merchant) to whom the payment is made. type: string format: email type: description: Type of the transaction for the registered user specified in the `user` property. type: string enum: - PAYMENT - REFUND - CHARGE_BACK card_type: description: Issuing card network of the payment card used for the transaction. type: string enum: - VISA - AMEX - CUP - DINERS - DISCOVER - ELO - ELV - HIPERCARD - JCB - MAESTRO - MASTERCARD - VISA_ELECTRON - VISA_VPAY - UNKNOWN TransactionFull: allOf: - $ref: '#/components/schemas/TransactionBase' - $ref: '#/components/schemas/TransactionCheckoutInfo' - $ref: '#/components/schemas/TransactionMixinHistory' - type: object properties: username: description: Email address of the registered user (merchant) to whom the payment is made. type: string format: email lat: $ref: '#/components/schemas/Lat' lon: $ref: '#/components/schemas/Lon' horizontal_accuracy: $ref: '#/components/schemas/HorizontalAccuracy' simple_payment_type: description: Simple name of the payment type. type: string enum: - MOTO - CASH - CC_SIGNATURE - ELV - CC_CUSTOMER_ENTERED - MANUAL_ENTRY - EMV verification_method: description: Verification method used for the transaction. type: string enum: - none - signature - offline pin - online pin - offline pin + signature - confirmation code verified card: $ref: '#/components/schemas/CardResponse' local_time: description: Local date and time of the creation of the transaction. type: string format: date-time payout_type: description: Payout type for the transaction. type: string enum: - BANK_ACCOUNT - BALANCE - PREPAID_CARD products: description: List of products from the merchant's catalogue for which the transaction serves as a payment. type: array items: $ref: '#/components/schemas/Product' vat_rates: description: List of VAT rates applicable to the transaction. type: array items: {} transaction_events: description: List of transaction events related to the transaction. type: array items: $ref: '#/components/schemas/TransactionEvent' simple_status: description: Status generated from the processing status and the latest transaction state. type: string enum: - SUCCESSFUL - PAID_OUT - CANCEL_FAILED - CANCELLED - CHARGEBACK - FAILED - REFUND_FAILED - REFUNDED - NON_COLLECTION links: description: List of hyperlinks for accessing related resources. type: array items: anyOf: - $ref: '#/components/schemas/Link' - $ref: '#/components/schemas/LinkRefund' uniqueItems: true events: description: List of events related to the transaction. type: array items: $ref: '#/components/schemas/Event' uniqueItems: true location: description: Details of the payment location as received from the payment terminal. type: object properties: lat: $ref: '#/components/schemas/Lat' lon: $ref: '#/components/schemas/Lon' horizontal_accuracy: $ref: '#/components/schemas/HorizontalAccuracy' tax_enabled: description: Indicates whether tax deduction is enabled for the transaction. type: boolean VatRates: description: Merchant VAT rates type: object properties: id: description: Internal ID type: number description: description: Description type: string rate: description: Rate type: number ordering: description: Ordering type: number country: description: Country ISO code type: string AmountEvent: description: Amount of the event. type: number format: float Currency: description: 'Three-letter [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) code of the currency for the amount. Currently supported currency values are enumerated above.' type: string example: EUR enum: - BGN - BRL - CHF - CLP - CZK - DKK - EUR - GBP - HRK - HUF - NOK - PLN - RON - SEK - USD EventType: description: Type of the transaction event. type: string enum: - PAYOUT - CHARGE_BACK - REFUND - PAYOUT_DEDUCTION EventStatus: description: Status of the transaction event. type: string enum: - PENDING - SCHEDULED - FAILED - REFUNDED - SUCCESSFUL - PAID_OUT EventID: description: Unique ID of the transaction event. type: integer format: int64 HorizontalAccuracy: description: Indication of the precision of the geographical position received from the payment terminal. type: number format: float Lat: description: Latitude value from the coordinates of the payment location (as received from the payment terminal reader). type: number format: float maximum: 90 minimum: 0 LinkRefund: allOf: - $ref: '#/components/schemas/Link' - type: object properties: min_amount: description: Minimum allowed amount for the refund. type: number format: float max_amount: description: Maximum allowed amount for the refund. type: number format: float Lon: description: Longitude value from the coordinates of the payment location (as received from the payment terminal reader). type: number format: float maximum: 180 minimum: 0 TransactionID: description: Unique ID of the transaction. type: string TimestampEvent: description: Date and time of the transaction event. type: string format: date-time Permissions: description: Permissions assigned to an operator or user. type: object properties: create_moto_payments: type: boolean create_referral: type: boolean full_transaction_history_view: type: boolean refund_transactions: type: boolean admin: type: boolean required: - create_moto_payments - create_referral - full_transaction_history_view - refund_transactions - admin Operator: description: Operator account for a merchant. type: object properties: id: type: integer format: int32 username: type: string example: operator1@mydomain.com nickname: type: string example: Operator 1 nullable: true disabled: type: boolean example: false created_at: description: The timestamp of when the operator was created. type: string format: date-time updated_at: description: The timestamp of when the operator was last updated. type: string format: date-time permissions: $ref: '#/components/schemas/Permissions' account_type: type: string enum: - operator - normal required: - id - username - disabled - created_at - updated_at - permissions - account_type CompatError: description: Error object for compat API calls. type: object properties: error_code: type: string example: NOT_FOUND message: type: string example: Resource not found. required: - error_code - message Metadata: description: 'Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata.' type: object example: {} additionalProperties: maxLength: 256 Attributes: description: Object attributes that are modifiable only by SumUp applications. type: object example: {} additionalProperties: maxLength: 256 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 example: BR maxLength: 2 minLength: 2 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 post_code: description: | The postal code (aka. zip code) of the address. type: string example: '10999' maxLength: 32 country: $ref: '#/components/schemas/CountryCode' city: description: | The city of the address. type: string example: Berlin maxLength: 512 province: description: | The province where the address is located. This may not be relevant in some countries. type: string example: Berlin maxLength: 512 region: description: | The region where the address is located. This may not be relevant in some countries. type: string example: Baden Wuerttemberg maxLength: 512 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 County maxLength: 512 autonomous_community: description: | In Spain, an autonomous community is the first sub-national level of political and administrative division. type: string example: Catalonia maxLength: 512 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: 512 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: 512 neighborhood: description: | Locality level of the address. Used in countries such as Brazil or Chile. type: string example: Copacabana maxLength: 512 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: 512 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: 512 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: Medellín maxLength: 512 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 District maxLength: 512 zip_code: description: | A US system of postal codes used by the United States Postal Service (USPS). type: string example: '94103' maxLength: 512 eircode: description: | A postal address in Ireland. type: string example: D02 X285 maxLength: 512 example: street_address: - Paul-Linke-Ufer 39-40 - 2. Hinterhof post_code: '10999' city: Berlin country: DE externalDocs: description: Address documentation url: 'https://sumup.roadie.so/docs/default/Component/merchants/merchant/#addresses' required: - country PersonalIdentifier: type: object properties: ref: description: The unique reference for the personal identifier type. type: string example: br.cpf value: description: The company identifier value. type: string example: 847.060.136-90 example: ref: br.cpf value: 847.060.136-90 required: - ref - value MembershipStatus: description: The status of the membership. type: string enum: - accepted - pending - expired - disabled - unknown ResourceType: description: |- The type of the membership resource. Possible values are: * `merchant` - merchant account(s) * `organization` - organization(s) type: string example: merchant Membership: description: 'A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.' type: object properties: id: description: ID of the membership. type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP resource_id: description: ID of the resource the membership is in. type: string example: M2DDT39A type: $ref: '#/components/schemas/ResourceType' roles: description: User's roles. type: array items: type: string example: - role_admin permissions: description: User's permissions. type: array items: type: string example: - members_read - members_write - create_moto_payments - full_transaction_history_view - refund_transactions - create_referral - developer_settings_edit - developer_settings_access deprecated: true x-deprecation-notice: 'Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.' created_at: description: The timestamp of when the membership was created. type: string format: date-time example: '2023-01-20T15:16:17Z' updated_at: description: The timestamp of when the membership was last updated. type: string format: date-time example: '2023-01-20T15:16:17Z' invite: $ref: '#/components/schemas/Invite' status: $ref: '#/components/schemas/MembershipStatus' metadata: $ref: '#/components/schemas/Metadata' attributes: $ref: '#/components/schemas/Attributes' resource: $ref: '#/components/schemas/MembershipResource' required: - id - resource_id - type - roles - permissions - created_at - updated_at - status - resource title: Membership MembershipResource: description: Information about the resource the membership is in. type: object properties: id: description: ID of the resource the membership is in. type: string example: M2DDT39A type: $ref: '#/components/schemas/ResourceType' name: description: Display name of the resource. type: string example: Acme Corp logo: description: Logo fo the resource. type: string format: uri example: 'https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png' maxLength: 256 created_at: description: The timestamp of when the membership resource was created. type: string format: date-time example: '2023-01-20T15:16:17Z' updated_at: description: The timestamp of when the membership resource was last updated. type: string format: date-time example: '2023-01-20T15:16:17Z' attributes: $ref: '#/components/schemas/Attributes' required: - id - type - name - created_at - updated_at title: Resource Member: description: 'A member is user within specific resource identified by resource id, resource type, and associated roles.' type: object properties: id: description: ID of the member. type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP roles: description: User's roles. type: array items: type: string example: - role_admin permissions: description: User's permissions. type: array items: type: string example: - members_read - members_write - create_moto_payments - full_transaction_history_view - refund_transactions - create_referral - developer_settings_edit - developer_settings_access deprecated: true x-deprecation-notice: 'Permissions include only legacy permissions, please use roles instead. Member access is based on roles within a given resource and the permissions these roles grant.' created_at: description: The timestamp of when the member was created. type: string format: date-time example: '2023-01-20T15:16:17Z' updated_at: description: The timestamp of when the member was last updated. type: string format: date-time example: '2023-01-20T15:16:17Z' user: $ref: '#/components/schemas/MembershipUser' invite: $ref: '#/components/schemas/Invite' status: $ref: '#/components/schemas/MembershipStatus' metadata: $ref: '#/components/schemas/Metadata' attributes: $ref: '#/components/schemas/Attributes' example: id: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP roles: - role_admin - role_owner permissions: - members_read - members_write - create_moto_payments - full_transaction_history_view - refund_transactions - create_referral - developer_settings_edit - developer_settings_access created_at: '2023-01-20T15:16:17Z' updated_at: '2023-02-20T15:16:17Z' user: id: 44ca0f5b-813b-46e1-aee7-e6242010662e email: example@sumup.com mfa_on_login_enabled: true virtual_user: false service_account_user: false status: accepted required: - id - roles - permissions - created_at - updated_at - status title: Member Invite: description: Pending invitation for membership. type: object properties: email: description: Email address of the invited user. type: string format: email example: boaty.mcboatface@sumup.com expires_at: type: string format: date-time example: '2023-01-20T15:16:17Z' required: - email - expires_at title: Invite MembershipUser: description: Information about the user associated with the membership. type: object properties: id: description: Identifier for the End-User (also called Subject). type: string example: 44ca0f5b-813b-46e1-aee7-e6242010662e email: description: 'End-User''s preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.' type: string example: example@sumup.com mfa_on_login_enabled: description: True if the user has enabled MFA on login. type: boolean example: true virtual_user: description: True if the user is a virtual user (operator). type: boolean example: false service_account_user: description: True if the user is a service account. type: boolean example: false disabled_at: description: 'Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`).' type: string format: date-time nickname: description: User's preferred name. Used for display purposes only. type: string example: Test User picture: description: 'URL of the End-User''s profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.' type: string format: uri example: 'https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png' classic: $ref: '#/components/schemas/MembershipUserClassic' required: - id - email - mfa_on_login_enabled - virtual_user - service_account_user MembershipUserClassic: description: Classic identifiers of the user. type: object properties: user_id: type: integer format: int32 deprecated: true required: - user_id Role: description: A custom role that can be used to assign set of permissions to members. type: object properties: id: description: Unique identifier of the role. type: string example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP name: description: User-defined name of the role. type: string example: Senior Shop Manager II description: description: User-defined description of the role. type: string example: Manges the shop and the employees. permissions: description: List of permission granted by this role. type: array items: type: string example: [] maxItems: 100 x-deprecation-notice: 'Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.' is_predefined: description: True if the role is provided by SumUp. type: boolean example: true metadata: $ref: '#/components/schemas/Metadata' created_at: description: The timestamp of when the role was created. type: string format: date-time example: '2023-01-20T15:16:17Z' updated_at: description: The timestamp of when the role was last updated. type: string format: date-time example: '2023-01-20T15:16:17Z' required: - id - name - permissions - is_predefined - created_at - updated_at title: Role ListPersonsResponseBody: type: object properties: items: type: array items: $ref: '#/components/schemas/Person' required: - items 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: url 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/models/merchant' title: Merchant 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: 512 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 examples: - 'https://www.sumup.com' maxLength: 255 nullable: true attributes: $ref: '#/components/schemas/Attributes' externalDocs: description: Company documentation url: 'https://developer.sumup.com/tools/models/merchant#company' 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 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: Gin & Dougnuts maxLength: 512 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 maxLength: 30 pattern: '^[a-zA-Z0-9 \-+\''_.]{0,30}$' website: description: The business's publicly available website. type: string example: 'https://gindoughnuts.com' maxLength: 512 email: description: A publicly available email address. type: string example: contact@gindoughnuts.com maxLength: 256 phone_number: $ref: '#/components/schemas/PhoneNumber' address: $ref: '#/components/schemas/Address' branding: $ref: '#/components/schemas/Branding' Person: allOf: - $ref: '#/components/schemas/BasePerson' PhoneNumber: description: | A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. type: string example: '+420123456789' maxLength: 64 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' 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/models/merchant#legal-types' maxLength: 64 minLength: 4 CompanyIdentifiers: description: | A list of country-specific company identifiers. type: array items: $ref: '#/components/schemas/CompanyIdentifier' 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/models/merchant#company-identifiers' required: - ref - value 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 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 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 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/models/merchant#persons' required: - id ClassicMerchantIdentifiers: type: object properties: id: description: Classic (serial) merchant ID. type: integer format: int64 example: 1234 deprecated: true required: - id 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-31T12:00:00Z' 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-31T12:00:00Z' readOnly: true required: - created_at - updated_at BaseError: type: object properties: instance: description: | A unique identifier for the error instance. This can be used to trace the error back to the server logs. type: string message: description: | A human-readable message describing the error that occurred. type: string ErrorCategoryClient: description: | The category of the error. type: string enum: - client_error ErrorCodeNotFound: description: | An error code specifying the exact error that occurred. type: string enum: - not_found ErrorCategoryServer: description: | The category of the error. type: string enum: - server_error ErrorCodeInternalServerError: description: | An error code specifying the exact error that occurred. type: string enum: - internal_error Reader: description: A physical card reader device that can accept in-person payments. type: object properties: id: $ref: '#/components/schemas/ReaderID' name: $ref: '#/components/schemas/ReaderName' status: $ref: '#/components/schemas/ReaderStatus' device: $ref: '#/components/schemas/ReaderDevice' meta: $ref: '#/components/schemas/Meta' created_at: description: The timestamp of when the reader was created. type: string format: date-time example: '2023-01-18T15:16:17Z' updated_at: description: The timestamp of when the reader was last updated. type: string format: date-time example: '2023-01-20T15:16:17Z' required: - id - name - status - device - created_at - updated_at title: Reader ReaderID: description: |- Unique identifier of the object. Note that this identifies the instance of the physical devices pairing with your SumUp account. If you DELETE a reader, and pair the device again, the ID will be different. Do not use this ID to refer to a physical device. type: string example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 maxLength: 30 minLength: 30 ReaderName: description: 'Custom human-readable, user-defined name for easier identification of the reader.' type: string example: Frontdesk maxLength: 500 ReaderStatus: description: |- The status of the reader object gives information about the current state of the reader. Possible values: - `unknown` - The reader status is unknown. - `processing` - The reader is created and waits for the physical device to confirm the pairing. - `paired` - The reader is paired with a merchant account and can be used with SumUp APIs. - `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated. type: string example: paired enum: - unknown - processing - paired - expired ReaderDevice: description: Information about the underlying physical device. type: object properties: identifier: description: A unique identifier of the physical device (e.g. serial number). type: string example: U1DT3NA00-CN model: description: Identifier of the model of the device. type: string example: solo enum: - solo - virtual-solo required: - identifier - model ReaderPairingCode: description: The pairing code is a 8 or 9 character alphanumeric string that is displayed on a SumUp Device after initiating the pairing. It is used to link the physical device to the created pairing. type: string example: 4WLFDSBF maxLength: 9 minLength: 8 CreateReaderCheckoutUnprocessableEntity: description: Unprocessable entity type: object properties: errors: type: object additionalProperties: true x-struct: null x-validate: null example: DataValidation: description: Validation errors for the informed fields. value: errors: card_type: - is invalid installments: - not allowed return_url: - must be a valid URL tip_rates: - must be between 0.01 and 0.99 total_amount: - must be greater than 0 ReaderCheckoutPending: description: Error returned when a checkout was requested in the last 60 seconds. value: errors: detail: A pending transaction already exists for this device ReaderOffline: description: Error returned when the target device is not online. value: errors: detail: The device is offline. type: READER_OFFLINE required: - errors title: CreateReaderCheckoutUnprocessableEntity x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.CreateReaderCheckoutUnprocessableEntity x-validate: null CreateReaderCheckoutError: description: Error description type: object properties: errors: type: object properties: detail: description: Error message type: string x-struct: null x-validate: null required: - type x-struct: null x-validate: null required: - errors title: CreateReaderCheckoutError x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.CreateReaderCheckoutError x-validate: null CreateReaderTerminateUnprocessableEntity: description: Unprocessable entity type: object properties: errors: type: object additionalProperties: true x-struct: null x-validate: null example: ReaderOffline: description: Error returned when the target device is not online. value: errors: detail: The device is offline. type: READER_OFFLINE required: - errors title: CreateReaderTerminateUnprocessableEntity x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.CreateReaderTerminateUnprocessableEntity x-validate: null CreateReaderTerminateError: description: Error description type: object properties: errors: type: object properties: detail: description: Error message type: string x-struct: null x-validate: null required: - type x-struct: null x-validate: null required: - errors title: CreateReaderTerminateError x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.CreateReaderTerminateError x-validate: null CreateReaderCheckoutResponse: type: object properties: data: type: object properties: client_transaction_id: description: | The client transaction ID is a unique identifier for the transaction that is generated for the client. It can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get). type: string example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 x-struct: null x-validate: null required: - client_transaction_id x-struct: null x-validate: null example: data: client_transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 required: - data title: CreateReaderCheckoutResponse x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.CreateReaderCheckoutResponse x-validate: null CreateReaderCheckoutRequest: description: Reader Checkout type: object properties: affiliate: description: | Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction. type: object properties: app_id: description: | Application ID of the affiliate. It is a unique identifier for the application and should be set by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page. type: string example: com.example.app x-struct: null x-validate: null foreign_transaction_id: description: | Foreign transaction ID of the affiliate. It is a unique identifier for the transaction. It can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get). type: string example: 19e12390-72cf-4f9f-80b5-b0c8a67fa43f x-struct: null x-validate: null key: description: | Key of the affiliate. It is a unique identifier for the key and should be generated by the integrator in the [Affiliate Keys](https://developer.sumup.com/affiliate-keys) page. type: string example: 123e4567-e89b-12d3-a456-426614174000 x-struct: null x-validate: null tags: description: | Additional metadata for the transaction. It is key-value object that can be associated with the transaction. type: object example: custom_key_1: custom_value_1 custom_key_2: custom_value_2 additionalProperties: true x-struct: null x-validate: null required: - app_id - key - foreign_transaction_id title: Affiliate x-struct: Elixir.SoloEdgeWeb.OpenApi.Common.Affiliate x-validate: null card_type: description: | The card type of the card used for the transaction. Is is required only for some countries (e.g: Brazil). type: string example: credit enum: - credit - debit x-struct: null x-validate: null description: description: Description of the checkout to be shown in the Merchant Sales type: string x-struct: null x-validate: null installments: description: | Number of installments for the transaction. It may vary according to the merchant country. For example, in Brazil, the maximum number of installments is 12. type: integer example: 1 x-struct: null x-validate: null return_url: description: | Webhook URL to which the payment result will be sent. It must be a HTTPS url. type: string format: uri example: 'https://www.example.com' x-struct: null x-validate: null tip_rates: description: | List of tipping rates to be displayed to the cardholder. The rates are in percentage and should be between 0.01 and 0.99. The list should be sorted in ascending order. type: array items: format: float multipleOf: 0.01 type: number x-struct: null x-validate: null x-struct: null x-validate: null tip_timeout: description: | Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds. It can only be set if `tip_rates` is provided. **Note**: If the target device is a Solo, it must be in version 3.3.38.0 or higher. type: integer example: 30 default: 30 maximum: 120 minimum: 30 x-struct: null x-validate: null total_amount: description: | Amount structure. The amount is represented as an integer value altogether with the currency and the minor unit. For example, EUR 1.00 is represented as value 100 with minor unit of 2. type: object example: currency: EUR minor_unit: 2 value: 1000 properties: currency: description: Currency ISO 4217 code type: string example: EUR x-struct: null x-validate: null minor_unit: description: | The minor units of the currency. It represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0. type: integer example: 2 minimum: 0 x-struct: null x-validate: null value: description: Integer value of the amount. type: integer example: 1000 minimum: 0 x-struct: null x-validate: null required: - currency - minor_unit - value title: Money x-struct: Elixir.SoloEdgeWeb.OpenApi.Common.Money x-validate: null example: affiliate: app_id: com.example.app foreign_transaction_id: '123456' key: ef7b684a-d6f4-4e93-9b1b-6acdd6564a8e tags: {} card_type: debit description: This is a description... installments: 1 return_url: 'https://webhook.site/e21ddbb0-42c4-4358-a981-f5a95cd86fb5' tip_rates: - 0.05 - 0.1 - 0.15 tip_timeout: 60 total_amount: currency: EUR minor_unit: 2 value: 5033 required: - total_amount title: CreateReaderCheckoutRequest x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.CreateReaderCheckoutRequest x-validate: null ReaderCheckoutStatusChange: description: The callback payload containing the status change of the Reader Checkout. type: object properties: event_type: description: Type of event. type: string example: solo.transaction.updated x-struct: null x-validate: null id: description: Unique identifier for the event. type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 x-struct: null x-validate: null payload: description: The event payload. type: object properties: client_transaction_id: description: The unique client transaction id. It is the same returned by the Checkout. type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 x-struct: null x-validate: null merchant_code: description: The merchant code associated with the transaction. type: string example: M1234567 x-struct: null x-validate: null status: description: The current status of the transaction. type: string example: successful enum: - successful - failed x-struct: null x-validate: null transaction_id: description: 'The transaction id. Deprecated: use `client_transaction_id` instead.' type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 deprecated: true x-struct: null x-validate: null required: - client_transaction_id - merchant_code - status x-struct: null x-validate: null timestamp: description: Timestamp of the event. type: string format: date-time example: '2023-10-05T14:48:00Z' x-struct: null x-validate: null required: - id - event_type - payload - timestamp title: ReaderCheckoutStatusChange x-struct: Elixir.SoloEdgeWeb.OpenApi.ReadersController.ReaderCheckoutStatusChange x-validate: null AddressPayloadLegacy: description: Personal address type: object properties: address_line1: description: Address line 1 type: string address_line2: description: Address line 2 type: string city: description: City type: string country: description: Country ISO 3166-1 code type: string region_id: description: Country region id type: number region_name: description: Country region name type: string post_code: description: Postal code type: string landline: description: Landline number type: string first_name: description: First name type: string last_name: description: Last name type: string company: description: Company name type: string required: - address_line1 - city - country - post_code BankAccountPayload: type: object properties: bank_code: description: Bank code type: string branch_code: description: Branch code type: string account_number: description: Account number type: string iban: description: IBAN type: string swift: description: SWIFT code type: string account_type: description: Type of the account. type: string enum: - CURRENT - SAVINGS account_holder_name: description: Account holder name type: string check_digit: description: Check digit type: string primary: description: Determines if this bank account will be primary. Default is false type: boolean status: description: Determines the bank account status. type: string enum: - OPEN account_category: description: Determines if this bank account is business or personal. type: string enum: - PERSONAL - BUSINESS required: - account_holder_name - iban - swift DoingBusinessAsPayloadLegacy: description: Doing Business As information type: object properties: business_name: description: Doing business as name type: string tax_id: description: Doing business as Tax ID type: string vat_id: description: Doing business as VAT ID type: string website: description: Doing business as website type: string email: description: Doing business as email type: string address: $ref: '#/components/schemas/AddressPayloadLegacy' MerchantProfilePayload: description: Account's merchant profile type: object properties: legal_type_id: description: Id of the legal type of the merchant type: number merchant_category_code: description: Merchant category code type: string company_name: description: Company name type: string company_registration_number: description: Company registration number type: string vat_id: description: Vat ID type: string permanent_certificate_access_code: description: Payment certificate access code type: string website: description: Company website type: string nature_and_purpose: description: 'Nature and purpose of the business. Required for the following merchant category codes: 5999, 7392, 8999, 5694, 5969, 7299, 7399' type: string mobile_phone: description: Mobile number type: string address: $ref: '#/components/schemas/AddressPayloadLegacy' doing_business_as: type: object properties: business_name: description: Doing business as name type: string tax_id: description: Doing business as Tax ID type: string vat_id: description: Doing business as Vat ID type: string website: description: Doing business as website type: string email: description: Doing business as email type: string address: $ref: '#/components/schemas/AddressPayloadLegacy' business_owners: $ref: '#/components/schemas/BusinessOwners' is_test_account: description: Defines if the profile nature is for testing type: boolean required: - legal_type_id - company_registration_number - merchant_category_code - company_name - address MerchantSettingsPayload: type: object properties: payout_period: description: Payout period. type: string enum: - daily - weekly - monthly payout_type: description: Payout type. type: string enum: - SINGLE_PAYMENT payout_on_demand: description: 'If true, the merchant will not receive automatic payouts.' type: boolean payout_on_demand_available: description: 'If true, the merchant will be able to manage payout_on_demand settings' type: string expected_max_transaction_amount: description: Expected maximum amount of a single purchase type: number printers_enabled: description: Printers enabled. type: boolean gross_settlement: description: Gross settlement type: boolean PaymentInstrumentCard: description: Details of the payment card that is saved as a payment instrument. type: object properties: token: description: Unique token identifying the saved payment card for a customer. type: string readOnly: true active: description: 'Indicates whether the payment instrument is active and can be used for payments. To deactivate it, send a `DELETE` request to the resource endpoint.' type: boolean default: true readOnly: true type: description: Type of the payment instrument. type: string enum: - card card: $ref: '#/components/schemas/Card' required: - token - active - type - card PersonalProfilePayloadLegacy: description: Account's personal profile. type: object properties: first_name: description: First name of the user type: string last_name: description: Last name of the user type: string date_of_birth: description: Date of birth type: string format: date mobile_phone: description: Mobile phone number type: string national_id: description: 'National identification id. Country specific. Ex CPF (Brazil), DNI (Spain), PESEL (Poland)' type: string address: $ref: '#/components/schemas/AddressPayloadLegacy' required: - first_name - last_name - date_of_birth - address examples: CreatedReader: summary: A reader that waits for the physical device to acknowledge the pairing. value: id: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 name: Frontdesk status: processing device: identifier: U1DT3NA00-CN model: solo created_at: '2023-05-09T14:50:20.214Z' updated_at: '2023-05-09T14:52:58.714Z' links: UpdateReaderByID: operationId: UpdateReader parameters: id: $response.body#/id description: Update the reader object. This can be used to set a name after using this endpoint to verify the pairing code. DeleteReaderByID: operationId: DeleteReader parameters: id: $response.body#/id description: Delete the reader. requestBodies: BankAccounts: content: application/json: schema: $ref: '#/components/schemas/BankAccountPayload' CheckoutCreate: content: application/json: schema: $ref: '#/components/schemas/CheckoutCreateRequest' examples: Checkout: description: Standard request body for creating a checkout value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase id: 2b79757a-de87-4a2e-90e4-b17c947c730d status: PAID date: '2020-02-29T10:56:56+00:00' merchant_name: John Doe LTD redirect_url: 'https://sumup.com' Checkout3DS: description: Create a 3DS checkout value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase return_url: 'http://example.com/' customer_id: 831ff8d4cd5958ab5670 redirect_url: 'https://mysite.com/completed_purchase' CheckoutAPM: description: Create an Alternative Payment Method checkout value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 redirect_url: 'https://mysite.com/completed_purchase' CheckoutProcess: description: Details of the payment instrument for processing the checkout. content: application/json: schema: $ref: '#/components/schemas/ProcessCheckout' examples: ProcessCard: description: Process a checkout with a card value: payment_type: card installments: 1 mandate: type: recurrent user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36' user_ip: 172.217.169.174 card: type: VISA name: John Doe number: '1234567890123456' expiry_year: '2023' expiry_month: '01' cvv: '123' zip_code: '12345' last_4_digits: '3456' ProcessToken: description: Process a checkout with a token value: payment_type: card installments: 1 token: ba85dfee-c3cf-48a6-84f5-d7d761fbba50 customer_id: MEDKHDTI ProcessBoleto: description: Process a checkout with Boleto value: payment_type: boleto personal_details: email: user@example.com first_name: John last_name: Doe tax_id: 423.378.593-47 address: country: BR city: São Paulo line1: 'Rua Gilberto Sabino, 215' state: SP postal_code: 05425-020 ProcessiDeal: description: Process a checkout with iDeal value: payment_type: ideal personal_details: email: user@example.com first_name: John last_name: Doe address: country: NL ProcessBancontact: description: Process a checkout with Bancontact value: payment_type: bancontact personal_details: email: user@example.com first_name: John last_name: Doe address: country: BE CustomerCreate: description: Details of the customer. content: application/json: schema: $ref: '#/components/schemas/Customer' CustomerUpdate: content: application/json: schema: type: object properties: personal_details: $ref: '#/components/schemas/PersonalDetails' DoingBusinessAsLegacy: content: application/json: schema: $ref: '#/components/schemas/DoingBusinessAsPayloadLegacy' MerchantProfile: content: application/json: schema: $ref: '#/components/schemas/MerchantProfilePayload' MerchantSettings: content: application/json: schema: $ref: '#/components/schemas/MerchantSettingsPayload' PaymentInstrument: content: application/json: schema: $ref: '#/components/schemas/PaymentInstrumentCard' PersonalProfile: content: application/json: schema: $ref: '#/components/schemas/PersonalProfilePayloadLegacy' Refund: content: application/json: schema: description: Optional amount for partial refunds of transactions. type: object properties: amount: description: 'Amount to be refunded. Eligible amount can''t exceed the amount of the transaction and varies based on country and currency. If you do not specify a value, the system performs a full refund of the transaction.' type: number format: float responses: Checkout: description: Created content: application/json: schema: $ref: '#/components/schemas/Checkout' examples: Checkout: description: Standard response body for a successfully created checkout value: checkout_reference: 8ea25ec3-3293-40e9-a165-6d7f3b3073c5 amount: 10.1 currency: EUR merchant_code: MH4H92C7 merchant_country: DE description: My Checkout return_url: 'http://example.com' id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent status: active merchant_code: MH4H92C7 transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '012345' internal_id: 0 Checkout3DS: description: Response body for a successfully created 3DS checkout value: checkout_reference: 8ea25ec3-3293-40e9-a165-6d7f3b3073c5 amount: 10.1 currency: EUR description: My Checkout return_url: 'http://example.com' id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 redirect_url: 'https://mysite.com/completed_purchase' transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '012345' internal_id: 0 CheckoutAPM: description: 'Response body for APMs, including Blik, iDeal, ...' value: checkout_reference: 8ea25ec3-3293-40e9-a165-6d7f3b3073c5 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: My Checkout return_url: 'http://example.com' id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING date: '2021-06-29T11:08:36.000+00:00' merchant_name: My company merchant_country: DE redirect_url: 'https://sumup.com' purpose: CHECKOUT transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '012345' internal_id: 0 CheckoutList: description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/CheckoutSuccess' CheckoutRetrieve: description: OK content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' CheckoutProcess: description: OK content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' examples: CheckoutSuccessCard: description: Successfully processed checkout with a card value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase return_url: 'http://example.com' id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: '2020-02-29T10:56:56+00:00' valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent status: active merchant_code: MH4H92C7 transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '053201' internal_id: 1763892018 transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 CheckoutSuccessToken: description: Successfully processed checkout with a token value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase with token id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: '2020-02-29T10:56:56+00:00' transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_name: Sample Merchant redirect_url: 'https://mysite.com/completed_purchase' customer_id: 831ff8d4cd5958ab5670 payment_instrument: token: e76d7e5c-9375-4fac-a7e7-b19dc5302fbc transactions: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 merchant_code: MH4H92C7 vat_amount: 6 tip_amount: 3 entry_mode: CUSTOMER_ENTRY auth_code: '053201' internal_id: 1763892018 CheckoutSuccessBoleto: description: Successfully processed checkout with Boleto value: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: BRL merchant_code: MH4H92C7 description: Boleto checkout id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: '2021-07-06T12:34:02.000+00:00' merchant_name: Sample shop boleto: barcode: '34191090081790614310603072340007886840000000200' url: 'https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto' redirect_url: 'https://website.com' purpose: CHECKOUT transactions: - id: debd2986-9852-4e86-8a8e-7ea9c87dd679 transaction_code: TEN3E696NP merchant_code: MH4H92C9 amount: 10.1 vat_amount: 6 tip_amount: 3 currency: BRL timestamp: '2021-07-06T12:34:16.460+00:00' status: PENDING payment_type: BOLETO entry_mode: BOLETO installments_count: 1 internal_id: 1763892018 CheckoutSuccessiDeal: description: Successfully processed checkout with iDeal value: next_step: url: 'https://r3.girogate.de/ti/simideal' method: GET payload: tx: '961473700' rs: ILnaUeQTKJ184fVrjGILrLjePX9E4rmz cs: c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 full: 'https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5' mechanism: - browser CheckoutSuccessBancontact: description: Successfully processed checkout with Bancontact value: next_step: url: 'https://r3.girogate.de/ti/simbcmc' method: GET payload: tx: '624788471' rs: 5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB cs: 697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc full: 'https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc' mechanism: - browser CheckoutProcessAccepted: description: Accepted content: application/json: schema: $ref: '#/components/schemas/CheckoutAccepted' Customer: description: Created content: application/json: schema: $ref: '#/components/schemas/Customer' PaymentInstrumentList: description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/PaymentInstrumentResponse' PersonalProfileLegacy: description: OK content: application/json: schema: $ref: '#/components/schemas/PersonalProfileLegacy' Transaction: description: OK content: application/json: schema: $ref: '#/components/schemas/TransactionFull' NoBodyResponse: description: No Content ErrorNotAuthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Token: description: The access token is invalid or has expired. value: error_message: invalid access token error_code: NOT_AUTHORIZED Not_Authorized_Token: description: The access token is valid but the application is not authorized. value: error_message: NOT_AUTHORIZED error_code: NOT_AUTHORIZED Missing_Token: description: No access token is provided. value: message: access token required error_code: NOT_AUTHORIZED ErrorForbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: description: You do not have required scopes for making this request. value: error_message: request_not_allowed error_code: FORBIDDEN status_code: '403' ErrorNotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not_Found: description: The identified resource is not found on the server. value: error_code: NOT_FOUND message: Resource not found ErrorConflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: Checkout_Processed: description: The identified checkout resource is already processed. value: error_code: CHECKOUT_PROCESSED message: Checkout is already processed CompatErrorResponse: description: Error response for compat API calls. content: application/json: schema: $ref: '#/components/schemas/CompatError' ListMemberships: description: Returns a list of Membership objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Membership' total_count: type: integer example: 3 required: - total_count - items ListMembers: description: Returns a list of Member objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Member' total_count: type: integer example: 3 required: - items ListRoles: description: Returns a list of Role objects. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Role' required: - items 404NotFound: description: | No user with the specified ID exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryClient' code: $ref: '#/components/schemas/ErrorCodeNotFound' 500InternalServerError: description: | An internal server error occurred. content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: category: $ref: '#/components/schemas/ErrorCategoryServer' code: $ref: '#/components/schemas/ErrorCodeInternalServerError' 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. tags: - name: Checkouts description: | Accept payments from your end users by adding the Checkouts model to your platform. SumUp supports standard and single payment 3DS checkout flows. The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a checkout and then processing the checkout. x-core-objects: - $ref: '#/components/schemas/Checkout' - name: Customers description: | Allow your regular customers to save their information with the Customers model. This will prevent re-entering payment instrument information for recurring payments on your platform. Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers. x-core-objects: - $ref: '#/components/schemas/Customer' - name: Transactions description: | Retrieve details for a specific transaction by it’s `id` or any other required query parameter, or list all transactions related to the merchant account. - name: Payouts description: | The Payouts model will allow you to track funds you’ve received from SumUp. You can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint. x-core-objects: - $ref: '#/components/schemas/FinancialPayouts' - name: Receipts description: The Receipts model obtains receipt-like details for specific transactions. x-core-objects: - $ref: '#/components/schemas/Receipt' - name: Merchant description: Manage merchant profile. x-core-objects: - $ref: '#/components/schemas/MerchantAccount' - name: Subaccounts description: Endpoints for managing merchant sub-accounts (operators). x-deprecation-notice: 'Subaccounts API is deprecated, please use [Members](https://developer.sumup.com/api/members) API instead to manage your account members.' x-core-objects: - $ref: '#/components/schemas/Operator' - name: Members description: Endpoints to manage account members. Members are users that have membership within merchant accounts. x-core-objects: - $ref: '#/components/schemas/Member' x-beta: true - name: Memberships description: Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles. x-core-objects: - $ref: '#/components/schemas/Membership' x-beta: true - name: Roles description: 'Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.' x-core-objects: - $ref: '#/components/schemas/Role' x-beta: true - name: Merchants description: Merchant account represents a single business entity at SumUp. x-core-objects: - $ref: '#/components/schemas/Merchant' - name: Readers description: A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments. x-core-objects: - $ref: '#/components/schemas/Reader'