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 example: - id: apple_pay - id: blik 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. To use the [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the `hosted_checkout.enabled` to `true`. 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 HostedCheckout: description: Create a checkout with a SumUp-hosted payment page x-beta: true value: checkout_reference: b50pr914-6k0e-3091-a592-890010285b3d amount: 12 currency: EUR merchant_code: MCXXXXXX description: A sample checkout hosted_checkout: enabled: true 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' 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' 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' HostedCheckout: description: Response body for a checkout with a SumUp-hosted payment page value: checkout_reference: b50pr914-6k0e-3091-a592-890010285b3d amount: 12 currency: EUR merchant_code: MCXXXXXX merchant_country: DE merchant_name: Sample Shop description: A sample checkout id: 64553e20-3f0e-49e4-8af3-fd0eca86ce91 status: PENDING date: 2000-01-01T12:49:24.899+00:00 purpose: CHECKOUT hosted_checkout: enabled: true hosted_checkout_url: https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676 transactions: [] '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' example: - checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: 2020-02-29T10:56:56+00:00 '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/{checkout_id}: parameters: - name: checkout_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' example: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase 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 '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' 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' 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 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.2/checkouts/{checkout_id}/apple-pay-session: put: operationId: CreateApplePaySession summary: Create an Apple Pay session description: | Creates an Apple Pay merchant session for the specified checkout. Use this endpoint after the customer selects Apple Pay and before calling `ApplePaySession.completeMerchantValidation(...)` in the browser. SumUp validates the merchant session request and returns the Apple Pay session object that your frontend should pass to Apple's JavaScript API. parameters: - name: checkout_id in: path description: Unique ID of the checkout resource. required: true schema: type: string requestBody: description: The data needed to create an apple pay session for a checkout. content: application/json: schema: type: object properties: context: description: the context to create this apple pay session. type: string format: hostname example: example.com target: description: The target url to create this apple pay session. type: string format: uri example: https://apple-pay-gateway-cert.apple.com/paymentservices/startSession required: - context - target responses: '200': description: | Successful request. Returns the Apple Pay merchant session object that should be forwarded to the Apple Pay JS SDK to complete merchant validation and continue the payment flow. content: application/json: schema: type: object example: displayName: Test Account domainName: pay.sumup.com epochTimestamp: 1775323532665 expiresAt: 1775327132665 merchantIdentifier: 7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB merchantSessionIdentifier: SSH92CC412E5FCF4FAB88684914C953C0D4_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24 nonce: a968a2bf operationalAnalyticsIdentifier: Test Account:7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB pspId: 7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB retries: 0 signature: '400': description: Bad Request content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - type: array description: List of error messages. items: $ref: '#/components/schemas/Error' example: error_code: INVALID message: Bad Request '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: [] tags: - Checkouts x-codegen: method_name: create_apple_pay_session x-scopes: [] /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 required: - instance - error_code - error_message properties: instance: type: string error_code: type: string error_message: type: string examples: Missing_Customer_ID: description: The required customer identifier is missing. value: error_code: INVALID message: Validation error param: 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 /v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds: parameters: - name: merchant_code in: path description: Merchant code of the account that owns the payment to refund. required: true schema: type: string example: MH4H92C7 - name: transaction_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: example: amount: 5 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 example: 5 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` - `transaction_code` - `foreign_transaction_id` - `client_transaction_id` parameters: - name: merchant_code in: path description: Merchant code of the account whose transaction should be retrieved. 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: 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' example: 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' '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 /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 description: Merchant code of the account whose transaction history should be listed. 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 example: - merchant@example.com example: - merchant@example.com - 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' example: - 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 transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 user: merchant@example.com type: PAYMENT payout_date: 2019-08-28 payout_type: BANK_ACCOUNT refunded_amount: 0 links: type: array items: $ref: '#/components/schemas/TransactionsHistoryLink' example: [] example: items: - 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 transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 user: merchant@example.com type: PAYMENT payout_date: 2019-08-28 payout_type: BANK_ACCOUNT refunded_amount: 0 links: [] '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 /v1.0/merchants/{merchant_code}/payouts: get: operationId: ListPayoutsV1 summary: List payouts description: |- Lists payout and payout-deduction records for the specified merchant account within the requested date range. The response can include: - regular payouts (`type = PAYOUT`) - deduction records for refunds, chargebacks, direct debit returns, or balance adjustments Results are sorted by payout date in the requested `order`. parameters: - name: merchant_code in: path description: Merchant code of the account whose payouts should be listed. required: true schema: type: string example: MH4H92C7 - name: start_date in: query description: Start date of the payout period filter, inclusive, in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) `date` format (`YYYY-MM-DD`). required: true schema: type: string format: date example: 2024-02-01 - name: end_date in: query description: End date of the payout period filter, inclusive, in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) `date` format (`YYYY-MM-DD`). Must be greater than or equal to `start_date`. required: true schema: type: string format: date example: 2024-02-29 - name: format in: query description: Response format for the payout list. required: false schema: type: string example: json default: json enum: - json - csv - name: limit in: query description: Maximum number of payout records to return. required: false schema: type: integer example: 10 maximum: 9999 minimum: 1 - name: order in: query description: Sort direction for the returned payouts. required: false schema: type: string example: desc default: asc enum: - asc - desc responses: '200': description: Returns the list of payout and deduction records for the requested period. content: application/json: schema: $ref: '#/components/schemas/FinancialPayouts' example: - amount: 132.45 currency: EUR date: 2024-02-29 fee: 3.12 id: 123456789 reference: payout-2024-02-29 status: SUCCESSFUL transaction_code: TEENSK4W2K type: PAYOUT text/plain: schema: description: CSV-formatted payout export returned when `format=csv`. type: string example: |- id,type,amount,date,currency,fee,status,reference,transaction_code 123456789,PAYOUT,132.45,2024-02-29,EUR,3.12,SUCCESSFUL,payout-2024-02-29,TEENSK4W2K '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 Invalid date range: description: '`start_date` cannot be later than `end_date`.' value: - error_code: INVALID message: negative date range '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 /v1.1/receipts/{transaction_id}: get: operationId: GetReceipt summary: Retrieve receipt details description: Retrieves receipt specific data for a transaction. parameters: - name: transaction_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' example: transaction_data: transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_code: MH4H92C7 amount: '10.10' vat_amount: '6.00' tip_amount: '3.00' currency: EUR timestamp: 2020-02-29T10:56:56.876Z status: SUCCESSFUL payment_type: ECOM entry_mode: CUSTOMER_ENTRY installments_count: 1 process_as: CREDIT merchant_data: merchant_profile: merchant_code: MH4H92C7 acquirer_data: authorization_code: '053201' '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/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' externalDocs: description: Persons documentation url: https://developer.sumup.com/tools/models/merchant#persons security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: list_persons x-permissions: - persons_read x-scopes: - user.profile - user.profile_readonly /v1/merchants/{merchant_code}/persons/{person_id}: get: operationId: GetPerson summary: Retrieve a Person description: Returns a single person related to the merchant. parameters: - name: version in: query description: | The version of the resource. At the moment, the only supported value is `latest`. When provided and the requested resource's `change_status` is pending, the resource will be returned with all pending changes applied. When no changes are pending the resource is returned as is. The `change_status` in the response body will reflect the current state of the resource. schema: type: string examples: - latest - name: merchant_code in: path description: Short unique identifier for the merchant. required: true schema: type: string example: MK10CL2A - name: person_id in: path description: Person ID required: true schema: type: string example: pers_5AKFHN2KSK8D3TS79DJE3P3A2Z x-go-type: merchants.PersonID x-go-type-import: path: github.com/sumup/merchants/internal/domain/merchants responses: '200': description: Returns a Person for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Person' '404': description: The requested Person does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' externalDocs: description: Persons documentation url: https://developer.sumup.com/tools/models/merchant#persons security: - apiKey: [] - oauth2: - user.profile - user.profile_readonly tags: - Merchants x-codegen: method_name: get_person x-permissions: - persons_read x-scopes: - user.profile - user.profile_readonly /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: reader_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: reader_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/{reader_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: reader_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: reader_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: reader_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: checkout_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' 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' 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 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 example: - merchant@example.com schema: type: array items: type: string format: email example: - merchant@example.com 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 HostedCheckout: description: Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response. type: object properties: enabled: description: Whether the checkout should include a SumUp-hosted payment page. type: boolean example: true required: - enabled title: Hosted Checkout 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 example: f00a8f74-b05d-4605-bd73-2a901bae5802 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 example: Purchase return_url: description: Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout. type: string format: uri example: http://example.com 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 example: PENDING 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' hosted_checkout_url: description: URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout. type: string format: uri example: https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676 readOnly: true 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' example: - 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' 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 example: f00a8f74-b05d-4605-bd73-2a901bae5802 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 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 example: Purchase return_url: description: Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout. type: string format: uri example: http://example.com/ 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 example: 831ff8d4cd5958ab5670 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 hosted_checkout: $ref: '#/components/schemas/HostedCheckout' 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 example: card 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 example: 1 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 example: ba85dfee-c3cf-48a6-84f5-d7d761fbba50 customer_id: description: Customer identifier associated with the saved payment instrument. Required when `token` is provided. type: string example: MEDKHDTI 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 example: PaReq: eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw== MD: b1a536c0-29b9-11eb-adc1-0242ac120002 TermUrl: https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment additionalProperties: type: string 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 example: Resource not found error_code: description: Platform code for the error. type: string example: NOT_FOUND 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 example: request_not_allowed error_code: description: Platform code for the error. type: string example: FORBIDDEN status_code: description: HTTP status code for the error. type: string example: '403' title: Error Forbidden DetailsError: description: Error message structure. type: object properties: title: description: Short title of the error. type: string example: Bad Request details: description: Details of the error. type: string example: One or more of the parameters are invalid. status: description: The status code. type: number example: 400 failed_constraints: description: List of violated validation constraints. type: array items: type: object properties: message: type: string reference: type: string example: - message: Currency must also be specified when filtering by amount reference: currency 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: Ordered list of payout and payout-deduction records. type: array items: $ref: '#/components/schemas/FinancialPayout' title: Financial Payouts FinancialPayout: description: |- A single payout-related record. A record can represent either: - an actual payout sent to the merchant (`type = PAYOUT`) - a deduction applied against merchant funds for a refund, chargeback, direct debit return, or balance adjustment type: object properties: id: description: Unique identifier of the payout-related record. type: integer example: 123456789 type: description: High-level payout record category. type: string example: PAYOUT enum: - PAYOUT - CHARGE_BACK_DEDUCTION - REFUND_DEDUCTION - DD_RETURN_DEDUCTION - BALANCE_DEDUCTION amount: description: Amount of the payout or deduction in major units. type: number format: float example: 132.45 date: description: Payout date associated with the record, in `YYYY-MM-DD` format. type: string format: date example: 2024-02-29 currency: description: Three-letter ISO 4217 currency code of the payout. type: string example: EUR fee: description: Fee amount associated with the payout record, in major units. type: number format: float example: 3.12 status: description: Merchant-facing outcome of the payout record. type: string example: SUCCESSFUL enum: - SUCCESSFUL - FAILED reference: description: Processor or payout reference associated with the record. type: string example: payout-2024-02-29 transaction_code: description: Transaction code of the original sale associated with the payout or deduction. type: string example: TEENSK4W2K required: - id - type - amount - date - currency - fee - status - reference - transaction_code title: Financial Payout 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 example: {} acquirer_data: description: Acquirer-specific metadata related to the card authorization. type: object example: authorization_code: '053201' return_code: '00' 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 example: transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_code: MH4H92C7 amount: '10.10' vat_amount: '6.00' tip_amount: '3.00' currency: EUR timestamp: 2020-02-29T10:56:56.876Z status: SUCCESSFUL payment_type: ECOM entry_mode: CUSTOMER_ENTRY installments_count: 1 process_as: CREDIT 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: $ref: '#/components/schemas/TransactionStatus' 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' 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 TransactionStatus: description: |- Current status of the transaction. - `PENDING`: The transaction has been created but its final outcome is not known yet. - `SUCCESSFUL`: The transaction completed successfully. - `CANCELLED`: The transaction was cancelled or otherwise reversed before completion. - `FAILED`: The transaction attempt did not complete successfully. - `REFUNDED`: The transaction was refunded in full or in part. type: string enum: - SUCCESSFUL - CANCELLED - FAILED - PENDING - REFUNDED title: Transaction Status 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 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 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 Attributes: description: Object attributes that are modifiable only by SumUp applications. type: object example: {} additionalProperties: true 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/glossary/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/glossary/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' CountryCode: description: | An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This definition users `oneOf` with a two-character string type to allow for support of future countries in client code. type: string examples: - AR - AT - AU - BE - BG - BR - CH - CL - CO - CY - CZ - DE - DK - EE - ES - FI - FR - GB - GR - HU - IE - IT - LT - LU - LV - MT - MX - NL - NO - PE - PL - PT - RO - SE - SI - SK - US maxLength: 2 minLength: 2 PhoneNumber: description: | A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. type: string example: '+420123456789' maxLength: 16 Address: description: |- An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, `city` is `post_town`. In the United States, the top-level administrative unit used in addresses is `state`, whereas in Chile it's `region`. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored. type: object properties: street_address: type: array items: type: string description: The first line of the address. maxLength: 100 example: - Paul-Linke-Ufer 39-40 - 2. Hinterhof maxItems: 2 minItems: 1 post_code: description: | The postal code (aka. zip code) of the address. type: string example: '10999' maxLength: 10 country: $ref: '#/components/schemas/CountryCode' city: description: | The city of the address. type: string example: Berlin maxLength: 60 province: description: | The province where the address is located. This may not be relevant in some countries. type: string example: Ontario maxLength: 60 region: description: | The region where the address is located. This may not be relevant in some countries. type: string example: Baden-Wuerttemberg maxLength: 60 county: description: | A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc. type: string example: Dublin maxLength: 60 autonomous_community: description: | In Spain, an autonomous community is the first sub-national level of political and administrative division. type: string example: Catalonia maxLength: 60 post_town: description: | A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system. type: string example: London maxLength: 60 state: description: | Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil. type: string example: California maxLength: 60 neighborhood: description: | Locality level of the address. Used in countries such as Brazil or Chile. type: string example: Copacabana maxLength: 60 commune: description: | In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile. type: string example: Providencia maxLength: 60 department: description: | A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia. type: string example: Antioquia maxLength: 60 municipality: description: | A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia. type: string example: Medellin maxLength: 60 district: description: | A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal. type: string example: Lisbon maxLength: 60 zip_code: description: | A US system of postal codes used by the United States Postal Service (USPS). type: string example: '94103' maxLength: 10 eircode: description: | A postal address in Ireland. type: string example: D02 X285 maxLength: 10 examples: - street_address: - Paul-Linke-Ufer 39-40 - 2. Hinterhof post_code: '10999' city: Berlin country: DE - street_address: - 156 Avenida Vida Nova - Apto 2 city: Taboão da Serra post_code: '06764045' state: SP neighborhood: Jardim Maria Rosa country: BR externalDocs: description: Address documentation url: https://developer.sumup.com/tools/glossary/merchant#addresses required: - country 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/glossary/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/glossary/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 PersonalIdentifier: type: object properties: ref: description: | The unique reference for the personal identifier type as defined in the country SDK. type: string examples: - br.cpf value: description: | The company identifier value. type: string examples: - 847.060.136-90 maxLength: 30 examples: - ref: br.cpf value: 847.060.136-90 required: - ref - value 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/glossary/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 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: reader_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: reader_id: $response.body#/id description: Delete the reader. requestBodies: 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 HostedCheckout: description: Create a checkout with a SumUp-hosted payment page x-beta: true value: checkout_reference: b50pr914-6k0e-3091-a592-890010285b3d amount: 12 currency: EUR merchant_code: MCXXXXXX description: A sample checkout hosted_checkout: enabled: true 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' Refund: description: Optional amount for partial refunds. content: application/json: example: amount: 5 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 example: 5 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' 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' 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' HostedCheckout: description: Response body for a checkout with a SumUp-hosted payment page value: checkout_reference: b50pr914-6k0e-3091-a592-890010285b3d amount: 12 currency: EUR merchant_code: MCXXXXXX merchant_country: DE merchant_name: Sample Shop description: A sample checkout id: 64553e20-3f0e-49e4-8af3-fd0eca86ce91 status: PENDING date: 2000-01-01T12:49:24.899+00:00 purpose: CHECKOUT hosted_checkout: enabled: true hosted_checkout_url: https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676 transactions: [] CheckoutList: description: Returns a list of checkout resources. content: application/json: schema: type: array items: $ref: '#/components/schemas/CheckoutSuccess' example: - checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING date: 2020-02-29T10:56:56+00:00 CheckoutRetrieve: description: Returns the requested checkout resource. content: application/json: schema: $ref: '#/components/schemas/CheckoutSuccess' example: checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: 10.1 currency: EUR merchant_code: MH4H92C7 description: Purchase 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 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' 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' 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 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' example: 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' 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: 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'