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.' 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: The request is invalid for the submitted query parameters. 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 security: - apiKey: [] - oauth2: [] tags: - Checkouts x-codegen: method_name: list_available_payment_methods x-scopes: [] /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: Details for creating a checkout resource. required: true 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 valid_until: '2020-02-29T10:56:56+00:00' 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: Returns the created checkout resource. 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: The request body is invalid. 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: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '403': description: The request isn't sufficiently authorized to create a checkout. 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: A checkout already exists for the provided unique parameters. 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: Returns a list of checkout resources. content: application/json: schema: type: array items: $ref: '#/components/schemas/CheckoutSuccess' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' 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: Returns the requested checkout resource. content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '404': description: The requested resource does not exist. 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. required: true 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' 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: Returns the checkout resource after a processing attempt. 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: Returns the next required action for asynchronous checkout processing. content: application/json: schema: $ref: '#/components/schemas/CheckoutAccepted' '400': description: The request body is invalid for processing the checkout. 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: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '404': description: The requested resource does not exist. 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: The request conflicts with the current state of the resource. 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: Returns the checkout object after successful deactivation. 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: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '404': description: The requested resource does not exist. 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: The request conflicts with the current state of the resource. 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. required: true content: application/json: schema: $ref: '#/components/schemas/Customer' responses: '201': description: Returns the customer resource. content: application/json: schema: $ref: '#/components/schemas/Customer' '400': description: The request body is invalid. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorExtended' - type: object properties: instance: type: string error_code: type: string error_message: type: string examples: Missing_Customer_ID: description: The required customer identifier is missing. value: instance: 32a44c6c-85d3-49e8-86bf-a5bba98c4621 error_code: INVALID error_message: customer_id '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '403': description: The request is authenticated but not permitted for this operation. 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: A customer with the provided identifier already exists. 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: Returns the customer resource. content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '403': description: The request is authenticated but not permitted for this operation. 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: The requested resource does not exist. 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: Customer fields to update. required: true content: application/json: schema: type: object properties: personal_details: $ref: '#/components/schemas/PersonalDetails' responses: '200': description: Returns the customer resource. content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '403': description: The request is authenticated but not permitted for this operation. 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: The requested resource does not exist. 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: Returns the list of saved payment instruments for the customer. content: application/json: schema: type: array items: $ref: '#/components/schemas/PaymentInstrumentResponse' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '403': description: The request is authenticated but not permitted for this operation. 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: The requested resource does not exist. 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: Returns an empty response body when the operation succeeds. '400': description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Request: description: The request cannot be processed. value: error_code: INVALID_REQUEST message: bad request '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '403': description: The request is authenticated but not permitted for this operation. 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: The requested resource does not exist. 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: Optional amount for partial refunds. 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: Returns an empty response body when the operation succeeds. '404': description: The requested resource does not exist. 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: The transaction cannot be refunded due to business constraints. 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 Not_Enough_Balance: description: The merchant balance does not allow performing the refund. value: error_code: NOT_ENOUGH_BALANCE message: Not enough available balance to perform the operation at the moment 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: Returns the requested transaction resource. content: application/json: schema: $ref: '#/components/schemas/TransactionFull' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '404': description: The requested resource does not exist. 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: Returns the requested transaction resource. content: application/json: schema: $ref: '#/components/schemas/TransactionFull' '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '404': description: The requested resource does not exist. 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: $ref: '#/components/schemas/PaymentType' - name: 'entry_modes[]' in: query description: Filters the returned results by the specified list of entry modes. required: false schema: type: array items: $ref: '#/components/schemas/EntryMode' - 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: Returns a page of transaction history items. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/TransactionHistory' links: type: array items: $ref: '#/components/schemas/TransactionsHistoryLink' '400': description: The request is invalid for the submitted query parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Parameter: description: A request parameter has an invalid value. value: message: Validation error error_code: INVALID '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' 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: $ref: '#/components/schemas/PaymentType' - 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: Returns a page of transaction history items. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/TransactionHistory' links: type: array items: $ref: '#/components/schemas/TransactionsHistoryLink' '400': description: The request is invalid for the submitted query parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Parameter: description: A request parameter has an invalid value. value: message: Validation error error_code: INVALID '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' deprecated: true security: - apiKey: [] - oauth2: - transactions.history tags: - Transactions x-codegen: method_name: list_deprecated x-scopes: - transactions.history '/v1.0/merchants/{merchant_code}/payouts': get: operationId: ListPayoutsV1 summary: List payouts description: Lists ordered payouts for the merchant account. 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: Returns the list of payouts for the requested period. content: application/json: schema: $ref: '#/components/schemas/FinancialPayouts' '400': description: The request is invalid for the submitted query parameters. content: application/json: schema: type: array items: $ref: '#/components/schemas/ErrorExtended' examples: Missing_Required_Dates: description: Required date filters are missing. value: - error_code: MISSING message: 'Validation error: required' param: start_date - error_code: MISSING message: 'Validation error: required' param: end_date '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' 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 account. 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: Returns the list of payouts for the requested period. content: application/json: schema: $ref: '#/components/schemas/FinancialPayouts' '400': description: The request is invalid for the submitted query parameters. content: application/json: schema: type: array items: $ref: '#/components/schemas/ErrorExtended' examples: Missing_Required_Dates: description: Required date filters are missing. value: - error_code: MISSING message: 'Validation error: required' param: start_date - error_code: MISSING message: 'Validation error: required' param: end_date '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' 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 '/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: Returns receipt details for the requested transaction. content: application/json: schema: $ref: '#/components/schemas/Receipt' '400': description: The request is invalid for the submitted parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid_Merchant_Code: description: The provided merchant code is invalid. value: message: is not a valid merchant code error_code: INVALID '401': description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' '404': description: The requested transaction event does not exist for the provided transaction. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Event_Not_Found: description: The provided transaction event ID cannot be found for this transaction. value: message: No such tx event (ID=9567461191) for transaction 4ffb8dfc-7f2b-413d-a497-2ad00766585e error_code: NOT_FOUND 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' '401': description: Authentication failed or missing required scope. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/unauthorized' title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. 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: Operator creation was forbidden. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/forbidden' title: Forbidden status: 403 detail: You do not have permission to perform this action. 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' '401': description: Authentication failed or missing required scope. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/unauthorized' title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. 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/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. 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: [] /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 - name: resource.parent.id in: query description: |- Filter memberships by the parent of the resource the membership is in. When filtering by parent both `resource.parent.id` and `resource.parent.type` must be present. Pass explicit null to filter for resources without a parent. schema: type: string nullable: true - name: resource.parent.type in: query description: |- Filter memberships by the parent of the resource the membership is in. When filtering by parent both `resource.parent.id` and `resource.parent.type` must be present. Pass explicit null to filter for resources without a parent. schema: allOf: - $ref: '#/components/schemas/ResourceType' nullable: true - name: roles in: query description: Filter the returned memberships by role. schema: type: array items: type: string example: - role_employee - role_accountant explode: true style: form 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 '400': description: Invalid query parameter combination. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '401': description: Authentication failed or missing required scope. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/unauthorized' title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '404': description: Merchant not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. '429': description: Too many invitations were sent to that user and the rate limit was exceeded. The Retry-After header indicates when the client can retry. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/too-many-requests' title: Too Many Requests status: 429 detail: Too many requests were sent. Please try again later. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '403': description: Cannot change password for managed user. Password was already used before. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/forbidden' title: Forbidden status: 403 detail: You do not have permission to perform this action. '404': description: Merchant or member not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. '409': description: Cannot update member as some data conflict with existing members. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/conflict' title: Conflict status: 409 detail: The request conflicts with the current state of the resource. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '404': description: Merchant not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '404': description: Merchant not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '404': description: Merchant not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: The requested Merchant does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Merchant documentation url: 'https://developer.sumup.com/tools/models/merchant' security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: get x-permissions: - merchant_read x-scopes: - user.profile - user.profile_readonly '/v1/merchants/{merchant_code}/persons': get: operationId: ListPersons summary: List Persons description: Returns a list of persons related to the merchant. parameters: - name: version in: query description: | The version of the resource. At the moment, the only supported value is `latest`. When provided and the requested resource's `change_status` is pending, the resource will be returned with all pending changes applied. When no changes are pending the resource is returned as is. The `change_status` in the response body will reflect the current state of the resource. schema: type: string examples: - latest - name: merchant_code in: path description: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A responses: '200': description: Returns a list of persons for a valid merchant identifier. content: application/json: schema: $ref: '#/components/schemas/ListPersonsResponseBody' '404': description: The requested Merchant does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: | An internal server error occurred. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Persons documentation url: 'https://developer.sumup.com/tools/models/merchant#persons' security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: list_persons x-permissions: - persons_read x-scopes: - user.profile - user.profile_readonly '/v1/merchants/{merchant_code}/persons/{person_id}': get: operationId: GetPerson summary: Retrieve a Person description: Returns a single person related to the merchant. parameters: - name: version in: query description: | The version of the resource. At the moment, the only supported value is `latest`. When provided and the requested resource's `change_status` is pending, the resource will be returned with all pending changes applied. When no changes are pending the resource is returned as is. The `change_status` in the response body will reflect the current state of the resource. schema: type: string examples: - latest - name: merchant_code in: path description: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - name: person_id in: path description: Person ID required: true schema: type: string example: pers_5AKFHN2KSK8D3TS79DJE3P3A2Z x-go-type: merchants.PersonID x-go-type-import: path: github.com/sumup/merchants/internal/domain/merchants responses: '200': description: Returns a Person for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Person' '404': description: The requested Person does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: | An internal server error occurred. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Persons documentation url: 'https://developer.sumup.com/tools/models/merchant#persons' security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: get_person x-permissions: - persons_read x-scopes: - user.profile - user.profile_readonly '/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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A 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 '401': description: Authentication failed or missing required scope. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/unauthorized' title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A requestBody: required: true content: application/json: schema: type: object properties: pairing_code: $ref: '#/components/schemas/ReaderPairingCode' name: $ref: '#/components/schemas/ReaderName' metadata: $ref: '#/components/schemas/Metadata' 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. '400': description: The request is invalid. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/bad-request' title: Bad Request status: 400 detail: Request validation failed. '404': description: There's no pending reader for the submitted pairing code. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. '409': description: The Reader is not in a pending state. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/conflict' title: Conflict status: 409 detail: The request conflicts with the current state of the resource. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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 exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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. '404': description: The requested Reader resource does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. security: - apiKey: [] - oauth2: - readers.write tags: - Readers x-codegen: method_name: delete 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: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - 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' metadata: $ref: '#/components/schemas/Metadata' responses: '200': description: Returns the updated Reader object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Reader' '403': description: The request isn't sufficiently authorized to modify the reader. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/forbidden' title: Forbidden status: 403 detail: You do not have permission to perform this action. '404': description: The requested Reader resource does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: 'https://developer.sumup.com/problem/not-found' title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. 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 started 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 example: MC0X0ABC - name: reader_id in: path description: The unique identifier of the Reader required: true schema: type: string 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' application/problem+json: example: detail: Bad Request status: 400 title: Bad Request type: 'https://developer.sumup.com/problem/bad-request' schema: $ref: '#/components/schemas/Problem' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutError' application/problem+json: example: detail: Unauthorized status: 401 title: Unauthorized type: 'https://developer.sumup.com/problem/unauthorized' schema: $ref: '#/components/schemas/Problem' '404': description: Response when given reader is not found content: application/json: schema: $ref: '#/components/schemas/NotFound' application/problem+json: example: detail: The requested resource doesn't exist or does not belong to you. status: 404 title: Requested resource couldn't be found. type: 'https://developer.sumup.com/problem/not-found' schema: $ref: '#/components/schemas/Problem' '422': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutUnprocessableEntity' application/problem+json: example: detail: Validation failed status: 422 title: Unprocessable Entity type: 'https://developer.sumup.com/problem/validation-error' schema: $ref: '#/components/schemas/Problem' 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. callbacks: {} 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}/status': get: operationId: GetReaderStatus summary: Get a Reader Status description: | Provides the last known status for a Reader. This endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state). Supported States * `IDLE` – Reader ready for next transaction * `SELECTING_TIP` – Waiting for tip input * `WAITING_FOR_CARD` – Awaiting card insert/tap * `WAITING_FOR_PIN` – Waiting for PIN entry * `WAITING_FOR_SIGNATURE` – Waiting for customer signature * `UPDATING_FIRMWARE` – Firmware update in progress Device Status * `ONLINE` – Device connected and operational * `OFFLINE` – Device disconnected (last state persisted) **Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher. parameters: - name: merchant_code in: path description: Merchant Code required: true schema: type: string example: MC0X0ABC - name: reader_id in: path description: The unique identifier of the Reader required: true schema: type: string example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 responses: '200': description: Response with the device status. content: application/json: schema: $ref: '#/components/schemas/StatusResponse' '400': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/BadRequest' application/problem+json: example: detail: Bad Request status: 400 title: Bad Request type: 'https://developer.sumup.com/problem/bad-request' schema: $ref: '#/components/schemas/Problem' '401': description: Response when given merchant's token is invalid content: application/json: schema: $ref: '#/components/schemas/Unauthorized' application/problem+json: example: detail: Unauthorized status: 401 title: Unauthorized type: 'https://developer.sumup.com/problem/unauthorized' schema: $ref: '#/components/schemas/Problem' '404': description: Response when given reader is not found content: application/json: schema: $ref: '#/components/schemas/NotFound' application/problem+json: example: detail: The requested resource doesn't exist or does not belong to you. status: 404 title: Requested resource couldn't be found. type: 'https://developer.sumup.com/problem/not-found' schema: $ref: '#/components/schemas/Problem' callbacks: {} security: - apiKey: [] - oauth2: - readers.read tags: - Readers x-codegen: method_name: get_status x-permissions: - readers_view x-scopes: - readers.read '/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 example: MC0X0ABC - name: reader_id in: path description: The unique identifier of the Reader required: true schema: type: string 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' application/problem+json: example: detail: Bad Request status: 400 title: Bad Request type: 'https://developer.sumup.com/problem/bad-request' schema: $ref: '#/components/schemas/Problem' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateError' application/problem+json: example: detail: Unauthorized status: 401 title: Unauthorized type: 'https://developer.sumup.com/problem/unauthorized' schema: $ref: '#/components/schemas/Problem' '404': description: Response when given reader is not found content: application/json: schema: $ref: '#/components/schemas/NotFound' application/problem+json: example: detail: The requested resource doesn't exist or does not belong to you. status: 404 title: Requested resource couldn't be found. type: 'https://developer.sumup.com/problem/not-found' schema: $ref: '#/components/schemas/Problem' '422': description: Response when given params (or one of them) are invalid content: application/json: schema: $ref: '#/components/schemas/CreateReaderTerminateUnprocessableEntity' application/problem+json: example: detail: The device is offline. status: 422 title: Reader Offline type: 'https://developer.sumup.com/problem/reader-offline' schema: $ref: '#/components/schemas/Problem' callbacks: {} 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 EntryModesFilter: name: 'entry_modes[]' in: query description: Filters the returned results by the specified list of entry modes. required: false schema: type: array items: $ref: '#/components/schemas/EntryMode' 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: $ref: '#/components/schemas/PaymentType' 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: 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 title: Address Legacy 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 type: $ref: '#/components/schemas/CardType' required: - name - number - expiry_month - expiry_year - cvv - type title: Card 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: $ref: '#/components/schemas/CardType' title: Card Response Device: description: Details of the device used to create the transaction. type: object properties: name: description: Device name. type: string example: m0xx system_name: description: Device OS. type: string example: Android model: description: Device model. type: string example: GT-I9300 system_version: description: Device OS version. type: string example: '4.3' uuid: description: Device UUID. type: string example: 3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2 title: Device ElvCardAccount: description: Details of the ELV card account associated with the transaction. type: object properties: sort_code: description: ELV card sort code. type: string example: '87096214' last_4_digits: description: ELV card account number last 4 digits. type: string example: '5674' sequence_no: description: ELV card sequence number. type: integer example: 1 iban: description: ELV IBAN. type: string example: DE60870962140012345674 title: ELV Card Account Checkout: description: 'Core checkout resource returned by the Checkouts API. A checkout is created before payment processing and then updated as payment attempts, redirects, and resulting transactions are attached to it.' type: object properties: checkout_reference: description: 'Merchant-defined reference for the checkout. Use it to correlate the SumUp checkout with your own order, cart, subscription, or payment attempt in your systems.' type: string maxLength: 90 amount: description: 'Amount to be charged to the payer, expressed in major units.' type: number format: float example: 10.1 currency: $ref: '#/components/schemas/Currency' merchant_code: description: Merchant account that receives the payment. type: string example: MH4H92C7 description: description: 'Short merchant-defined description shown in SumUp tools and reporting. Use it to make the checkout easier to recognize in dashboards, support workflows, and reconciliation.' type: string return_url: description: Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout. type: string format: uri id: description: Unique SumUp identifier of the checkout resource. type: string example: 4e425463-3e1b-431d-83fa-1e51c2925e99 readOnly: true status: description: 'Current high-level state of the checkout. `PENDING` means the checkout exists but is not yet completed, `PAID` means a payment succeeded, `FAILED` means the latest processing attempt failed, and `EXPIRED` means the checkout can no longer be processed.' type: string enum: - PENDING - FAILED - PAID - EXPIRED 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: 'Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time.' type: string format: date-time example: '2020-02-29T10:56:56+00:00' nullable: true customer_id: description: Merchant-scoped identifier of the customer associated with the checkout. Use it when storing payment instruments or reusing saved customer context for recurring and returning-payer flows. type: string example: 831ff8d4cd5958ab5670 mandate: $ref: '#/components/schemas/MandateResponse' transactions: description: Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history. type: array items: allOf: - $ref: '#/components/schemas/TransactionBase' - $ref: '#/components/schemas/TransactionCheckoutInfo' uniqueItems: true title: Checkout CheckoutCreateRequest: description: 'Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here.' type: object properties: checkout_reference: description: Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems. type: string maxLength: 90 amount: description: 'Amount to be charged to the payer, expressed in major units.' type: number format: float currency: $ref: '#/components/schemas/Currency' merchant_code: description: Merchant account that should receive the payment. type: string example: MH4H92C7 description: description: Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout. type: string return_url: description: Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout. type: string format: uri customer_id: description: Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer. type: string purpose: description: Business purpose of the checkout. Use `CHECKOUT` for a standard payment and `SETUP_RECURRING_PAYMENT` when collecting consent and payment details for future recurring charges. type: string default: CHECKOUT enum: - CHECKOUT - SETUP_RECURRING_PAYMENT valid_until: description: 'Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time.' type: string format: date-time example: '2020-02-29T10:56:56+00:00' nullable: true redirect_url: description: 'URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for [APMs](https://developer.sumup.com/online-payments/apm/introduction) and recommended for card checkouts that may require [3DS](https://developer.sumup.com/online-payments/features/3ds). If it is omitted, the [Payment Widget](https://developer.sumup.com/online-payments/checkouts) can render the challenge in an iframe instead of using a full-page redirect.' type: string example: 'https://mysite.com/completed_purchase' required: - checkout_reference - amount - currency - merchant_code title: Checkout Create Request ProcessCheckout: description: 'Request body for attempting payment on an existing checkout. The required companion fields depend on the selected `payment_type`, for example card details, saved-card data, or payer information required by a specific payment method.' type: object properties: payment_type: description: Payment method used for this processing attempt. It determines which additional request fields are required. type: string enum: - card - boleto - ideal - blik - bancontact - google_pay - apple_pay 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' google_pay: description: Raw `PaymentData` object received from Google Pay. Send the Google Pay response payload as-is. type: object example: apiVersionMinor: 0 apiVersion: 2 paymentMethodData: description: Visa •••• 1111 tokenizationData: type: PAYMENT_GATEWAY token: token-data type: CARD info: cardNetwork: VISA cardDetails: '1111' apple_pay: description: Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is. type: object example: token: paymentData: data: si2xuT2ArQo689SfE-long-token signature: MIAGCSqGSIb3DQEHA-long-signature header: publicKeyHash: PWfjDi3TSwgZ20TY/A7f3V6J/1rhHyRDCspbeljM0io= ephemeralPublicKey: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaBtz7UN2MNV0qInJVEEhXy10PU0KfO6KxFjXm93oKWL6lCsxZZGDl/EKioUHVSlKgpsKGin0xvgldfxeJVgy0g== transactionId: 62e0568bc9258e9d0e059d745650fc8211d05ef7a7a1589a6411bf9b12cdfd04 version: EC_v1 paymentMethod: displayName: MasterCard 8837 network: MasterCard type: debit transactionIdentifier: 62E0568BC9258E9D0E059D745650FC8211D05EF7A7A1589A6411BF9B12CDFD04 token: description: Saved-card token to use instead of raw card details when processing with a previously stored payment instrument. type: string customer_id: description: Customer identifier associated with the saved payment instrument. Required when `token` is provided. type: string personal_details: $ref: '#/components/schemas/PersonalDetails' required: - payment_type title: Process Checkout CheckoutSuccess: description: 'Checkout resource returned after a synchronous processing attempt. In addition to the base checkout fields, it can include the resulting transaction identifiers and any newly created payment instrument token.' 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: URL where the payer is redirected after a redirect-based payment or SCA flow completes. type: string example: 'https://mysite.com/completed_purchase' payment_instrument: description: Details of the saved payment instrument created or reused during checkout processing. type: object properties: token: description: Token value type: string example: e76d7e5c-9375-4fac-a7e7-b19dc5302fbc title: Checkout Success CheckoutAccepted: description: 'Response returned when checkout processing requires an additional payer action, such as a 3DS challenge or a redirect to an external payment method page.' type: object properties: next_step: description: Instructions for the next action the payer or client must take. type: object properties: url: description: URL to open or submit in order to continue processing. type: string example: 'https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A' method: description: HTTP method to use when following the next step. type: string example: POST redirect_url: description: Merchant URL where the payer returns after the external flow finishes. type: string example: 'https://mysite.com/completed_purchase' mechanism: description: 'Allowed presentation mechanisms for the next step. `iframe` means the flow can be embedded, while `browser` means it can be completed through a full-page redirect.' type: array items: type: string enum: - iframe - browser payload: description: Parameters required to complete the next step. The exact keys depend on the payment provider and flow type. 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' title: Checkout Accepted Customer: description: Saved customer details. 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 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 title: Error Problem: description: |- A RFC 9457 problem details object. Additional properties specific to the problem type may be present. type: object properties: type: description: A URI reference that identifies the problem type. type: string format: uri example: 'https://developer.sumup.com/problem/not-found' title: description: 'A short, human-readable summary of the problem type.' type: string example: Requested resource couldn't be found. status: description: The HTTP status code generated by the origin server for this occurrence of the problem. type: integer example: 404 detail: description: A human-readable explanation specific to this occurrence of the problem. type: string example: The requested resource doesn't exist or does not belong to you. instance: description: A URI reference that identifies the specific occurrence of the problem. type: string format: uri additionalProperties: true required: - type title: Problem ErrorExtended: description: Error payload with the invalid parameter reference. 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 title: Error Extended 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 title: Error Forbidden 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: description: List of violated validation constraints. type: array items: type: object properties: message: type: string reference: type: string title: Details Error Event: description: High-level transaction event details. 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: description: Amount of the event. type: number format: float timestamp: description: Date and time of the transaction event. type: string format: date-time 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 title: Event FinancialPayouts: description: List of payout summaries. 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 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 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 title: Link TransactionsHistoryLink: description: Hypermedia link used for transaction history pagination. type: object properties: rel: description: Relation. type: string example: next href: description: Location. type: string example: limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending required: - rel - href title: Transactions History Link MandatePayload: description: Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments. type: object properties: type: description: Type of mandate to create for the saved payment instrument. type: string example: recurrent enum: - recurrent user_agent: description: Browser or client user agent observed when consent was collected. type: string example: '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: description: IP address of the payer when the mandate was accepted. type: string example: 172.217.169.174 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 title: Mandate Payload MandateResponse: description: Details of the mandate linked to the saved payment instrument. type: object properties: type: description: Type of mandate stored for the checkout or payment instrument. type: string status: description: Current lifecycle status of the mandate. type: string example: active enum: - active - inactive merchant_code: description: Merchant account for which the mandate is valid. type: string example: MH4H92C7 example: type: recurrent status: active merchant_code: MH4H92C7 title: Mandate Response 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: $ref: '#/components/schemas/CardType' 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' title: Payment Instrument Response 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' title: Personal Details Product: description: Purchase product. type: object properties: name: description: Product name. type: string example: Purchase reader for merchant with code ME3FCAVF price_label: description: Product description. type: string price: description: Product price. type: number format: decimal example: 100 vat_rate: description: VAT percentage. type: number format: decimal single_vat_amount: description: VAT amount for a single product. type: number format: decimal price_with_vat: description: Product price incl. VAT. type: number format: decimal vat_amount: description: VAT amount. type: number format: decimal quantity: description: Product quantity. type: integer example: 1 total_price: description: Quantity x product price. type: number format: decimal example: 100 total_with_vat: description: Total price incl. VAT. type: number format: decimal title: Product Receipt: description: Receipt details for a transaction. type: object properties: transaction_data: $ref: '#/components/schemas/ReceiptTransaction' merchant_data: $ref: '#/components/schemas/ReceiptMerchantData' emv_data: description: EMV-specific metadata returned for card-present payments. type: object acquirer_data: description: Acquirer-specific metadata related to the card authorization. type: object properties: tid: type: string authorization_code: type: string return_code: type: string local_time: type: string title: Receipt ReceiptEvent: description: Transaction event details as rendered on the receipt. 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: description: Amount of the event. type: string format: double timestamp: description: Date and time of the transaction event. type: string format: date-time receipt_no: description: Receipt number associated with the event. type: string title: Receipt Event ReceiptCard: description: Payment card details displayed on the receipt. type: object properties: last_4_digits: description: Card last 4 digits. type: string type: description: Card Scheme. type: string title: Receipt Card ReceiptReader: description: Card reader details displayed on the receipt. type: object properties: code: description: Reader serial number. type: string type: description: Reader type. type: string title: Receipt Reader ReceiptMerchantData: description: Receipt merchant data type: object properties: merchant_profile: description: Merchant profile details displayed on the receipt. type: object properties: merchant_code: type: string example: MH4H92C7 business_name: type: string company_registration_number: type: string vat_id: type: string website: type: string email: type: string language: type: string address: type: object properties: address_line1: type: string address_line2: type: string city: type: string country: type: string country_en_name: type: string country_native_name: type: string region_name: type: string post_code: type: string landline: type: string locale: description: Locale used for rendering localized receipt fields. type: string title: Receipt Merchant Data ReceiptTransaction: description: Transaction information. type: object properties: transaction_code: description: Transaction code. type: string transaction_id: $ref: '#/components/schemas/TransactionID' merchant_code: description: Merchant 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_reader: $ref: '#/components/schemas/ReceiptReader' card: $ref: '#/components/schemas/ReceiptCard' installments_count: description: Number of installments. type: integer process_as: description: Debit/Credit. type: string example: CREDIT enum: - CREDIT - DEBIT products: description: Products type: array items: type: object properties: name: description: Product name type: string example: Coffee description: description: Product description type: string price: description: Product price type: string format: double example: '150.0' vat_rate: description: VAT rate type: string format: double example: '0.0' single_vat_amount: description: VAT amount for a single product type: string format: double example: '0.0' price_with_vat: description: Product price including VAT type: string format: double example: '150.0' vat_amount: description: VAT amount type: string format: double example: '0.0' quantity: description: Product quantity type: integer format: int64 example: 1 total_price: description: Quantity x product price type: string format: double example: '150.0' total_with_vat: description: Total price including VAT type: string format: double example: '150.0' 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 title: Receipt Transaction TransactionEvent: description: Detailed information about a transaction event. type: object properties: id: $ref: '#/components/schemas/EventID' event_type: $ref: '#/components/schemas/EventType' status: $ref: '#/components/schemas/EventStatus' amount: description: Amount of the event. type: number format: decimal example: 58.8 due_date: description: Date when the transaction event is due to occur. type: string format: date example: '2020-05-25' date: description: Date when the transaction event occurred. type: string format: date example: '2020-05-25' installment_number: description: 'Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`.' type: integer example: 1 timestamp: description: Date and time of the transaction event. type: string format: date-time example: '2020-05-25T10:49:42.784Z' title: Transaction Event 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: $ref: '#/components/schemas/PaymentType' installments_count: description: Current number of the installment for deferred payments. type: integer minimum: 1 title: Transaction Base TransactionCheckoutInfo: description: Checkout-specific fields associated with a transaction. 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: $ref: '#/components/schemas/EntryMode' 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 format: int64 example: 1763892018 title: Transaction Checkout Info TransactionMixinHistory: description: Additional transaction fields used by history and detailed views. 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 title: Transaction Mixin History TransactionHistory: description: Transaction entry returned in history listing responses. 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: $ref: '#/components/schemas/CardType' payout_date: description: Payout date (if paid out at once). type: string format: date example: '2019-08-28' payout_type: description: Payout type. type: string example: BANK_ACCOUNT enum: - BANK_ACCOUNT - PREPAID_CARD refunded_amount: description: Total refunded amount. type: number format: decimal example: 0 title: Transaction History PaymentType: description: Payment type used for the transaction. type: string enum: - CASH - POS - ECOM - RECURRING - BITCOIN - BALANCE - MOTO - BOLETO - DIRECT_DEBIT - APM - UNKNOWN title: Payment Type EntryMode: description: Entry mode of the payment details. type: string enum: - BOLETO - SOFORT - IDEAL - BANCONTACT - EPS - MYBANK - SATISPAY - BLIK - P24 - GIROPAY - PIX - QR_CODE_PIX - APPLE_PAY - GOOGLE_PAY - PAYPAL - TWINT - NONE - CHIP - MANUAL_ENTRY - CUSTOMER_ENTRY - MAGSTRIPE_FALLBACK - MAGSTRIPE - DIRECT_DEBIT - CONTACTLESS - MOTO - CONTACTLESS_MAGSTRIPE - N/A title: Entry Mode CardType: description: Issuing card network of the payment card used for the transaction. type: string enum: - ALELO - AMEX - CONECS - CUP - DINERS - DISCOVER - EFTPOS - ELO - ELV - GIROCARD - HIPERCARD - INTERAC - JCB - MAESTRO - MASTERCARD - PLUXEE - SWILE - TICKET - VISA - VISA_ELECTRON - VISA_VPAY - VPAY - VR - UNKNOWN title: Card Type TransactionFull: description: 'Full transaction resource with checkout, payout, and event details.' allOf: - $ref: '#/components/schemas/TransactionBase' - $ref: '#/components/schemas/TransactionCheckoutInfo' - $ref: '#/components/schemas/TransactionMixinHistory' - type: object properties: foreign_transaction_id: description: External/foreign transaction id (passed by clients). type: string example: J13253253x1 client_transaction_id: description: Client transaction id. type: string example: 'urn:sumup:pos:sale:MNKKNGST:1D4E3B2D-111D-48D7-9AF0-832DAEF63DD7;2' username: description: Email address of the registered user (merchant) to whom the payment is made. type: string format: email fee_amount: description: Transaction SumUp total fee amount. type: number format: decimal example: 8 lat: $ref: '#/components/schemas/Lat' lon: $ref: '#/components/schemas/Lon' horizontal_accuracy: $ref: '#/components/schemas/HorizontalAccuracy' merchant_id: description: SumUp merchant internal Id. type: integer format: int64 example: 136902 device_info: $ref: '#/components/schemas/Device' simple_payment_type: description: Simple name of the payment type. type: string enum: - CASH - CC_SIGNATURE - ELV - ELV_WITHOUT_SIGNATURE - CC_CUSTOMER_ENTERED - MANUAL_ENTRY - EMV - RECURRING - BALANCE - MOTO - BOLETO - APM - BITCOIN - CARD verification_method: description: Verification method used for the transaction. type: string enum: - none - signature - offline PIN - online PIN - offline PIN + signature - na card: $ref: '#/components/schemas/CardResponse' elv_account: $ref: '#/components/schemas/ElvCardAccount' local_time: description: Local date and time of the creation of the transaction. type: string format: date-time payout_date: description: The date of the payout. type: string format: date example: '2019-08-28' payout_type: description: Payout type for the transaction. type: string enum: - BANK_ACCOUNT - PREPAID_CARD process_as: description: Debit/Credit. type: string example: CREDIT enum: - CREDIT - DEBIT 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: type: object properties: rate: description: VAT rate. type: number format: decimal example: 0.045 net: description: NET amount of products having this VAT rate applied. type: number format: decimal example: 1.36 vat: description: VAT amount of this rate applied. type: number format: decimal example: 0.06 gross: description: Gross amount of products having this VAT rate applied. type: number format: decimal example: 1.42 transaction_events: description: Detailed list of events related to the transaction. type: array items: $ref: '#/components/schemas/TransactionEvent' simple_status: description: |- High-level status of the transaction from the merchant's perspective. - `PENDING`: The payment has been initiated and is still being processed. A final outcome is not available yet. - `SUCCESSFUL`: The payment was completed successfully. - `PAID_OUT`: The payment was completed successfully and the funds have already been included in a payout to the merchant. - `FAILED`: The payment did not complete successfully. - `CANCELLED`: The payment was cancelled or reversed and is no longer payable or payable to the merchant. - `CANCEL_FAILED`: An attempt to cancel or reverse the payment was not completed successfully. - `REFUNDED`: The payment was refunded in full or in part. - `REFUND_FAILED`: An attempt to refund the payment was not completed successfully. - `CHARGEBACK`: The payment was subject to a chargeback. - `NON_COLLECTION`: The amount could not be collected from the merchant after a chargeback or related adjustment. type: string enum: - SUCCESSFUL - PAID_OUT - CANCEL_FAILED - CANCELLED - CHARGEBACK - FAILED - REFUND_FAILED - REFUNDED - NON_COLLECTION - PENDING links: description: List of hyperlinks for accessing related resources. type: array items: $ref: '#/components/schemas/Link' events: description: Compact list of events related to the transaction. type: array items: $ref: '#/components/schemas/Event' 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 title: Transaction Full 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 - COP - CZK - DKK - EUR - GBP - HRK - HUF - NOK - PLN - RON - SEK - USD title: Currency EventType: description: Type of the transaction event. type: string enum: - PAYOUT - CHARGE_BACK - REFUND - PAYOUT_DEDUCTION title: Event Type EventStatus: description: |- Status of the transaction event. Not every value is used for every event type. - `PENDING`: The event has been created but is not final yet. Used for events that are still being processed and whose final outcome is not known yet. - `SCHEDULED`: The event is planned for a future payout cycle but has not been executed yet. This applies to payout events before money is actually sent out. - `RECONCILED`: The underlying payment has been matched with settlement data and is ready to continue through payout processing, but the funds have not been paid out yet. This applies to payout events. - `PAID_OUT`: The payout event has been completed and the funds were included in a merchant payout. - `REFUNDED`: A refund event has been accepted and recorded in the refund flow. This is the status returned for refund events once the transaction amount is being or has been returned to the payer. - `SUCCESSFUL`: The event completed successfully. Use this as the generic terminal success status for event types that do not expose a more specific business outcome such as `PAID_OUT` or `REFUNDED`. - `FAILED`: The event could not be completed. Typical examples are a payout that could not be executed or an event that was rejected during processing. type: string enum: - FAILED - PAID_OUT - PENDING - RECONCILED - REFUNDED - SCHEDULED - SUCCESSFUL title: Event Status EventID: description: Unique ID of the transaction event. type: integer format: int64 title: Event ID HorizontalAccuracy: description: Indication of the precision of the geographical position received from the payment terminal. type: number format: float title: Horizontal Accuracy 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 title: Latitude 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 title: Longitude TransactionID: description: Unique ID of the transaction. type: string title: Transaction ID 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 Attributes: description: Object attributes that are modifiable only by SumUp applications. type: object example: {} additionalProperties: true 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://backstage.sumup.net/docs/default/Component/merchants/merchant/#addresses' required: - country 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 pattern: '^[A-Z]{2}$' PersonalIdentifier: type: object properties: ref: description: The unique reference for the personal identifier type. type: string example: br.cpf maxLength: 32 value: description: The company identifier value. type: string example: 847.060.136-90 maxLength: 128 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 Metadata: description: 'Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.' type: object example: {} additionalProperties: true maxProperties: 64 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: uri alias: description: | A user-facing name of the merchant account for use in dashboards and other user-facing applications. For customer-facing business name see `merchant.business_profile`. type: string default_currency: description: | Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account. type: string example: EUR maxLength: 3 minLength: 3 readOnly: true default_locale: description: |- Merchant's default locale, represented as a BCP47 [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646) language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1](https://www.iso.org/iso-639-language-code) language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1](https://www.iso.org/iso-3166-country-codes.html) country code in uppercase, separated by a dash. For example, en-US or fr-CA. In multilingual countries this is the merchant's preferred locale out of those, that are officially spoken in the country. In a countries with a single official language this will match the official language. type: string example: de-DE maxLength: 5 minLength: 2 sandbox: description: True if the merchant is a sandbox for testing. type: boolean example: false meta: $ref: '#/components/schemas/Meta' classic: $ref: '#/components/schemas/ClassicMerchantIdentifiers' version: $ref: '#/components/schemas/Version' change_status: $ref: '#/components/schemas/ChangeStatus' - $ref: '#/components/schemas/Timestamps' externalDocs: description: Merchant documentation url: 'https://developer.sumup.com/tools/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: 150 minLength: 1 merchant_category_code: description: | The merchant category code for the account as specified by [ISO18245](https://www.iso.org/standard/33365.html). MCCs are used to classify businesses based on the goods or services they provide. type: string example: '1532' pattern: '^[0-9]{4}$' legal_type: $ref: '#/components/schemas/LegalType' address: $ref: '#/components/schemas/Address' trading_address: $ref: '#/components/schemas/Address' identifiers: $ref: '#/components/schemas/CompanyIdentifiers' phone_number: $ref: '#/components/schemas/PhoneNumber' website: description: | HTTP(S) URL of the company's website. type: string format: uri examples: - 'https://www.sumup.com' maxLength: 255 nullable: true attributes: $ref: '#/components/schemas/Attributes' externalDocs: description: Company documentation url: 'https://developer.sumup.com/tools/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: Example Coffee maxLength: 150 minLength: 1 dynamic_descriptor: description: | The descriptor is the text that your customer sees on their bank account statement. The more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks). type: string example: Example Coffee maxLength: 30 minLength: 1 pattern: '^[a-zA-Z0-9 \-+\''_.]{0,30}$' website: description: The business's publicly available website. type: string format: uri example: 'https://example.com' maxLength: 255 email: description: A publicly available email address. type: string example: contact@example.com maxLength: 255 phone_number: $ref: '#/components/schemas/PhoneNumber' address: $ref: '#/components/schemas/Address' branding: $ref: '#/components/schemas/Branding' 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: 16 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 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' metadata: $ref: '#/components/schemas/Metadata' service_account_id: description: |- Identifier of the system-managed service account associated with this reader. Present only for readers that are already paired. This field is currently in beta and may change. type: string format: uuid x-beta: true 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](https://developer.sumup.com/api/readers/delete-reader) 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 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 InstallmentsTooLow: description: Error returned when installments is not within the allowed range. value: errors: installments: - is invalid ReaderBusy: description: Error returned when a checkout was requested in the last 60 seconds. value: errors: detail: There is a pending checkout for the device. type: READER_BUSY 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 CreateReaderCheckoutError: description: Error description type: object properties: errors: type: object properties: detail: description: Error message type: string type: description: Error code type: string required: - type required: - errors title: CreateReaderCheckoutError StatusResponse: description: Status of a device type: object properties: data: type: object properties: battery_level: description: Battery level percentage type: number format: float example: 10.5 maximum: 100 minimum: 0 battery_temperature: description: Battery temperature in Celsius type: integer example: 35 connection_type: description: Type of connection used by the device type: string example: Wi-Fi enum: - btle - edge - gprs - lte - umts - usb - Wi-Fi firmware_version: description: Firmware version of the device type: string example: 3.3.3.21 last_activity: description: Timestamp of the last activity from the device type: string format: date-time example: '2025-09-25T15:20:00Z' state: description: Latest state of the device type: string example: IDLE enum: - IDLE - SELECTING_TIP - WAITING_FOR_CARD - WAITING_FOR_PIN - WAITING_FOR_SIGNATURE - UPDATING_FIRMWARE status: description: Status of a device type: string example: ONLINE enum: - ONLINE - OFFLINE required: - status example: data: battery_level: 10 battery_temperature: 35 connection_type: Wi-Fi firmware_version: 3.3.3.21 last_activity: '2025-09-25T15:20:00Z' state: IDLE status: ONLINE required: - data title: StatusResponse CreateReaderTerminateUnprocessableEntity: description: Unprocessable entity type: object properties: errors: type: object additionalProperties: true 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 CreateReaderTerminateError: description: Error description type: object properties: errors: type: object properties: detail: description: Error message type: string type: description: Error code type: string required: - type required: - errors title: CreateReaderTerminateError BadRequest: description: 400 Bad Request type: object properties: errors: type: object properties: detail: description: Fuller message giving context to error type: string type: description: Key indicating type of error type: string enum: - INVALID_BEARER_TOKEN - INVALID_USER_AGENT - NOT_ENOUGH_UNPAID_PAYOUTS - DUPLICATE_HEADERS required: - type example: errors: detail: Bad request type: INVALID_BEARER_TOKEN required: - errors title: BadRequest 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 required: - client_transaction_id example: data: client_transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 required: - data title: CreateReaderCheckoutResponse Unauthorized: description: 401 Unauthorized type: object properties: errors: type: object properties: detail: description: Fuller message giving context to error type: string type: description: 'Key indicating type of error. Present only for typed 401 responses (e.g. invalid token, invalid password). Absent for generic unauthorized responses.' type: string enum: - INVALID_ACCESS_TOKEN - INVALID_PASSWORD required: - detail example: errors: detail: Unauthorized required: - errors title: Unauthorized CreateReaderCheckoutRequest: description: Reader Checkout type: object properties: aade: description: | Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol. When such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider. type: object properties: provider_id: description: The identifier of the AADE signature provider. type: string example: '123' signature: description: The base64 encoded signature of the transaction data. type: string example: QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5 signature_data: description: The string containing the signed transaction data. type: string example: B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039 required: - provider_id - signature - signature_data affiliate: description: | Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction. type: object nullable: true 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 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 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 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 required: - app_id - key - foreign_transaction_id title: Affiliate 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 description: description: Description of the checkout to be shown in the Merchant Sales type: string 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. Omit if the merchant country does support installments. Otherwise, the checkout will be rejected. type: integer example: 1 minimum: 1 nullable: true 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' 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 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 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 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 value: description: Integer value of the amount. type: integer example: 1000 minimum: 0 required: - currency - minor_unit - value title: Money example: aade: provider_id: '123' signature: QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5 signature_data: B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039 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 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 id: description: Unique identifier for the event. type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 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 merchant_code: description: The merchant code associated with the transaction. type: string example: M1234567 status: description: The current status of the transaction. type: string example: successful enum: - successful - failed transaction_id: description: 'The transaction id. Deprecated: use `client_transaction_id` instead.' type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 deprecated: true required: - client_transaction_id - merchant_code - status timestamp: description: Timestamp of the event. type: string format: date-time example: '2023-10-05T14:48:00Z' required: - id - event_type - payload - timestamp title: ReaderCheckoutStatusChange NotFound: description: 404 Not Found type: object properties: errors: type: object properties: detail: description: Fuller message giving context to error type: string required: - detail example: errors: detail: Not Found required: - errors title: NotFound 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 title: Country Details 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 title: Time Offset Details 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_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 title: Address Payload Legacy 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 title: Business Owners 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_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 title: Address With Details BankAccountPayload: description: Bank account details used when creating or updating a payout account. 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 title: Bank Account Payload 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' title: Doing Business As Payload Legacy 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: description: Doing-business-as details associated with the merchant profile. 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 title: Merchant Profile Payload MerchantSettingsPayload: description: Merchant payout and settlement configuration. 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 title: Merchant Settings Payload PaymentInstrumentCard: description: Details of the payment card that is saved as a payment instrument. type: object properties: type: description: Type of the payment instrument. type: string enum: - card card: $ref: '#/components/schemas/Card' required: - type - card title: Payment Instrument 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 title: Personal Profile Payload Legacy BankAccount: description: Bank account details used for merchant payouts. 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: description: Name of the bank account holder. 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 title: Bank Account 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: description: Indicates whether the profile data is complete. type: boolean title: Personal Profile Legacy 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: description: Bank account details to be created or updated. content: application/json: schema: $ref: '#/components/schemas/BankAccountPayload' CheckoutCreate: required: true description: Details for creating a checkout resource. 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 valid_until: '2020-02-29T10:56:56+00:00' 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: required: true 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' 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: required: true description: Details of the customer. content: application/json: schema: $ref: '#/components/schemas/Customer' CustomerUpdate: required: true description: Customer fields to update. content: application/json: schema: type: object properties: personal_details: $ref: '#/components/schemas/PersonalDetails' DoingBusinessAsLegacy: description: Doing-business-as details for merchant profile updates. content: application/json: schema: $ref: '#/components/schemas/DoingBusinessAsPayloadLegacy' MerchantProfile: description: Merchant profile fields to create or update. content: application/json: schema: $ref: '#/components/schemas/MerchantProfilePayload' MerchantSettings: description: Merchant settings fields to create or update. content: application/json: schema: $ref: '#/components/schemas/MerchantSettingsPayload' PaymentInstrument: description: Payment instrument details. content: application/json: schema: $ref: '#/components/schemas/PaymentInstrumentCard' PersonalProfile: description: Personal profile details to create or update. content: application/json: schema: $ref: '#/components/schemas/PersonalProfilePayloadLegacy' Refund: description: Optional amount for partial refunds. 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: Returns the created checkout resource. 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: Returns a list of checkout resources. content: application/json: schema: type: array items: $ref: '#/components/schemas/CheckoutSuccess' CheckoutRetrieve: description: Returns the requested checkout resource. content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' CheckoutProcess: description: Returns the checkout resource after a processing attempt. 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: Returns the next required action for asynchronous checkout processing. content: application/json: schema: $ref: '#/components/schemas/CheckoutAccepted' Customer: description: Returns the customer resource. content: application/json: schema: $ref: '#/components/schemas/Customer' PaymentInstrumentList: description: Returns the list of saved payment instruments for the customer. content: application/json: schema: type: array items: $ref: '#/components/schemas/PaymentInstrumentResponse' Transaction: description: Returns the requested transaction resource. content: application/json: schema: $ref: '#/components/schemas/TransactionFull' NoBodyResponse: description: Returns an empty response body when the operation succeeds. ErrorNotAuthorized: description: The request is not authorized. content: application/json: schema: $ref: '#/components/schemas/Problem' examples: Problem_Details: description: Unauthorized response returned by API gateway. value: detail: Unauthorized. status: 401 title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: 'https://developer.sumup.com/problem/unauthorized' ErrorForbidden: description: The request is authenticated but not permitted for this operation. 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: The requested resource does not exist. 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: The request conflicts with the current state of the resource. 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 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 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: |- Checkouts represent online payment sessions that you create before attempting to charge a payer. A checkout captures the payment intent, such as the amount, currency, merchant, and optional customer or redirect settings, and then moves through its lifecycle as you process it. Use this tag to: - create a checkout before collecting or confirming payment details - process the checkout with a card, saved card, wallet, or supported alternative payment method - retrieve or list checkouts to inspect their current state and associated payment attempts - deactivate a checkout that should no longer be used Typical workflow: - create a checkout with the order amount, currency, and merchant information - process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts) - retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record Checkouts are used to initiate and orchestrate online payments. Transactions remain the authoritative record of the resulting payment outcome. 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: |- Transactions represent completed or attempted payment operations processed for a merchant account. A transaction contains the core payment result, such as the amount, currency, payment method, creation time, and current high-level status. In addition to the main payment outcome, a transaction can contain related events that describe what happened after the original payment attempt. These events provide visibility into the financial lifecycle of the transaction, for example: - `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant - `REFUND`: money returned to the payer - `CHARGE_BACK`: money reversed after the original payment - `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback From an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to: - list transactions for reporting, reconciliation, and customer support workflows - retrieve a single transaction when you need the latest payment details - inspect `simple_status` for the current merchant-facing outcome of the payment - inspect `events` or `transaction_events` when you need refund, payout, or chargeback history Typical workflow: - create and process payments through the Checkouts endpoints - use the Transactions endpoints to read the resulting payment records - use the returned statuses and events to update your own order, accounting, or support systems - 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: 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'