From e0d84dcbe49e7b08027b3c14c70234a57817ad57 Mon Sep 17 00:00:00 2001 From: appscisumup Date: Mon, 3 Aug 2026 16:17:25 +0000 Subject: [PATCH 1/2] chore: synced local 'openapi.json' with remote 'specs/openapi.json' --- openapi.json | 5340 +++++++++++++++++++++++++------------------------- 1 file changed, 2670 insertions(+), 2670 deletions(-) diff --git a/openapi.json b/openapi.json index 04f9652b..eb483fc3 100755 --- a/openapi.json +++ b/openapi.json @@ -1,5 +1,5 @@ { - "openapi": "3.0.1", + "openapi": "3.0.3", "info": { "title": "SumUp REST API", "version": "1.0.0", @@ -15,38 +15,129 @@ "description": "Production server" } ], + "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.\n\nUse this tag to:\n- create a checkout before collecting or confirming payment details\n- process the checkout with a card, saved card, wallet, or supported alternative payment method\n- retrieve or list checkouts to inspect their current state and associated payment attempts\n- deactivate a checkout that should no longer be used\n\nTypical workflow:\n- create a checkout with the order amount, currency, and merchant information\n- process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts)\n- retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record\n\nCheckouts 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.\n\nThis will prevent re-entering payment instrument information for recurring payments on your platform.\n\nDepending on the needs you can allow, creating, listing or deactivating payment instruments \u0026 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.\n\nIn 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:\n- `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant\n- `REFUND`: money returned to the payer\n- `CHARGE_BACK`: money reversed after the original payment\n- `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback\n\nFrom an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to:\n- list transactions for reporting, reconciliation, and customer support workflows\n- retrieve a single transaction when you need the latest payment details\n- inspect `simple_status` for the current merchant-facing outcome of the payment\n- inspect `events` or `transaction_events` when you need refund, payout, or chargeback history\n\nTypical workflow:\n- create and process payments through the Checkouts endpoints\n- use the Transactions endpoints to read the resulting payment records\n- 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.\n\nYou 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": "Readers" + }, + { + "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": "A Merchant represents a single business which can use SumUp products like payment processing.", + "x-core-objects": [ + { + "$ref": "#/components/schemas/Merchant" + } + ] + } + ], "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.", + "tags": [ + "Checkouts" + ], + "x-codegen": { + "method_name": "list_available_payment_methods" + }, + "x-scopes": [], "parameters": [ { - "name": "merchant_code", "in": "path", - "description": "The SumUp merchant code.", + "name": "merchant_code", "required": true, + "description": "The SumUp merchant code.", "schema": { "type": "string", "example": "MH4H92C7" } }, { - "name": "amount", "in": "query", - "description": "The amount for which the payment methods should be eligible, in major units.", + "name": "amount", "required": false, + "description": "The amount for which the payment methods should be eligible, in major units.", "schema": { "type": "number", "example": 9.99 } }, { - "name": "currency", "in": "query", - "description": "The currency for which the payment methods should be eligible.", + "name": "currency", "required": false, + "description": "The currency for which the payment methods should be eligible.", "schema": { "type": "string", "example": "EUR" @@ -63,6 +154,14 @@ "properties": { "available_payment_methods": { "type": "array", + "example": [ + { + "id": "apple_pay" + }, + { + "id": "blik" + } + ], "items": { "type": "object", "required": [ @@ -70,20 +169,12 @@ ], "properties": { "id": { - "description": "The ID of the payment method.", "type": "string", + "description": "The ID of the payment method.", "example": "qr_code_pix" } } - }, - "example": [ - { - "id": "apple_pay" - }, - { - "id": "blik" - } - ] + } } } }, @@ -138,14 +229,7 @@ { "oauth2": [] } - ], - "tags": [ - "Checkouts" - ], - "x-codegen": { - "method_name": "list_available_payment_methods" - }, - "x-scopes": [] + ] } }, "/v0.1/checkouts": { @@ -153,9 +237,30 @@ "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.\n\nFor 3DS checkouts, add the `redirect_url` parameter to your request body schema.\nTo use the [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the `hosted_checkout.enabled` to `true`.\n\nFollow by processing a checkout to charge the provided payment instrument.", + "tags": [ + "Checkouts" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payments", + "checkouts.write" + ] + } + ], + "x-codegen": { + "method_name": "create" + }, + "x-scopes": [ + "payments", + "checkouts.write" + ], "requestBody": { - "description": "Details for creating a checkout resource.", "required": true, + "description": "Details for creating a checkout resource.", "content": { "application/json": { "schema": { @@ -437,7 +542,15 @@ } } } - }, + } + }, + "get": { + "operationId": "ListCheckouts", + "summary": "List checkouts", + "description": "Lists created checkout resources according to the applied `checkout_reference`.", + "tags": [ + "Checkouts" + ], "security": [ { "apiKey": [] @@ -445,25 +558,17 @@ { "oauth2": [ "payments", - "checkouts.write" + "checkouts.read" ] } ], - "tags": [ - "Checkouts" - ], "x-codegen": { - "method_name": "create" + "method_name": "list" }, "x-scopes": [ "payments", - "checkouts.write" - ] - }, - "get": { - "operationId": "ListCheckouts", - "summary": "List checkouts", - "description": "Lists created checkout resources according to the applied `checkout_reference`.", + "checkouts.read" + ], "parameters": [ { "name": "checkout_reference", @@ -523,28 +628,7 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "payments", - "checkouts.read" - ] - } - ], - "tags": [ - "Checkouts" - ], - "x-codegen": { - "method_name": "list" - }, - "x-scopes": [ - "payments", - "checkouts.read" - ] + } } }, "/v0.1/checkouts/{checkout_id}": { @@ -552,8 +636,8 @@ { "name": "checkout_id", "in": "path", - "description": "Unique ID of the checkout resource.", "required": true, + "description": "Unique ID of the checkout resource.", "schema": { "type": "string" } @@ -563,6 +647,27 @@ "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.", + "tags": [ + "Checkouts" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payments", + "checkouts.read" + ] + } + ], + "x-codegen": { + "method_name": "get" + }, + "x-scopes": [ + "payments", + "checkouts.read" + ], "responses": { "200": { "description": "Returns the requested checkout resource.", @@ -627,7 +732,15 @@ } } } - }, + } + }, + "patch": { + "operationId": "UpdateCheckout", + "summary": "Update a checkout", + "description": "Updates an identified checkout resource.", + "tags": [ + "Checkouts" + ], "security": [ { "apiKey": [] @@ -635,28 +748,20 @@ { "oauth2": [ "payments", - "checkouts.read" + "checkouts.write" ] } ], - "tags": [ - "Checkouts" - ], "x-codegen": { - "method_name": "get" + "method_name": "update" }, "x-scopes": [ "payments", - "checkouts.read" - ] - }, - "patch": { - "operationId": "UpdateCheckout", - "summary": "Update a checkout", - "description": "Updates an identified checkout resource.", + "checkouts.write" + ], "requestBody": { - "description": "Details for updating a checkout resource.", "required": true, + "description": "Details for updating a checkout resource.", "content": { "application/json": { "schema": { @@ -739,10 +844,18 @@ } } } - }, - "security": [ - { - "apiKey": [] + } + }, + "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.\n\nFollow this request with `Retrieve a checkout` to confirm its status.", + "tags": [ + "Checkouts" + ], + "security": [ + { + "apiKey": [] }, { "oauth2": [ @@ -751,24 +864,16 @@ ] } ], - "tags": [ - "Checkouts" - ], "x-codegen": { - "method_name": "update" + "method_name": "process" }, "x-scopes": [ "payments", "checkouts.write" - ] - }, - "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.\n\nFollow this request with `Retrieve a checkout` to confirm its status.", + ], "requestBody": { - "description": "Details of the payment instrument for processing the checkout.", "required": true, + "description": "Details of the payment instrument for processing the checkout.", "content": { "application/json": { "schema": { @@ -990,7 +1095,7 @@ "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz", "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5" }, - "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", + "full": "https://r3.girogate.de/ti/simideal?tx=961473700\u0026rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz\u0026cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", "mechanism": [ "browser" ] @@ -1008,7 +1113,7 @@ "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB", "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc" }, - "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", + "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471\u0026rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB\u0026cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", "mechanism": [ "browser" ] @@ -1140,7 +1245,15 @@ } } } - }, + } + }, + "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.", + "tags": [ + "Checkouts" + ], "security": [ { "apiKey": [] @@ -1152,21 +1265,13 @@ ] } ], - "tags": [ - "Checkouts" - ], "x-codegen": { - "method_name": "process" + "method_name": "deactivate" }, "x-scopes": [ "payments", "checkouts.write" - ] - }, - "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.", @@ -1252,28 +1357,7 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "payments", - "checkouts.write" - ] - } - ], - "tags": [ - "Checkouts" - ], - "x-codegen": { - "method_name": "deactivate" - }, - "x-scopes": [ - "payments", - "checkouts.write" - ] + } } }, "/v0.2/checkouts/{checkout_id}/apple-pay-session": { @@ -1281,41 +1365,48 @@ "operationId": "CreateApplePaySession", "summary": "Create an Apple Pay session", "description": "Creates an Apple Pay merchant session for the specified checkout.\n\nUse this endpoint after the customer selects Apple Pay and before calling\n`ApplePaySession.completeMerchantValidation(...)` in the browser.\nSumUp validates the merchant session request and returns the Apple Pay\nsession object that your frontend should pass to Apple's JavaScript API.\n", + "tags": [ + "Checkouts" + ], "parameters": [ { "name": "checkout_id", "in": "path", - "description": "Unique ID of the checkout resource.", "required": true, + "description": "Unique ID of the checkout resource.", "schema": { "type": "string" } } ], + "x-codegen": { + "method_name": "create_apple_pay_session" + }, + "x-scopes": [], "requestBody": { "description": "The data needed to create an apple pay session for a checkout.", "content": { "application/json": { "schema": { "type": "object", + "required": [ + "context", + "target" + ], "properties": { "context": { - "description": "the context to create this apple pay session.", "type": "string", + "description": "the context to create this apple pay session.", "format": "hostname", "example": "example.com" }, "target": { - "description": "The target url to create this apple pay session.", "type": "string", + "description": "The target url to create this apple pay session.", "format": "uri", "example": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession" } - }, - "required": [ - "context", - "target" - ] + } } } } @@ -1339,7 +1430,7 @@ "operationalAnalyticsIdentifier": "Test Account:7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB", "pspId": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB", "retries": 0, - "signature": "" + "signature": "\u003capple-pay-signature\u003e" } } } @@ -1396,14 +1487,7 @@ { "oauth2": [] } - ], - "tags": [ - "Checkouts" - ], - "x-codegen": { - "method_name": "create_apple_pay_session" - }, - "x-scopes": [] + ] } }, "/v0.1/customers": { @@ -1411,9 +1495,30 @@ "operationId": "CreateCustomer", "summary": "Create a customer", "description": "Creates a new saved customer resource which you can later manipulate and save payment instruments to.", + "tags": [ + "Customers" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payment_instruments", + "customers.write" + ] + } + ], + "x-codegen": { + "method_name": "create" + }, + "x-scopes": [ + "payment_instruments", + "customers.write" + ], "requestBody": { - "description": "Details of the customer.", "required": true, + "description": "Details of the customer.", "content": { "application/json": { "schema": { @@ -1537,28 +1642,7 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "payment_instruments", - "customers.write" - ] - } - ], - "tags": [ - "Customers" - ], - "x-codegen": { - "method_name": "create" - }, - "x-scopes": [ - "payment_instruments", - "customers.write" - ] + } } }, "/v0.1/customers/{customer_id}": { @@ -1566,8 +1650,8 @@ { "name": "customer_id", "in": "path", - "description": "Unique ID of the saved customer resource.", "required": true, + "description": "Unique ID of the saved customer resource.", "schema": { "type": "string" } @@ -1577,6 +1661,27 @@ "operationId": "GetCustomer", "summary": "Retrieve a customer", "description": "Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation.", + "tags": [ + "Customers" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payment_instruments", + "customers.read" + ] + } + ], + "x-codegen": { + "method_name": "get" + }, + "x-scopes": [ + "payment_instruments", + "customers.read" + ], "responses": { "200": { "description": "Returns the customer resource.", @@ -1649,7 +1754,15 @@ } } } - }, + } + }, + "put": { + "operationId": "UpdateCustomer", + "summary": "Update a customer", + "description": "Updates an identified saved customer resource's personal details.\n\nThe request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.", + "tags": [ + "Customers" + ], "security": [ { "apiKey": [] @@ -1657,28 +1770,20 @@ { "oauth2": [ "payment_instruments", - "customers.read" + "customers.write" ] } ], - "tags": [ - "Customers" - ], "x-codegen": { - "method_name": "get" + "method_name": "update" }, "x-scopes": [ "payment_instruments", - "customers.read" - ] - }, - "put": { - "operationId": "UpdateCustomer", - "summary": "Update a customer", - "description": "Updates an identified saved customer resource's personal details.\n\nThe request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.", + "customers.write" + ], "requestBody": { - "description": "Customer fields to update.", "required": true, + "description": "Customer fields to update.", "content": { "application/json": { "schema": { @@ -1764,28 +1869,7 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "payment_instruments", - "customers.write" - ] - } - ], - "tags": [ - "Customers" - ], - "x-codegen": { - "method_name": "update" - }, - "x-scopes": [ - "payment_instruments", - "customers.write" - ] + } } }, "/v0.1/customers/{customer_id}/payment-instruments": { @@ -1793,8 +1877,8 @@ { "name": "customer_id", "in": "path", - "description": "Unique ID of the saved customer resource.", "required": true, + "description": "Unique ID of the saved customer resource.", "schema": { "type": "string" } @@ -1804,6 +1888,27 @@ "operationId": "ListPaymentInstruments", "summary": "List payment instruments", "description": "Lists all payment instrument resources that are saved for an identified customer.", + "tags": [ + "Customers" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payment_instruments", + "customers.read" + ] + } + ], + "x-codegen": { + "method_name": "list_payment_instruments" + }, + "x-scopes": [ + "payment_instruments", + "customers.read" + ], "responses": { "200": { "description": "Returns the list of saved payment instruments for the customer.", @@ -1879,28 +1984,7 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "payment_instruments", - "customers.read" - ] - } - ], - "tags": [ - "Customers" - ], - "x-codegen": { - "method_name": "list_payment_instruments" - }, - "x-scopes": [ - "payment_instruments", - "customers.read" - ] + } } }, "/v0.1/customers/{customer_id}/payment-instruments/{token}": { @@ -1908,8 +1992,8 @@ { "name": "customer_id", "in": "path", - "description": "Unique ID of the saved customer resource.", "required": true, + "description": "Unique ID of the saved customer resource.", "schema": { "type": "string" } @@ -1917,8 +2001,8 @@ { "name": "token", "in": "path", - "description": "Unique token identifying the card saved as a payment instrument resource.", "required": true, + "description": "Unique token identifying the card saved as a payment instrument resource.", "schema": { "type": "string" } @@ -1928,6 +2012,27 @@ "operationId": "DeactivatePaymentInstrument", "summary": "Deactivate a payment instrument", "description": "Deactivates an identified card payment instrument resource for a customer.", + "tags": [ + "Customers" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payment_instruments", + "customers.write" + ] + } + ], + "x-codegen": { + "method_name": "deactivate_payment_instrument" + }, + "x-scopes": [ + "payment_instruments", + "customers.write" + ], "responses": { "204": { "description": "Returns an empty response body when the operation succeeds." @@ -2012,28 +2117,7 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "payment_instruments", - "customers.write" - ] - } - ], - "tags": [ - "Customers" - ], - "x-codegen": { - "method_name": "deactivate_payment_instrument" - }, - "x-scopes": [ - "payment_instruments", - "customers.write" - ] + } } }, "/v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds": { @@ -2051,8 +2135,8 @@ { "name": "transaction_id", "in": "path", - "description": "Unique ID of the transaction.", "required": true, + "description": "Unique ID of the transaction.", "schema": { "type": "string" } @@ -2062,6 +2146,27 @@ "operationId": "RefundTransaction", "summary": "Refund a transaction", "description": "Refunds an identified transaction either in full or partially.", + "tags": [ + "Transactions" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "payments", + "refunds.write" + ] + } + ], + "x-codegen": { + "method_name": "refund" + }, + "x-scopes": [ + "payments", + "refunds.write" + ], "requestBody": { "description": "Optional amount for partial refunds.", "content": { @@ -2070,13 +2175,13 @@ "amount": 5 }, "schema": { - "description": "Optional amount for partial refunds of transactions.", "type": "object", + "description": "Optional amount for partial refunds of transactions.", "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", + "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.", "example": 5 } } @@ -2209,35 +2314,35 @@ } } } - }, + } + } + }, + "/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:\n- `id`\n- `transaction_code`\n- `foreign_transaction_id`\n- `client_transaction_id`", + "tags": [ + "Transactions" + ], "security": [ { "apiKey": [] }, { "oauth2": [ - "payments", - "refunds.write" + "transactions.history", + "transactions.read" ] } ], - "tags": [ - "Transactions" - ], "x-codegen": { - "method_name": "refund" + "method_name": "get" }, "x-scopes": [ - "payments", - "refunds.write" - ] - } - }, - "/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:\n- `id`\n- `transaction_code`\n- `foreign_transaction_id`\n- `client_transaction_id`", + "transactions.history", + "transactions.read" + ], "parameters": [ { "name": "merchant_code", @@ -2351,7 +2456,17 @@ } } } - }, + } + } + }, + "/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.", + "tags": [ + "Transactions" + ], "security": [ { "apiKey": [] @@ -2363,23 +2478,13 @@ ] } ], - "tags": [ - "Transactions" - ], "x-codegen": { - "method_name": "get" + "method_name": "list" }, "x-scopes": [ "transactions.history", "transactions.read" - ] - } - }, - "/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", @@ -2406,11 +2511,11 @@ "description": "Specifies the order in which the returned results are displayed.", "schema": { "type": "string", - "default": "ascending", "enum": [ "ascending", "descending" - ] + ], + "default": "ascending" } }, { @@ -2426,19 +2531,19 @@ "in": "query", "description": "Filters the returned results by user email.", "required": false, + "example": [ + "merchant@example.com" + ], "schema": { "type": "array", + "example": [ + "merchant@example.com" + ], "items": { "type": "string", "format": "email" - }, - "example": [ - "merchant@example.com" - ] - }, - "example": [ - "merchant@example.com" - ] + } + } }, { "name": "statuses[]", @@ -2559,9 +2664,6 @@ "properties": { "items": { "type": "array", - "items": { - "$ref": "#/components/schemas/TransactionHistory" - }, "example": [ { "transaction_code": "TEENSK4W2K", @@ -2579,14 +2681,17 @@ "payout_type": "BANK_ACCOUNT", "refunded_amount": 0 } - ] + ], + "items": { + "$ref": "#/components/schemas/TransactionHistory" + } }, "links": { "type": "array", + "example": [], "items": { "$ref": "#/components/schemas/TransactionsHistoryLink" - }, - "example": [] + } } } }, @@ -2655,35 +2760,37 @@ } } } - }, + } + } + }, + "/v1.0/merchants/{merchant_code}/payouts": { + "get": { + "summary": "List payouts", + "operationId": "ListPayoutsV1", + "description": "Lists payout and payout-deduction records for the specified merchant account within the requested date range.\n\nThe response can include:\n- regular payouts (`type = PAYOUT`)\n- deduction records for refunds, chargebacks, direct debit returns, or balance adjustments\n\nResults are sorted by payout date in the requested `order`.", + "tags": [ + "Payouts" + ], "security": [ { "apiKey": [] }, { "oauth2": [ - "transactions.history", - "transactions.read" + "user.profile", + "user.profile_readonly", + "payouts.read" ] } ], - "tags": [ - "Transactions" - ], "x-codegen": { "method_name": "list" }, "x-scopes": [ - "transactions.history", - "transactions.read" - ] - } - }, - "/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.\n\nThe response can include:\n- regular payouts (`type = PAYOUT`)\n- deduction records for refunds, chargebacks, direct debit returns, or balance adjustments\n\nResults are sorted by payout date in the requested `order`.", + "user.profile", + "user.profile_readonly", + "payouts.read" + ], "parameters": [ { "name": "merchant_code", @@ -2696,8 +2803,8 @@ } }, { - "name": "start_date", "in": "query", + "name": "start_date", "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": { @@ -2707,8 +2814,8 @@ } }, { - "name": "end_date", "in": "query", + "name": "end_date", "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": { @@ -2718,45 +2825,45 @@ } }, { - "name": "format", "in": "query", + "name": "format", "description": "Response format for the payout list.", "required": false, "schema": { "type": "string", - "example": "json", - "default": "json", "enum": [ "json", "csv" - ] + ], + "default": "json", + "example": "json" } }, { - "name": "limit", "in": "query", + "name": "limit", "description": "Maximum number of payout records to return.", "required": false, "schema": { "type": "integer", - "example": 10, + "minimum": 1, "maximum": 9999, - "minimum": 1 + "example": 10 } }, { - "name": "order", "in": "query", + "name": "order", "description": "Sort direction for the returned payouts.", "required": false, "schema": { "type": "string", - "example": "desc", - "default": "asc", "enum": [ "asc", "desc" - ] + ], + "default": "asc", + "example": "desc" } } ], @@ -2784,8 +2891,8 @@ }, "text/plain": { "schema": { - "description": "CSV-formatted payout export returned when `format=csv`.", - "type": "string" + "type": "string", + "description": "CSV-formatted payout export returned when `format=csv`." }, "example": "id,type,amount,date,currency,fee,status,reference,transaction_code\n123456789,PAYOUT,132.45,2024-02-29,EUR,3.12,SUCCESSFUL,payout-2024-02-29,TEENSK4W2K" } @@ -2852,41 +2959,37 @@ } } } - }, + } + } + }, + "/v1.1/receipts/{transaction_id}": { + "get": { + "operationId": "GetReceipt", + "summary": "Retrieve receipt details", + "description": "Retrieves receipt specific data for a transaction.", + "tags": [ + "Receipts" + ], "security": [ { "apiKey": [] }, { "oauth2": [ - "user.profile", - "user.profile_readonly", - "payouts.read" + "receipts.read" ] } ], - "tags": [ - "Payouts" - ], "x-codegen": { - "method_name": "list" + "method_name": "get" }, "x-scopes": [ - "user.profile", - "user.profile_readonly", - "payouts.read" - ] - } - }, - "/v1.1/receipts/{transaction_id}": { - "get": { - "operationId": "GetReceipt", - "summary": "Retrieve receipt details", - "description": "Retrieves receipt specific data for a transaction.", + "receipts.read" + ], "parameters": [ { - "name": "transaction_id", "in": "path", + "name": "transaction_id", "description": "SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD.", "required": true, "schema": { @@ -2894,8 +2997,8 @@ } }, { - "name": "mid", "in": "query", + "name": "mid", "description": "Merchant code.", "required": true, "schema": { @@ -2903,8 +3006,8 @@ } }, { - "name": "tx_event_id", "in": "query", + "name": "tx_event_id", "description": "The ID of the transaction event (refund).", "required": false, "schema": { @@ -3008,38 +3111,18 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "receipts.read" - ] - } - ], - "tags": [ - "Receipts" - ], - "x-codegen": { - "method_name": "get" - }, - "x-scopes": [ - "receipts.read" - ] + } } }, "/v0/merchants/{merchant_code}/readers/{reader_id}/go-checkout": { "post": { - "operationId": "CreateGoReaderCheckout", - "summary": "Create a Go Reader Payment", "description": "Initiates a payment on the SumUp Go terminal identified by the reader ID.\n\nUse `client_transaction_id` as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate.", + "operationId": "CreateGoReaderCheckout", "parameters": [ { - "name": "Authorization", - "in": "header", "description": "Access token in the format 'Bearer {token}'.", + "in": "header", + "name": "Authorization", "required": true, "schema": { "type": "string" @@ -3047,8 +3130,8 @@ }, { "name": "merchant_code", - "in": "path", "description": "Short unique identifier for the merchant.", + "in": "path", "required": true, "schema": { "type": "string", @@ -3066,8 +3149,8 @@ } ], "requestBody": { - "description": "Payment details to initiate on the reader.", "required": true, + "description": "Payment details to initiate on the reader.", "content": { "application/json": { "schema": { @@ -3168,6 +3251,21 @@ } } }, + "summary": "Create a Go Reader Payment", + "tags": [ + "Readers" + ], + "x-scopes": [ + "payments", + "readers.write" + ], + "x-permissions": [ + "readers_checkout_create" + ], + "x-codegen": { + "method_name": "create_go_checkout", + "ignore": true + }, "security": [ { "apiKey": [] @@ -3178,28 +3276,35 @@ "readers.write" ] } - ], - "tags": [ - "Readers" - ], - "x-codegen": { - "method_name": "create_go_checkout", - "ignore": true - }, - "x-permissions": [ - "readers_checkout_create" - ], - "x-scopes": [ - "payments", - "readers.write" ] } }, "/v0.1/memberships": { "get": { - "operationId": "ListMemberships", "summary": "List memberships", "description": "List memberships of the current user.", + "tags": [ + "Memberships" + ], + "operationId": "ListMemberships", + "x-codegen": { + "method_name": "list" + }, + "x-scopes": [ + "user.profile", + "user.profile_readonly" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "user.profile", + "user.profile_readonly" + ] + } + ], "parameters": [ { "name": "offset", @@ -3207,9 +3312,9 @@ "description": "Offset of the first member to return.", "schema": { "type": "integer", - "example": 0, "default": 0, - "minimum": 0 + "minimum": 0, + "example": 0 } }, { @@ -3218,10 +3323,10 @@ "description": "Maximum number of members to return.", "schema": { "type": "integer", - "example": 10, "default": 10, + "minimum": 1, "maximum": 25, - "minimum": 1 + "example": 10 } }, { @@ -3278,12 +3383,12 @@ "in": "query", "description": "Filter memberships by the parent of the resource the membership is in.\nWhen 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": { + "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResourceType" } - ], - "nullable": true + ] } }, { @@ -3300,8 +3405,8 @@ "role_accountant" ] }, - "explode": true, - "style": "form" + "style": "form", + "explode": true } ], "responses": { @@ -3311,6 +3416,10 @@ "application/json": { "schema": { "type": "object", + "required": [ + "total_count", + "items" + ], "properties": { "items": { "type": "array", @@ -3322,11 +3431,7 @@ "type": "integer", "example": 3 } - }, - "required": [ - "total_count", - "items" - ] + } } } } @@ -3363,35 +3468,11 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "user.profile", - "user.profile_readonly" - ] - } - ], - "tags": [ - "Memberships" - ], - "x-codegen": { - "method_name": "list" - }, - "x-scopes": [ - "user.profile", - "user.profile_readonly" - ] + } } }, "/v0.1/merchants/{merchant_code}/members": { "get": { - "operationId": "ListMerchantMembers", - "summary": "List members", - "description": "Lists merchant members.", "parameters": [ { "name": "offset", @@ -3399,9 +3480,9 @@ "description": "Offset of the first member to return.", "schema": { "type": "integer", - "example": 0, "default": 0, - "minimum": 0 + "minimum": 0, + "example": 0 } }, { @@ -3410,22 +3491,22 @@ "description": "Maximum number of members to return.", "schema": { "type": "integer", - "example": 10, "default": 10, + "minimum": 1, "maximum": 25, - "minimum": 1 + "example": 10 } }, { "name": "scroll", "in": "query", "description": "Indicates to skip count query.", + "x-document": false, "schema": { "type": "boolean", - "example": true, - "default": false - }, - "x-document": false + "default": false, + "example": true + } }, { "name": "email", @@ -3468,13 +3549,13 @@ "role_accountant" ] }, - "explode": true, - "style": "form" + "style": "form", + "explode": true }, { "name": "merchant_code", - "in": "path", "description": "Short unique identifier for the merchant.", + "in": "path", "required": true, "schema": { "type": "string", @@ -3482,6 +3563,37 @@ } } ], + "summary": "List members", + "description": "Lists merchant members.", + "tags": [ + "Members" + ], + "operationId": "ListMerchantMembers", + "x-codegen": { + "method_name": "list" + }, + "x-permissions": [ + { + "relation": "merchant_read", + "object_type": "merchant", + "object_id_param": "merchant_code" + } + ], + "x-scopes": [ + "user.subaccounts", + "members.read" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "user.subaccounts", + "members.read" + ] + } + ], "responses": { "200": { "description": "Returns a list of Member objects.", @@ -3489,6 +3601,9 @@ "application/json": { "schema": { "type": "object", + "required": [ + "items" + ], "properties": { "items": { "type": "array", @@ -3500,10 +3615,7 @@ "type": "integer", "example": 3 } - }, - "required": [ - "items" - ] + } } } } @@ -3524,7 +3636,15 @@ } } } - }, + } + }, + "post": { + "operationId": "CreateMerchantMember", + "summary": "Create a member", + "description": "Create a merchant member.", + "tags": [ + "Members" + ], "security": [ { "apiKey": [] @@ -3532,43 +3652,23 @@ { "oauth2": [ "user.subaccounts", - "members.read" + "members.write" ] } ], - "tags": [ - "Members" - ], "x-codegen": { - "method_name": "list" + "method_name": "create" }, "x-permissions": [ { - "relation": "merchant_read", + "relation": "members_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "members.read" - ] - }, - "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" - } - } + "members.write" ], "requestBody": { "required": true, @@ -3576,37 +3676,41 @@ "application/json": { "schema": { "type": "object", + "required": [ + "email", + "roles" + ], "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" + "type": "boolean", + "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." }, "email": { - "description": "Email address of the member to add.", "type": "string", "format": "email", + "description": "Email address of the member to add.", "maxLength": 256 }, "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", + "minLength": 8, "format": "password", - "minLength": 8 + "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." }, "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", + "description": "Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only.", "maxLength": 64 }, "roles": { - "description": "List of roles to assign to the new member.", "type": "array", + "description": "List of roles to assign to the new member.", + "maxItems": 124, "items": { "type": "string", "maxLength": 64 - }, - "maxItems": 124 + } }, "metadata": { "$ref": "#/components/schemas/Metadata" @@ -3620,11 +3724,7 @@ "roles": [ "role_employee" ] - }, - "required": [ - "email", - "roles" - ] + } } } } @@ -3689,61 +3789,51 @@ } } }, - "security": [ - { - "apiKey": [] - }, + "parameters": [ { - "oauth2": [ - "user.subaccounts", - "members.write" - ] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } } - ], - "tags": [ - "Members" - ], - "x-codegen": { - "method_name": "create" + ] + } + }, + "/v0.1/merchants/{merchant_code}/members/{member_id}": { + "get": { + "summary": "Retrieve a member", + "description": "Retrieve a merchant member.", + "tags": [ + "Members" + ], + "operationId": "GetMerchantMember", + "x-codegen": { + "method_name": "get" }, "x-permissions": [ { - "relation": "members_create", + "relation": "members_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "members.write" - ] - } - }, - "/v0.1/merchants/{merchant_code}/members/{member_id}": { - "get": { - "operationId": "GetMerchantMember", - "summary": "Retrieve a member", - "description": "Retrieve a merchant member.", - "parameters": [ + "members.read" + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] }, { - "name": "member_id", - "in": "path", - "description": "The ID of the member to retrieve.", - "required": true, - "schema": { - "type": "string", - "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" - } + "oauth2": [ + "user.subaccounts", + "members.read" + ] } ], "responses": { @@ -3774,59 +3864,59 @@ } } }, - "security": [ + "parameters": [ { - "apiKey": [] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } }, { - "oauth2": [ - "user.subaccounts", - "members.read" - ] + "in": "path", + "name": "member_id", + "description": "The ID of the member to retrieve.", + "required": true, + "schema": { + "type": "string", + "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" + } } - ], + ] + }, + "put": { + "summary": "Update a member", + "description": "Update the merchant member.", "tags": [ "Members" ], + "operationId": "UpdateMerchantMember", "x-codegen": { - "method_name": "get" + "method_name": "update" }, "x-permissions": [ { - "relation": "members_view", + "relation": "members_update", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "members.read" - ] - }, - "put": { - "operationId": "UpdateMerchantMember", - "summary": "Update a member", - "description": "Update the merchant member.", - "parameters": [ + "members.write" + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] }, { - "name": "member_id", - "in": "path", - "description": "The ID of the member to retrieve.", - "required": true, - "schema": { - "type": "string", - "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" - } + "oauth2": [ + "user.subaccounts", + "members.write" + ] } ], "requestBody": { @@ -3838,11 +3928,11 @@ "properties": { "roles": { "type": "array", + "maxItems": 124, "items": { "type": "string", "maxLength": 64 - }, - "maxItems": 124 + } }, "metadata": { "$ref": "#/components/schemas/Metadata" @@ -3851,20 +3941,20 @@ "$ref": "#/components/schemas/Attributes" }, "user": { - "description": "Allows you to update user data of managed users.", "type": "object", + "description": "Allows you to update user data of managed users.", "properties": { "nickname": { - "description": "User's nickname. Used for display purposes only.", "type": "string", "example": "Test User", + "description": "User's nickname. Used for display purposes only.", "maxLength": 64 }, "password": { - "description": "Password of the member to add. Only used if `is_managed_user` is true.", "type": "string", "format": "password", - "minLength": 8 + "minLength": 8, + "description": "Password of the member to add. Only used if `is_managed_user` is true." } } } @@ -3961,26 +4051,42 @@ } } }, - "security": [ + "parameters": [ { - "apiKey": [] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } }, { - "oauth2": [ - "user.subaccounts", - "members.write" - ] + "in": "path", + "name": "member_id", + "description": "The ID of the member to retrieve.", + "required": true, + "schema": { + "type": "string", + "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" + } } - ], + ] + }, + "delete": { + "summary": "Delete a member", + "description": "Deletes a merchant member.", "tags": [ "Members" ], + "operationId": "DeleteMerchantMember", "x-codegen": { - "method_name": "update" + "method_name": "delete" }, "x-permissions": [ { - "relation": "members_update", + "relation": "members_delete", "object_type": "merchant", "object_id_param": "merchant_code" } @@ -3988,32 +4094,16 @@ "x-scopes": [ "user.subaccounts", "members.write" - ] - }, - "delete": { - "operationId": "DeleteMerchantMember", - "summary": "Delete a member", - "description": "Deletes a merchant member.", - "parameters": [ + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] }, { - "name": "member_id", - "in": "path", - "description": "The ID of the member to retrieve.", - "required": true, - "schema": { - "type": "string", - "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" - } + "oauth2": [ + "user.subaccounts", + "members.write" + ] } ], "responses": { @@ -4053,51 +4143,61 @@ } } }, - "security": [ + "parameters": [ { - "apiKey": [] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } }, { - "oauth2": [ - "user.subaccounts", - "members.write" - ] + "in": "path", + "name": "member_id", + "description": "The ID of the member to retrieve.", + "required": true, + "schema": { + "type": "string", + "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" + } } - ], + ] + } + }, + "/v0.1/merchants/{merchant_code}/roles": { + "get": { + "summary": "List roles", + "description": "List merchant's custom roles.", "tags": [ - "Members" + "Roles" ], + "operationId": "ListMerchantRoles", "x-codegen": { - "method_name": "delete" + "method_name": "list" }, "x-permissions": [ { - "relation": "members_delete", + "relation": "roles_list", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "members.write" - ] - } - }, - "/v0.1/merchants/{merchant_code}/roles": { - "get": { - "operationId": "ListMerchantRoles", - "summary": "List roles", - "description": "List merchant's custom roles.", - "parameters": [ + "roles.read" + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] + }, + { + "oauth2": [ + "user.subaccounts", + "roles.read" + ] } ], "responses": { @@ -4107,6 +4207,9 @@ "application/json": { "schema": { "type": "object", + "required": [ + "items" + ], "properties": { "items": { "type": "array", @@ -4114,10 +4217,7 @@ "$ref": "#/components/schemas/Role" } } - }, - "required": [ - "items" - ] + } } } } @@ -4139,6 +4239,26 @@ } } }, + "parameters": [ + { + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } + } + ] + }, + "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.", + "tags": [ + "Roles" + ], "security": [ { "apiKey": [] @@ -4146,43 +4266,23 @@ { "oauth2": [ "user.subaccounts", - "roles.read" + "roles.write" ] } ], - "tags": [ - "Roles" - ], "x-codegen": { - "method_name": "list" + "method_name": "create" }, "x-permissions": [ { - "relation": "roles_list", + "relation": "roles_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "roles.read" - ] - }, - "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" - } - } + "roles.write" ], "requestBody": { "required": true, @@ -4190,15 +4290,20 @@ "application/json": { "schema": { "type": "object", + "required": [ + "name", + "permissions" + ], "properties": { "name": { - "description": "User-defined name of the role.", "type": "string", - "example": "Senior Shop Manager II" + "example": "Senior Shop Manager II", + "description": "User-defined name of the role." }, "permissions": { - "description": "User's permissions.", "type": "array", + "description": "User's permissions.", + "maxItems": 100, "items": { "type": "string" }, @@ -4206,22 +4311,17 @@ "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." + "example": "Manges the shop and the employees.", + "description": "User-defined description of the role." } - }, - "required": [ - "name", - "permissions" - ] + } } } } @@ -4270,61 +4370,51 @@ } } }, - "security": [ - { - "apiKey": [] - }, + "parameters": [ { - "oauth2": [ - "user.subaccounts", - "roles.write" - ] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } } - ], + ] + } + }, + "/v0.1/merchants/{merchant_code}/roles/{role_id}": { + "get": { + "summary": "Retrieve a role", + "description": "Retrieve a custom role by ID.", "tags": [ "Roles" ], + "operationId": "GetMerchantRole", "x-codegen": { - "method_name": "create" + "method_name": "get" }, "x-permissions": [ { - "relation": "roles_create", + "relation": "roles_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "roles.write" - ] - } - }, - "/v0.1/merchants/{merchant_code}/roles/{role_id}": { - "get": { - "operationId": "GetMerchantRole", - "summary": "Retrieve a role", - "description": "Retrieve a custom role by ID.", - "parameters": [ + "roles.read" + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] }, { - "name": "role_id", - "in": "path", - "description": "The ID of the role to retrieve.", - "required": true, - "schema": { - "type": "string", - "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" - } + "oauth2": [ + "user.subaccounts", + "roles.read" + ] } ], "responses": { @@ -4355,6 +4445,36 @@ } } }, + "parameters": [ + { + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } + }, + { + "in": "path", + "name": "role_id", + "description": "The ID of the role to retrieve.", + "required": true, + "schema": { + "type": "string", + "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" + } + } + ] + }, + "delete": { + "operationId": "DeleteMerchantRole", + "summary": "Delete a role", + "description": "Delete a custom role.", + "tags": [ + "Roles" + ], "security": [ { "apiKey": [] @@ -4362,53 +4482,23 @@ { "oauth2": [ "user.subaccounts", - "roles.read" + "roles.write" ] } ], - "tags": [ - "Roles" - ], "x-codegen": { - "method_name": "get" + "method_name": "delete" }, "x-permissions": [ { - "relation": "roles_view", + "relation": "roles_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ "user.subaccounts", - "roles.read" - ] - }, - "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" - } - } + "roles.write" ], "responses": { "200": { @@ -4447,6 +4537,36 @@ } } }, + "parameters": [ + { + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } + }, + { + "in": "path", + "name": "role_id", + "description": "The ID of the role to retrieve.", + "required": true, + "schema": { + "type": "string", + "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" + } + } + ] + }, + "patch": { + "operationId": "UpdateMerchantRole", + "summary": "Update a role", + "description": "Update a custom role.", + "tags": [ + "Roles" + ], "security": [ { "apiKey": [] @@ -4458,15 +4578,12 @@ ] } ], - "tags": [ - "Roles" - ], "x-codegen": { - "method_name": "delete" + "method_name": "update" }, "x-permissions": [ { - "relation": "roles_delete", + "relation": "roles_update", "object_type": "merchant", "object_id_param": "merchant_code" } @@ -4474,33 +4591,6 @@ "x-scopes": [ "user.subaccounts", "roles.write" - ] - }, - "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, @@ -4510,13 +4600,14 @@ "type": "object", "properties": { "name": { - "description": "User-defined name of the role.", "type": "string", - "example": "Senior Shop Manager II" + "example": "Senior Shop Manager II", + "description": "User-defined name of the role." }, "permissions": { - "description": "User's permissions.", "type": "array", + "description": "User's permissions.", + "maxItems": 100, "items": { "type": "string" }, @@ -4524,13 +4615,12 @@ "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": "Manges the shop and the employees.", + "description": "User-defined description of the role." } }, "example": { @@ -4589,33 +4679,27 @@ } } }, - "security": [ + "parameters": [ { - "apiKey": [] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } }, { - "oauth2": [ - "user.subaccounts", - "roles.write" - ] - } - ], - "tags": [ - "Roles" - ], - "x-codegen": { - "method_name": "update" - }, - "x-permissions": [ - { - "relation": "roles_update", - "object_type": "merchant", - "object_id_param": "merchant_code" + "in": "path", + "name": "role_id", + "description": "The ID of the role to retrieve.", + "required": true, + "schema": { + "type": "string", + "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" + } } - ], - "x-scopes": [ - "user.subaccounts", - "roles.write" ] } }, @@ -4624,11 +4708,14 @@ "operationId": "GetMerchant", "summary": "Get Merchant", "description": "Returns a Merchant for a valid Merchant code.", + "tags": [ + "Merchants" + ], "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.\n", + "in": "query", "schema": { "type": "string", "examples": [ @@ -4638,8 +4725,8 @@ }, { "name": "merchant_code", - "in": "path", "description": "Short unique identifier for the merchant.", + "in": "path", "required": true, "schema": { "type": "string", @@ -4647,6 +4734,31 @@ } } ], + "externalDocs": { + "description": "Merchant documentation", + "url": "https://developer.sumup.com/tools/models/merchant" + }, + "x-codegen": { + "method_name": "get" + }, + "x-scopes": [ + "user.profile", + "user.profile_readonly" + ], + "x-permissions": [ + "merchant_read" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "user.profile", + "user.profile_readonly" + ] + } + ], "responses": { "200": { "description": "Returns a Merchant for a valid identifier.", @@ -4668,35 +4780,7 @@ } } } - }, - "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": { @@ -4704,11 +4788,14 @@ "operationId": "ListPersons", "summary": "List Persons", "description": "Returns the Persons related to a Merchant.", + "tags": [ + "Merchants" + ], "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.\n", + "in": "query", "schema": { "type": "string", "examples": [ @@ -4718,8 +4805,8 @@ }, { "name": "merchant_code", - "in": "path", "description": "Short unique identifier for the merchant.", + "in": "path", "required": true, "schema": { "type": "string", @@ -4727,6 +4814,31 @@ } } ], + "externalDocs": { + "description": "Persons documentation", + "url": "https://developer.sumup.com/tools/models/merchant#persons" + }, + "x-scopes": [ + "user.profile", + "user.profile_readonly" + ], + "x-permissions": [ + "persons_read" + ], + "x-codegen": { + "method_name": "list_persons" + }, + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "user.profile", + "user.profile_readonly" + ] + } + ], "responses": { "200": { "description": "Returns a list of Persons for a valid Merchant identifier.", @@ -4748,35 +4860,7 @@ } } } - }, - "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}": { @@ -4784,11 +4868,14 @@ "operationId": "GetPerson", "summary": "Get Person", "description": "Returns a single Person related to a Merchant.", + "tags": [ + "Merchants" + ], "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.\n", + "in": "query", "schema": { "type": "string", "examples": [ @@ -4798,8 +4885,8 @@ }, { "name": "merchant_code", - "in": "path", "description": "Short unique identifier for the merchant.", + "in": "path", "required": true, "schema": { "type": "string", @@ -4808,8 +4895,8 @@ }, { "name": "person_id", - "in": "path", "description": "Person ID", + "in": "path", "required": true, "schema": { "type": "string", @@ -4821,6 +4908,31 @@ } } ], + "externalDocs": { + "description": "Persons documentation", + "url": "https://developer.sumup.com/tools/models/merchant#persons" + }, + "x-scopes": [ + "user.profile", + "user.profile_readonly" + ], + "x-permissions": [ + "persons_read" + ], + "x-codegen": { + "method_name": "get_person" + }, + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "user.profile", + "user.profile_readonly" + ] + } + ], "responses": { "200": { "description": "Returns a Person for a valid identifier.", @@ -4842,54 +4954,42 @@ } } } + } + } + }, + "/v0.1/merchants/{merchant_code}/readers": { + "get": { + "summary": "List Readers", + "description": "List all readers of the merchant.", + "operationId": "ListReaders", + "tags": [ + "Readers" + ], + "x-codegen": { + "method_name": "list" }, - "externalDocs": { - "description": "Persons documentation", - "url": "https://developer.sumup.com/tools/models/merchant#persons" - }, + "x-permissions": [ + { + "relation": "readers_list", + "object_type": "merchant", + "object_id_param": "merchant_code" + } + ], + "x-scopes": [ + "readers.read", + "terminals.read" + ], "security": [ { "apiKey": [] }, { "oauth2": [ - "user.profile", - "user.profile_readonly" + "readers.read", + "terminals.read" ] } ], - "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.", @@ -4897,6 +4997,9 @@ "application/json": { "schema": { "type": "object", + "required": [ + "items" + ], "properties": { "items": { "type": "array", @@ -4904,10 +5007,7 @@ "$ref": "#/components/schemas/Reader" } } - }, - "required": [ - "items" - ] + } } } } @@ -4929,49 +5029,49 @@ } } }, - "security": [ - { - "apiKey": [] - }, + "parameters": [ { - "oauth2": [ - "readers.read", - "terminals.read" - ] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } } - ], + ] + }, + "post": { + "summary": "Create a Reader", + "operationId": "CreateReader", + "description": "Create a new Reader for the merchant account.", "tags": [ "Readers" ], "x-codegen": { - "method_name": "list" + "method_name": "create" }, "x-permissions": [ { - "relation": "readers_list", + "relation": "readers_create", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ - "readers.read", - "terminals.read" - ] - }, - "post": { - "operationId": "CreateReader", - "summary": "Create a Reader", - "description": "Create a new Reader for the merchant account.", - "parameters": [ + "readers.write", + "terminals.write" + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] + }, + { + "oauth2": [ + "readers.write", + "terminals.write" + ] } ], "requestBody": { @@ -4980,6 +5080,10 @@ "application/json": { "schema": { "type": "object", + "required": [ + "pairing_code", + "name" + ], "properties": { "pairing_code": { "$ref": "#/components/schemas/ReaderPairingCode" @@ -4990,11 +5094,7 @@ "metadata": { "$ref": "#/components/schemas/Metadata" } - }, - "required": [ - "pairing_code", - "name" - ] + } } } } @@ -5091,45 +5191,57 @@ } } }, - "security": [ - { - "apiKey": [] - }, + "parameters": [ { - "oauth2": [ - "readers.write", - "terminals.write" - ] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } } - ], + ] + } + }, + "/v0.1/merchants/{merchant_code}/readers/{reader_id}": { + "get": { + "summary": "Retrieve a Reader", + "description": "Retrieve a Reader.", + "operationId": "GetReader", "tags": [ "Readers" ], "x-codegen": { - "method_name": "create" + "method_name": "get" }, "x-permissions": [ { - "relation": "readers_create", + "relation": "readers_view", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ - "readers.write", - "terminals.write" - ] - } - }, - "/v0.1/merchants/{merchant_code}/readers/{reader_id}": { - "get": { - "operationId": "GetReader", - "summary": "Retrieve a Reader", - "description": "Retrieve a Reader.", + "readers.read", + "terminals.read" + ], + "security": [ + { + "apiKey": [] + }, + { + "oauth2": [ + "readers.read", + "terminals.read" + ] + } + ], "parameters": [ { - "name": "If-Modified-Since", "in": "header", + "name": "If-Modified-Since", "description": "Return the reader only if it has been modified after the specified timestamp given in the headers.\n\nTimestamps are accepted in the following formats:\n\n - 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).\n - RFC 3339: Used for timestamps in JSON payloads on this API.", "required": false, "schema": { @@ -5143,15 +5255,15 @@ { "format": "date-time", "type": "string", - "example": "2023-05-30T10:38:01+00:00" + "example": "2023-05-30T10:38:01Z" } ] } }, { "name": "merchant_code", - "in": "path", "description": "Short unique identifier for the merchant.", + "in": "path", "required": true, "schema": { "type": "string", @@ -5195,59 +5307,38 @@ } } } - }, - "security": [ - { - "apiKey": [] - }, - { - "oauth2": [ - "readers.read", - "terminals.read" - ] - } - ], + } + }, + "delete": { + "summary": "Delete a reader", + "description": "Delete a reader.", + "operationId": "DeleteReader", "tags": [ "Readers" ], "x-codegen": { - "method_name": "get" + "method_name": "delete" }, "x-permissions": [ { - "relation": "readers_view", + "relation": "readers_delete", "object_type": "merchant", "object_id_param": "merchant_code" } ], "x-scopes": [ - "readers.read", - "terminals.read" - ] - }, - "delete": { - "operationId": "DeleteReader", - "summary": "Delete a reader", - "description": "Delete a reader.", - "parameters": [ + "readers.write", + "terminals.write" + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] }, { - "name": "reader_id", - "in": "path", - "description": "The unique identifier of the reader.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReaderID" - } + "oauth2": [ + "readers.write", + "terminals.write" + ] } ], "responses": { @@ -5271,26 +5362,41 @@ } } }, - "security": [ + "parameters": [ { - "apiKey": [] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } }, { - "oauth2": [ - "readers.write", - "terminals.write" - ] + "name": "reader_id", + "in": "path", + "description": "The unique identifier of the reader.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReaderID" + } } - ], + ] + }, + "patch": { + "summary": "Update a Reader", + "description": "Update a Reader.", + "operationId": "UpdateReader", "tags": [ "Readers" ], "x-codegen": { - "method_name": "delete" + "method_name": "update" }, "x-permissions": [ { - "relation": "readers_delete", + "relation": "readers_update", "object_type": "merchant", "object_id_param": "merchant_code" } @@ -5298,31 +5404,16 @@ "x-scopes": [ "readers.write", "terminals.write" - ] - }, - "patch": { - "operationId": "UpdateReader", - "summary": "Update a Reader", - "description": "Update a Reader.", - "parameters": [ + ], + "security": [ { - "name": "merchant_code", - "in": "path", - "description": "Short unique identifier for the merchant.", - "required": true, - "schema": { - "type": "string", - "example": "MK10CL2A" - } + "apiKey": [] }, { - "name": "reader_id", - "in": "path", - "description": "The unique identifier of the reader.", - "required": true, - "schema": { - "$ref": "#/components/schemas/ReaderID" - } + "oauth2": [ + "readers.write", + "terminals.write" + ] } ], "requestBody": { @@ -5387,87 +5478,102 @@ } } }, - "security": [ + "parameters": [ { - "apiKey": [] + "name": "merchant_code", + "description": "Short unique identifier for the merchant.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "MK10CL2A" + } }, { - "oauth2": [ - "readers.write", - "terminals.write" - ] - } - ], - "tags": [ - "Readers" - ], - "x-codegen": { - "method_name": "update" - }, - "x-permissions": [ - { - "relation": "readers_update", - "object_type": "merchant", - "object_id_param": "merchant_code" + "name": "reader_id", + "in": "path", + "description": "The unique identifier of the reader.", + "required": true, + "schema": { + "$ref": "#/components/schemas/ReaderID" + } } - ], - "x-scopes": [ - "readers.write", - "terminals.write" ] } }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout": { "post": { - "operationId": "CreateReaderCheckout", - "summary": "Create a Reader Checkout", + "callbacks": { + "ReaderCheckoutStatusChange": { + "{$request.body#/return_url}": { + "post": { + "callbacks": {}, + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReaderCheckoutStatusChange" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Your server returns this code if it accepts the callback.\nIf the server returns any other code, the callback will be retried up to 5 times with exponential backoff.\n" + } + } + } + } + } + }, "description": "Creates a Checkout for a Reader.\n\nThis process is asynchronous and the actual transaction may take some time to be started on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise checkout won't be accepted\n* 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.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.\n", + "operationId": "CreateReaderCheckout", "parameters": [ { - "name": "merchant_code", - "in": "path", "description": "Merchant Code", + "example": "MC0X0ABC", + "in": "path", + "name": "merchant_code", "required": true, "schema": { "type": "string" - }, - "example": "MC0X0ABC" + } }, { - "name": "reader_id", - "in": "path", "description": "The unique identifier of the Reader", + "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", + "in": "path", + "name": "reader_id", "required": true, "schema": { "type": "string" - }, - "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65" + } } ], "requestBody": { - "description": "A checkout initial attributes", - "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutRequest" } } - } + }, + "description": "A checkout initial attributes", + "required": true }, "responses": { "201": { - "description": "The Checkout got successfully created for the given reader.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReaderCheckoutResponse" } } - } + }, + "description": "The Checkout got successfully created for the given reader." }, "400": { - "description": "Response when given params (or one of them) are invalid", "content": { "application/json": { "schema": { @@ -5485,10 +5591,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given params (or one of them) are invalid" }, "401": { - "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -5506,10 +5612,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Unauthorized" }, "404": { - "description": "Response when given reader is not found", "content": { "application/json": { "schema": { @@ -5527,10 +5633,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given reader is not found" }, "422": { - "description": "Response when given params (or one of them) are invalid", "content": { "application/json": { "schema": { @@ -5548,31 +5654,8 @@ "$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.\nIf the server returns any other code, the callback will be retried up to 5 times with exponential backoff.\n" - } - }, - "callbacks": {} - } - } + }, + "description": "Response when given params (or one of them) are invalid" } }, "security": [ @@ -5585,6 +5668,7 @@ ] } ], + "summary": "Create a Reader Checkout", "tags": [ "Readers" ], @@ -5601,44 +5685,43 @@ }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/status": { "get": { - "operationId": "GetReaderStatus", - "summary": "Get a Reader Status", + "callbacks": {}, "description": "Provides the last known status for a Reader.\n\nThis 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).\n\nSupported States\n\n* `IDLE` – Reader ready for next transaction\n* `SELECTING_TIP` – Waiting for tip input\n* `WAITING_FOR_CARD` – Awaiting card insert/tap\n* `WAITING_FOR_PIN` – Waiting for PIN entry\n* `WAITING_FOR_SIGNATURE` – Waiting for customer signature\n* `UPDATING_FIRMWARE` – Firmware update in progress\n\nDevice Status\n\n* `ONLINE` – Device connected and operational\n* `OFFLINE` – Device disconnected (last state persisted)\n\n**Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher.\n", + "operationId": "GetReaderStatus", "parameters": [ { - "name": "merchant_code", - "in": "path", "description": "Merchant Code", + "example": "MC0X0ABC", + "in": "path", + "name": "merchant_code", "required": true, "schema": { "type": "string" - }, - "example": "MC0X0ABC" + } }, { - "name": "reader_id", - "in": "path", "description": "The unique identifier of the Reader", + "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", + "in": "path", + "name": "reader_id", "required": true, "schema": { "type": "string" - }, - "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65" + } } ], "responses": { "200": { - "description": "Response with the device status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } - } + }, + "description": "Response with the device status." }, "400": { - "description": "Response when given params (or one of them) are invalid", "content": { "application/json": { "schema": { @@ -5656,10 +5739,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given params (or one of them) are invalid" }, "401": { - "description": "Response when given merchant's token is invalid", "content": { "application/json": { "schema": { @@ -5677,10 +5760,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given merchant's token is invalid" }, "404": { - "description": "Response when given reader is not found", "content": { "application/json": { "schema": { @@ -5698,10 +5781,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given reader is not found" } }, - "callbacks": {}, "security": [ { "apiKey": [] @@ -5712,6 +5795,7 @@ ] } ], + "summary": "Get a Reader Status", "tags": [ "Readers" ], @@ -5728,47 +5812,46 @@ }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate": { "post": { - "operationId": "CreateReaderTerminate", - "summary": "Terminate a Reader Checkout", + "callbacks": {}, "description": "Terminate a Reader Checkout stops the current transaction on the target device.\n\nThis process is asynchronous and the actual termination may take some time to be performed on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise terminate won't be accepted\n* The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.\n* There is no confirmation of the termination.\n\nIf a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher.\n", + "operationId": "CreateReaderTerminate", "parameters": [ { - "name": "merchant_code", - "in": "path", "description": "Merchant Code", + "example": "MC0X0ABC", + "in": "path", + "name": "merchant_code", "required": true, "schema": { "type": "string" - }, - "example": "MC0X0ABC" + } }, { - "name": "reader_id", - "in": "path", "description": "The unique identifier of the Reader", + "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", + "in": "path", + "name": "reader_id", "required": true, "schema": { "type": "string" - }, - "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65" + } } ], "requestBody": { - "description": "A checkout initial attributes", - "required": false, "content": { "application/json": {} - } + }, + "description": "A checkout initial attributes", + "required": false }, "responses": { "202": { - "description": "The Terminate action was successfully dispatched for the given reader.", "content": { "application/json": {} - } + }, + "description": "The Terminate action was successfully dispatched for the given reader." }, "400": { - "description": "Response when given params (or one of them) are invalid", "content": { "application/json": { "schema": { @@ -5786,10 +5869,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given params (or one of them) are invalid" }, "401": { - "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -5807,10 +5890,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Unauthorized" }, "404": { - "description": "Response when given reader is not found", "content": { "application/json": { "schema": { @@ -5828,10 +5911,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given reader is not found" }, "422": { - "description": "Response when given params (or one of them) are invalid", "content": { "application/json": { "schema": { @@ -5849,10 +5932,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given params (or one of them) are invalid" } }, - "callbacks": {}, "security": [ { "apiKey": [] @@ -5863,6 +5946,7 @@ ] } ], + "summary": "Terminate a Reader Checkout", "tags": [ "Readers" ], @@ -5879,54 +5963,53 @@ }, "/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout/{checkout_id}": { "get": { - "operationId": "GetReaderCheckout", - "summary": "Get a Reader Checkout", + "callbacks": {}, "description": "Get a Checkout for a Reader.\n", + "operationId": "GetReaderCheckout", "parameters": [ { - "name": "merchant_code", - "in": "path", "description": "Merchant Code", + "example": "MC0X0ABC", + "in": "path", + "name": "merchant_code", "required": true, "schema": { "type": "string" - }, - "example": "MC0X0ABC" + } }, { - "name": "reader_id", - "in": "path", "description": "The unique identifier of the Reader", + "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", + "in": "path", + "name": "reader_id", "required": true, "schema": { "type": "string" - }, - "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65" + } }, { - "name": "checkout_id", - "in": "path", "description": "The unique identifier of the Checkout", + "example": "74ecff66-1655-43ed-8ce3-193f49fa602f", + "in": "path", + "name": "checkout_id", "required": true, "schema": { "type": "string" - }, - "example": "74ecff66-1655-43ed-8ce3-193f49fa602f" + } } ], "responses": { "200": { - "description": "The Checkout got successfully retrieved for the given reader.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReaderCheckoutResponse" } } - } + }, + "description": "The Checkout got successfully retrieved for the given reader." }, "401": { - "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -5944,10 +6027,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Unauthorized" }, "404": { - "description": "Response when given reader or checkout is not found", "content": { "application/json": { "schema": { @@ -5965,10 +6048,10 @@ "$ref": "#/components/schemas/Problem" } } - } + }, + "description": "Response when given reader or checkout is not found" } }, - "callbacks": {}, "security": [ { "apiKey": [] @@ -5979,6 +6062,7 @@ ] } ], + "summary": "Get a Reader Checkout", "tags": [ "Readers" ], @@ -5995,256 +6079,73 @@ } }, "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" + "schemas": { + "AddressLegacy": { + "title": "Address Legacy", + "type": "object", + "description": "Profile's personal address information.", + "properties": { + "city": { + "type": "string", + "description": "City name from the address.", + "example": "Berlin" + }, + "country": { + "type": "string", + "description": "Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", + "example": "DE" + }, + "line_1": { + "type": "string", + "description": "First line of the address with details of the street name and number.", + "example": "Sample street" + }, + "line_2": { + "type": "string", + "description": "Second line of the address with details of the building, unit, apartment, and floor numbers.", + "example": "ap. 5" + }, + "postal_code": { + "type": "string", + "description": "Postal code from the address.", + "example": "10115" + }, + "state": { + "type": "string", + "description": "State name or abbreviation from the address.", + "example": "Berlin" + } } }, - "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.", + "title": "Card", "type": "object", + "description": "__Required when payment type is `card`.__ Details of the payment card.", "properties": { "name": { - "description": "Name of the cardholder as it appears on the payment card.", "type": "string", - "example": "FIRSTNAME LASTNAME", - "writeOnly": true + "description": "Name of the cardholder as it appears on the payment card.", + "writeOnly": true, + "example": "FIRSTNAME LASTNAME" }, "number": { - "description": "Number of the payment card (without spaces).", "type": "string", - "example": "1234567890123456", - "writeOnly": true + "description": "Number of the payment card (without spaces).", + "writeOnly": true, + "example": "1234567890123456" }, "expiry_year": { - "description": "Year from the expiration time of the payment card. Accepted formats are `YY` and `YYYY`.", "type": "string", - "example": "2023", - "maxLength": 4, + "description": "Year from the expiration time of the payment card. Accepted formats are `YY` and `YYYY`.", + "writeOnly": true, "minLength": 2, - "writeOnly": true + "maxLength": 4, + "example": "2023" }, "expiry_month": { - "description": "Month from the expiration time of the payment card. Accepted format is `MM`.", "type": "string", + "description": "Month from the expiration time of the payment card. Accepted format is `MM`.", + "writeOnly": true, "enum": [ "01", "02", @@ -6258,24 +6159,23 @@ "10", "11", "12" - ], - "writeOnly": true + ] }, "cvv": { - "description": "Three or four-digit card verification value (security code) of the payment card.", "type": "string", - "example": "123", + "description": "Three or four-digit card verification value (security code) of the payment card.", + "writeOnly": true, "maxLength": 4, "minLength": 3, - "writeOnly": true + "example": "123" }, "zip_code": { - "description": "Required five-digit ZIP code. Applicable only to merchant users in the USA.", "type": "string", - "example": "12345", + "description": "Required five-digit ZIP code. Applicable only to merchant users in the USA.", + "writeOnly": true, "maxLength": 5, "minLength": 5, - "writeOnly": true + "example": "12345" }, "type": { "$ref": "#/components/schemas/CardType" @@ -6288,194 +6188,184 @@ "expiry_year", "cvv", "type" - ], - "title": "Card" + ] }, "CardResponse": { - "description": "Details of the payment card.", + "title": "Card Response", "type": "object", + "description": "Details of the payment card.", "properties": { "last_4_digits": { - "description": "Last 4 digits of the payment card number.", "type": "string", - "example": "3456", - "maxLength": 4, + "description": "Last 4 digits of the payment card number.", + "readOnly": true, "minLength": 4, - "readOnly": true + "maxLength": 4, + "example": "3456" }, "type": { "$ref": "#/components/schemas/CardType" } - }, - "title": "Card Response" + } }, "Device": { + "title": "Device", "description": "Details of the device used to create the transaction.", "type": "object", "properties": { "name": { - "description": "Device name.", "type": "string", + "description": "Device name.", "example": "m0xx" }, "system_name": { - "description": "Device OS.", "type": "string", + "description": "Device OS.", "example": "Android" }, "model": { - "description": "Device model.", "type": "string", + "description": "Device model.", "example": "GT-I9300" }, "system_version": { - "description": "Device OS version.", "type": "string", + "description": "Device OS version.", "example": "4.3" }, "uuid": { - "description": "Device UUID.", "type": "string", + "description": "Device UUID.", "example": "3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2" } - }, - "title": "Device" + } }, "ElvCardAccount": { + "title": "ELV Card Account", "description": "Details of the ELV card account associated with the transaction.", "type": "object", "properties": { "sort_code": { - "description": "ELV card sort code.", "type": "string", + "description": "ELV card sort code.", "example": "87096214" }, "last_4_digits": { - "description": "ELV card account number last 4 digits.", "type": "string", + "description": "ELV card account number last 4 digits.", "example": "5674" }, "sequence_no": { - "description": "ELV card sequence number.", "type": "integer", + "description": "ELV card sequence number.", "example": 1 }, "iban": { - "description": "ELV IBAN.", "type": "string", + "description": "ELV IBAN.", "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.", + "title": "Hosted Checkout", "type": "object", + "description": "Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response.", "properties": { "enabled": { - "description": "Whether the checkout should include a SumUp-hosted payment page.", "type": "boolean", + "description": "Whether the checkout should include a SumUp-hosted payment page.", "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", + "title": "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.", "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 + "maxLength": 90, + "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.", + "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "amount": { - "description": "Amount to be charged to the payer, expressed in major units.", "type": "number", "format": "float", + "description": "Amount to be charged to the payer, expressed in major units.", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "merchant_code": { - "description": "Merchant account that receives the payment.", "type": "string", + "description": "Merchant account that receives the payment.", "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", + "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.", "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", + "description": "Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.", "example": "http://example.com" }, "id": { - "description": "Unique SumUp identifier of the checkout resource.", "type": "string", - "example": "4e425463-3e1b-431d-83fa-1e51c2925e99", - "readOnly": true + "description": "Unique SumUp identifier of the checkout resource.", + "readOnly": true, + "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" }, "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", + "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.", "enum": [ "PENDING", "FAILED", "PAID", "EXPIRED" - ] + ], + "example": "PENDING" }, "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", + "example": "2020-02-29T10:56:56+00:00", "format": "date-time", - "example": "2020-02-29T10:56:56+00:00" + "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." }, "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", + "format": "date-time", + "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.", "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", + "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.", "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 + "description": "URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.", + "readOnly": true, + "example": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676" }, "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" - } - ] - }, + "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.", "example": [ { "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", @@ -6493,54 +6383,64 @@ "auth_code": "012345" } ], - "uniqueItems": true + "uniqueItems": true, + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/TransactionBase" + }, + { + "$ref": "#/components/schemas/TransactionCheckoutInfo" + } + ] + } } - }, - "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.", + "title": "Checkout Create Request", "type": "object", + "description": "Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here.", "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 + "maxLength": 90, + "description": "Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems.", + "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "amount": { - "description": "Amount to be charged to the payer, expressed in major units.", "type": "number", "format": "float", + "description": "Amount to be charged to the payer, expressed in major units.", "example": 10.1 }, "currency": { "$ref": "#/components/schemas/Currency" }, "merchant_code": { - "description": "Merchant account that should receive the payment.", "type": "string", + "description": "Merchant account that should receive the payment.", "example": "MH4H92C7" }, "description": { - "description": "Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.", "type": "string", + "description": "Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.", "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", + "description": "Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.", "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", + "description": "Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.", "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", + "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.", "default": "CHECKOUT", "enum": [ "CHECKOUT", @@ -6548,16 +6448,16 @@ ] }, "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", + "format": "date-time", + "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.", "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" + "example": "https://mysite.com/completed_purchase", + "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." }, "hosted_checkout": { "$ref": "#/components/schemas/HostedCheckout" @@ -6568,56 +6468,55 @@ "amount", "currency", "merchant_code" - ], - "title": "Checkout Create Request" + ] }, "CheckoutUpdateRequest": { - "description": "Request body for updating an existing checkout. Include only the fields that should be changed.", + "title": "Checkout Update Request", "type": "object", + "description": "Request body for updating an existing checkout. Include only the fields that should be changed.", "properties": { "amount": { - "description": "Updated amount to be charged to the payer, expressed in major units.", "type": "number", "format": "float", + "description": "Updated amount to be charged to the payer, expressed in major units.", "example": 12.5 }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { - "description": "Updated short merchant-defined description shown in SumUp tools and reporting.", "type": "string", + "description": "Updated short merchant-defined description shown in SumUp tools and reporting.", "example": "Updated purchase" }, "checkout_reference": { - "description": "Updated merchant-defined reference for the checkout.", "type": "string", - "example": "f00a8f74-b05d-4605-bd73-2a901bae5802", - "maxLength": 90 + "maxLength": 90, + "description": "Updated merchant-defined reference for the checkout.", + "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "valid_until": { - "description": "Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable.", "type": "string", - "format": "date-time", "example": "2020-02-29T10:56:56+00:00", + "format": "date-time", + "description": "Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable.", "nullable": true }, "customer_id": { - "description": "Updated merchant-scoped customer identifier associated with the checkout.", "type": "string", + "description": "Updated merchant-scoped customer identifier associated with the checkout.", "example": "831ff8d4cd5958ab5670" } - }, - "title": "Checkout Update 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.", + "title": "Process Checkout", "type": "object", + "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.", "properties": { "payment_type": { - "description": "Payment method used for this processing attempt. It determines which additional request fields are required.", "type": "string", - "example": "card", + "description": "Payment method used for this processing attempt. It determines which additional request fields are required.", "enum": [ "card", "boleto", @@ -6626,14 +6525,15 @@ "bancontact", "google_pay", "apple_pay" - ] + ], + "example": "card" }, "installments": { - "description": "Number of installments for deferred payments. Available only to merchant users in Brazil.", "type": "integer", - "example": 1, + "description": "Number of installments for deferred payments. Available only to merchant users in Brazil.", + "minimum": 1, "maximum": 12, - "minimum": 1 + "example": 1 }, "mandate": { "$ref": "#/components/schemas/MandatePayload" @@ -6642,8 +6542,8 @@ "$ref": "#/components/schemas/Card" }, "google_pay": { - "description": "Raw `PaymentData` object received from Google Pay. Send the Google Pay response payload as-is.", "type": "object", + "description": "Raw `PaymentData` object received from Google Pay. Send the Google Pay response payload as-is.", "example": { "apiVersionMinor": 0, "apiVersion": 2, @@ -6662,8 +6562,8 @@ } }, "apple_pay": { - "description": "Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is.", "type": "object", + "description": "Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is.", "example": { "token": { "paymentData": { @@ -6686,13 +6586,13 @@ } }, "token": { - "description": "Saved-card token to use instead of raw card details when processing with a previously stored payment instrument.", "type": "string", + "description": "Saved-card token to use instead of raw card details when processing with a previously stored payment instrument.", "example": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50" }, "customer_id": { - "description": "Customer identifier associated with the saved payment instrument. Required when `token` is provided.", "type": "string", + "description": "Customer identifier associated with the saved payment instrument. Required when `token` is provided.", "example": "MEDKHDTI" }, "personal_details": { @@ -6701,10 +6601,10 @@ }, "required": [ "payment_type" - ], - "title": "Process Checkout" + ] }, "CheckoutSuccess": { + "title": "Checkout Success", "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": [ { @@ -6714,68 +6614,67 @@ "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 + "description": "Transaction code of the successful transaction with which the payment for the checkout is completed.", + "readOnly": true, + "example": "TEENSK4W2K" }, "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 + "description": "Transaction ID of the successful transaction with which the payment for the checkout is completed.", + "readOnly": true, + "example": "410fc44a-5956-44e1-b5cc-19c6f8d727a4" }, "merchant_name": { - "description": "Name of the merchant", "type": "string", + "description": "Name of the merchant", "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" + "example": "https://mysite.com/completed_purchase", + "description": "URL where the payer is redirected after a redirect-based payment or SCA flow completes." }, "payment_instrument": { - "description": "Details of the saved payment instrument created or reused during checkout processing.", "type": "object", + "description": "Details of the saved payment instrument created or reused during checkout processing.", "properties": { "token": { - "description": "Token value", "type": "string", + "description": "Token value", "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.", + "title": "Checkout Accepted", "type": "object", + "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.", "properties": { "next_step": { - "description": "Instructions for the next action the payer or client must take.", "type": "object", + "description": "Instructions for the next action the payer or client must take.", "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" + "example": "https://dummy-3ds-gateway.com/cap?RID=1233\u0026VAA=A", + "description": "URL to open or submit in order to continue processing." }, "method": { - "description": "HTTP method to use when following the next step.", "type": "string", - "example": "POST" + "example": "POST", + "description": "HTTP method to use when following the next step." }, "redirect_url": { - "description": "Merchant URL where the payer returns after the external flow finishes.", "type": "string", - "example": "https://mysite.com/completed_purchase" + "example": "https://mysite.com/completed_purchase", + "description": "Merchant URL where the payer returns after the external flow finishes." }, "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", @@ -6783,59 +6682,59 @@ "iframe", "browser" ] - } + }, + "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." }, "payload": { - "description": "Parameters required to complete the next step. The exact keys depend on the payment provider and flow type.", "type": "object", + "description": "Parameters required to complete the next step. The exact keys depend on the payment provider and flow type.", + "additionalProperties": { + "type": "string" + }, "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", + "title": "Customer", + "description": "Saved customer details.", + "required": [ + "customer_id" + ], "properties": { "customer_id": { - "description": "Unique ID of the customer.", "type": "string", + "description": "Unique ID of the customer.", "example": "831ff8d4cd5958ab5670" }, "personal_details": { "$ref": "#/components/schemas/PersonalDetails" } - }, - "required": [ - "customer_id" - ], - "title": "Customer" + } }, "Error": { - "description": "Error message structure.", + "title": "Error", "type": "object", + "description": "Error message structure.", "properties": { "message": { - "description": "Short description of the error.", "type": "string", + "description": "Short description of the error.", "example": "Resource not found" }, "error_code": { - "description": "Platform code for the error.", "type": "string", + "description": "Platform code for the error.", "example": "NOT_FOUND" } - }, - "title": "Error" + } }, "Problem": { "description": "A RFC 9457 problem details object.\n\nAdditional properties specific to the problem type may be present.", @@ -6875,6 +6774,7 @@ "title": "Problem" }, "ErrorExtended": { + "title": "Error Extended", "description": "Error payload with the invalid parameter reference.", "allOf": [ { @@ -6884,58 +6784,64 @@ "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" + "type": "string", + "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." } } } - ], - "title": "Error Extended" + ] }, "ErrorForbidden": { - "description": "Error message for forbidden requests.", + "title": "Error Forbidden", "type": "object", + "description": "Error message for forbidden requests.", "properties": { "error_message": { - "description": "Short description of the error.", "type": "string", + "description": "Short description of the error.", "example": "request_not_allowed" }, "error_code": { - "description": "Platform code for the error.", "type": "string", + "description": "Platform code for the error.", "example": "FORBIDDEN" }, "status_code": { - "description": "HTTP status code for the error.", "type": "string", + "description": "HTTP status code for the error.", "example": "403" } - }, - "title": "Error Forbidden" + } }, "DetailsError": { - "description": "Error message structure.", + "title": "Details Error", "type": "object", + "description": "Error message structure.", "properties": { "title": { - "description": "Short title of the error.", "type": "string", + "description": "Short title of the error.", "example": "Bad Request" }, "details": { - "description": "Details of the error.", "type": "string", + "description": "Details of the error.", "example": "One or more of the parameters are invalid." }, "status": { - "description": "The status code.", "type": "number", + "description": "The status code.", "example": 400 }, "failed_constraints": { - "description": "List of violated validation constraints.", "type": "array", + "description": "List of violated validation constraints.", + "example": [ + { + "message": "Currency must also be specified when filtering by amount", + "reference": "currency" + } + ], "items": { "type": "object", "properties": { @@ -6946,18 +6852,12 @@ "type": "string" } } - }, - "example": [ - { - "message": "Currency must also be specified when filtering by amount", - "reference": "currency" - } - ] + } } - }, - "title": "Details Error" + } }, "Event": { + "title": "Event", "description": "High-level transaction event details.", "type": "object", "properties": { @@ -6974,227 +6874,227 @@ "$ref": "#/components/schemas/TransactionEventStatus" }, "amount": { - "description": "Amount of the event.", "type": "number", - "format": "float" + "format": "float", + "description": "Amount of the event." }, "timestamp": { - "description": "Date and time of the transaction event.", "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Date and time of the transaction event." }, "fee_amount": { - "description": "Amount of the fee related to the event.", "type": "number", - "format": "float" + "format": "float", + "description": "Amount of the fee related to the event." }, "installment_number": { - "description": "Consecutive number of the installment.", - "type": "integer" + "type": "integer", + "description": "Consecutive number of the installment." }, "deducted_amount": { - "description": "Amount deducted for the event.", "type": "number", - "format": "float" + "format": "float", + "description": "Amount deducted for the event." }, "deducted_fee_amount": { - "description": "Amount of the fee deducted for the event.", "type": "number", - "format": "float" + "format": "float", + "description": "Amount of the fee deducted for the event." } - }, - "title": "Event" + } }, "FinancialPayouts": { + "title": "Financial Payouts", "description": "Ordered list of payout and payout-deduction records.", "type": "array", "items": { "$ref": "#/components/schemas/FinancialPayout" - }, - "title": "Financial Payouts" + } }, "FinancialPayout": { + "title": "Financial Payout", "description": "A single payout-related record.\n\nA record can represent either:\n- an actual payout sent to the merchant (`type = PAYOUT`)\n- a deduction applied against merchant funds for a refund, chargeback, direct debit return, or balance adjustment", "type": "object", + "required": [ + "id", + "type", + "amount", + "date", + "currency", + "fee", + "status", + "reference", + "transaction_code" + ], "properties": { "id": { - "description": "Unique identifier of the payout-related record.", "type": "integer", + "description": "Unique identifier of the payout-related record.", "example": 123456789 }, "type": { - "description": "High-level payout record category.", "type": "string", - "example": "PAYOUT", + "description": "High-level payout record category.", "enum": [ "PAYOUT", "CHARGE_BACK_DEDUCTION", "REFUND_DEDUCTION", "DD_RETURN_DEDUCTION", "BALANCE_DEDUCTION" - ] + ], + "example": "PAYOUT" }, "amount": { - "description": "Amount of the payout or deduction in major units.", "type": "number", "format": "float", + "description": "Amount of the payout or deduction in major units.", "example": 132.45 }, "date": { - "description": "Payout date associated with the record, in `YYYY-MM-DD` format.", "type": "string", "format": "date", + "description": "Payout date associated with the record, in `YYYY-MM-DD` format.", "example": "2024-02-29" }, "currency": { - "description": "Three-letter ISO 4217 currency code of the payout.", "type": "string", + "description": "Three-letter ISO 4217 currency code of the payout.", "example": "EUR" }, "fee": { - "description": "Fee amount associated with the payout record, in major units.", "type": "number", "format": "float", + "description": "Fee amount associated with the payout record, in major units.", "example": 3.12 }, "status": { - "description": "Merchant-facing outcome of the payout record.", "type": "string", - "example": "SUCCESSFUL", + "description": "Merchant-facing outcome of the payout record.", "enum": [ "SUCCESSFUL", "FAILED" - ] + ], + "example": "SUCCESSFUL" }, "reference": { - "description": "Processor or payout reference associated with the record.", "type": "string", + "description": "Processor or payout reference associated with the record.", "example": "payout-2024-02-29" }, "transaction_code": { - "description": "Transaction code of the original sale associated with the payout or deduction.", "type": "string", + "description": "Transaction code of the original sale associated with the payout or deduction.", "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.", + "title": "Link", "type": "object", + "description": "Details of a link to a related resource.", "properties": { "rel": { - "description": "Specifies the relation to the current resource.", - "type": "string" + "type": "string", + "description": "Specifies the relation to the current resource." }, "href": { - "description": "URL for accessing the related resource.", "type": "string", - "format": "uri" + "format": "uri", + "description": "URL for accessing the related resource." }, "type": { - "description": "Specifies the media type of the related resource.", - "type": "string" + "type": "string", + "description": "Specifies the media type of the related resource." }, "min_amount": { - "description": "Minimum allowed amount for the refund.", "type": "number", - "format": "float" + "format": "float", + "description": "Minimum allowed amount for the refund." }, "max_amount": { - "description": "Maximum allowed amount for the refund.", "type": "number", - "format": "float" + "format": "float", + "description": "Maximum allowed amount for the refund." } - }, - "title": "Link" + } }, "TransactionsHistoryLink": { + "title": "Transactions History Link", "description": "Hypermedia link used for transaction history pagination.", "type": "object", "properties": { "rel": { - "description": "Relation.", "type": "string", + "description": "Relation.", "example": "next" }, "href": { - "description": "Location.", "type": "string", - "example": "limit=10&oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1&order=ascending" + "description": "Location.", + "example": "limit=10\u0026oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1\u0026order=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.", + "title": "Mandate Payload", "type": "object", + "description": "Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments.", "properties": { "type": { - "description": "Type of mandate to create for the saved payment instrument.", "type": "string", - "example": "recurrent", + "description": "Type of mandate to create for the saved payment instrument.", "enum": [ "recurrent" - ] + ], + "example": "recurrent" }, "user_agent": { - "description": "Browser or client user agent observed when consent was collected.", "type": "string", + "description": "Browser or client user agent observed when consent was collected.", "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", + "description": "IP address of the payer when the mandate was accepted.", "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" + "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" + } }, "MandateResponse": { - "description": "Details of the mandate linked to the saved payment instrument.", + "title": "Mandate Response", "type": "object", + "description": "Details of the mandate linked to the saved payment instrument.", "properties": { "type": { - "description": "Type of mandate stored for the checkout or payment instrument.", - "type": "string" + "type": "string", + "description": "Type of mandate stored for the checkout or payment instrument." }, "status": { - "description": "Current lifecycle status of the mandate.", "type": "string", - "example": "active", + "description": "Current lifecycle status of the mandate.", "enum": [ "active", "inactive" - ] + ], + "example": "active" }, "merchant_code": { - "description": "Merchant account for which the mandate is valid.", "type": "string", + "description": "Merchant account for which the mandate is valid.", "example": "MH4H92C7" } }, @@ -7202,42 +7102,42 @@ "type": "recurrent", "status": "active", "merchant_code": "MH4H92C7" - }, - "title": "Mandate Response" + } }, "PaymentInstrumentResponse": { - "description": "Payment Instrument Response", + "title": "Payment Instrument Response", "type": "object", + "description": "Payment Instrument Response", "properties": { "token": { - "description": "Unique token identifying the saved payment card for a customer.", "type": "string", + "description": "Unique token identifying the saved payment card for a customer.", "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 + "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.", + "readOnly": true, + "default": true }, "type": { - "description": "Type of the payment instrument.", "type": "string", + "description": "Type of the payment instrument.", "enum": [ "card" ] }, "card": { - "description": "Details of the payment card.", "type": "object", + "description": "Details of the payment card.", "properties": { "last_4_digits": { - "description": "Last 4 digits of the payment card number.", "type": "string", - "example": "3456", - "maxLength": 4, + "description": "Last 4 digits of the payment card number.", + "readOnly": true, "minLength": 4, - "readOnly": true + "maxLength": 4, + "example": "3456" }, "type": { "$ref": "#/components/schemas/CardType" @@ -7248,8 +7148,8 @@ "$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", + "description": "Creation date of payment instrument. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code.", "format": "date-time" } }, @@ -7267,112 +7167,112 @@ "type": "VISA" }, "created_at": "2021-03-30T10:06:07.000+00:00" - }, - "title": "Payment Instrument Response" + } }, "PersonalDetails": { - "description": "Personal details for the customer.", + "title": "Personal Details", "type": "object", + "description": "Personal details for the customer.", "properties": { "first_name": { - "description": "First name of the customer.", "type": "string", + "description": "First name of the customer.", "example": "John" }, "last_name": { - "description": "Last name of the customer.", "type": "string", + "description": "Last name of the customer.", "example": "Doe" }, "email": { - "description": "Email address of the customer.", "type": "string", + "description": "Email address of the customer.", "example": "user@example.com" }, "phone": { - "description": "Phone number of the customer.", "type": "string", + "description": "Phone number of the customer.", "example": "+491635559723" }, "birth_date": { - "description": "Date of birth of the customer.", "type": "string", + "description": "Date of birth of the customer.", "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 + "description": "An identification number user for tax purposes (e.g. CPF)", + "maxLength": 255, + "example": "423.378.593-47" }, "address": { "$ref": "#/components/schemas/AddressLegacy" } - }, - "title": "Personal Details" + } }, "Product": { - "description": "Purchase product.", + "title": "Product", "type": "object", + "description": "Purchase product.", "properties": { "name": { - "description": "Product name.", "type": "string", + "description": "Product name.", "example": "Purchase reader for merchant with code ME3FCAVF" }, "price_label": { - "description": "Product description.", - "type": "string" + "type": "string", + "description": "Product description." }, "price": { - "description": "Product price.", "type": "number", "format": "decimal", + "description": "Product price.", "example": 100 }, "vat_rate": { - "description": "VAT percentage.", "type": "number", - "format": "decimal" + "format": "decimal", + "description": "VAT percentage." }, "single_vat_amount": { - "description": "VAT amount for a single product.", "type": "number", - "format": "decimal" + "format": "decimal", + "description": "VAT amount for a single product." }, "price_with_vat": { - "description": "Product price incl. VAT.", "type": "number", - "format": "decimal" + "format": "decimal", + "description": "Product price incl. VAT." }, "vat_amount": { - "description": "VAT amount.", "type": "number", - "format": "decimal" + "format": "decimal", + "description": "VAT amount." }, "quantity": { - "description": "Product quantity.", "type": "integer", + "description": "Product quantity.", "example": 1 }, "total_price": { - "description": "Quantity x product price.", "type": "number", "format": "decimal", + "description": "Quantity x product price.", "example": 100 }, "total_with_vat": { - "description": "Total price incl. VAT.", "type": "number", - "format": "decimal" + "format": "decimal", + "description": "Total price incl. VAT." } - }, - "title": "Product" + } }, "Receipt": { - "description": "Receipt details for a transaction.", "type": "object", + "title": "Receipt", + "description": "Receipt details for a transaction.", "properties": { "transaction_data": { "$ref": "#/components/schemas/ReceiptTransaction" @@ -7381,13 +7281,13 @@ "$ref": "#/components/schemas/ReceiptMerchantData" }, "emv_data": { - "description": "EMV-specific metadata returned for card-present payments.", "type": "object", + "description": "EMV-specific metadata returned for card-present payments.", "example": {} }, "acquirer_data": { - "description": "Acquirer-specific metadata related to the card authorization.", "type": "object", + "description": "Acquirer-specific metadata related to the card authorization.", "example": { "authorization_code": "053201", "return_code": "00" @@ -7407,10 +7307,10 @@ } } } - }, - "title": "Receipt" + } }, "ReceiptEvent": { + "title": "Receipt Event", "description": "Transaction event details as rendered on the receipt.", "type": "object", "properties": { @@ -7427,59 +7327,59 @@ "$ref": "#/components/schemas/TransactionEventStatus" }, "amount": { - "description": "Amount of the event.", "type": "string", - "format": "double" + "format": "double", + "description": "Amount of the event." }, "timestamp": { - "description": "Date and time of the transaction event.", "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Date and time of the transaction event." }, "receipt_no": { - "description": "Receipt number associated with the event.", - "type": "string" + "type": "string", + "description": "Receipt number associated with the event." } - }, - "title": "Receipt Event" + } }, "ReceiptCard": { + "title": "Receipt Card", "description": "Payment card details displayed on the receipt.", "type": "object", "properties": { "last_4_digits": { - "description": "Card last 4 digits.", - "type": "string" + "type": "string", + "description": "Card last 4 digits." }, "type": { - "description": "Card Scheme.", - "type": "string" + "type": "string", + "description": "Card Scheme." } - }, - "title": "Receipt Card" + } }, "ReceiptReader": { + "title": "Receipt Reader", "description": "Card reader details displayed on the receipt.", "type": "object", "properties": { "code": { - "description": "Reader serial number.", - "type": "string" + "type": "string", + "description": "Reader serial number." }, "type": { - "description": "Reader type.", - "type": "string" + "type": "string", + "description": "Reader type." } - }, - "title": "Receipt Reader" + } }, "ReceiptMerchantData": { - "description": "Receipt merchant data", + "title": "Receipt Merchant Data", "type": "object", + "description": "Receipt merchant data", "properties": { "merchant_profile": { - "description": "Merchant profile details displayed on the receipt.", "type": "object", + "description": "Merchant profile details displayed on the receipt.", "properties": { "merchant_code": { "type": "string", @@ -7538,63 +7438,78 @@ } }, "locale": { - "description": "Locale used for rendering localized receipt fields.", - "type": "string" + "type": "string", + "description": "Locale used for rendering localized receipt fields." } - }, - "title": "Receipt Merchant Data" + } }, "ReceiptTransaction": { - "description": "Transaction information.", + "title": "Receipt Transaction", "type": "object", + "description": "Transaction information.", + "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" + }, "properties": { "transaction_code": { - "description": "Transaction code.", - "type": "string" + "type": "string", + "description": "Transaction code." }, "transaction_id": { "$ref": "#/components/schemas/TransactionID" }, "merchant_code": { - "description": "Merchant code.", - "type": "string" + "type": "string", + "description": "Merchant code." }, "amount": { - "description": "Transaction amount.", - "type": "string" + "type": "string", + "description": "Transaction amount." }, "vat_amount": { - "description": "Transaction VAT amount.", - "type": "string" + "type": "string", + "description": "Transaction VAT amount." }, "tip_amount": { - "description": "Tip amount (included in transaction amount).", - "type": "string" + "type": "string", + "description": "Tip amount (included in transaction amount)." }, "currency": { - "description": "Transaction currency.", - "type": "string" + "type": "string", + "description": "Transaction currency." }, "timestamp": { - "description": "Time created at.", "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Time created at." }, "status": { - "description": "Transaction processing status.", - "type": "string" + "type": "string", + "description": "Transaction processing status." }, "payment_type": { - "description": "Transaction type.", - "type": "string" + "type": "string", + "description": "Transaction type." }, "entry_mode": { - "description": "Transaction entry mode.", - "type": "string" + "type": "string", + "description": "Transaction entry mode." }, "verification_method": { - "description": "Cardholder verification method.", - "type": "string" + "type": "string", + "description": "Cardholder verification method." }, "card_reader": { "$ref": "#/components/schemas/ReceiptReader" @@ -7603,145 +7518,130 @@ "$ref": "#/components/schemas/ReceiptCard" }, "installments_count": { - "description": "Number of installments.", - "type": "integer" + "type": "integer", + "description": "Number of installments." }, "process_as": { - "description": "Debit/Credit.", "type": "string", - "example": "CREDIT", + "description": "Debit/Credit.", "enum": [ "CREDIT", "DEBIT" - ] + ], + "example": "CREDIT" }, "products": { - "description": "Products", "type": "array", + "description": "Products", "items": { "type": "object", "properties": { "name": { - "description": "Product name", "type": "string", + "description": "Product name", "example": "Coffee" }, "description": { - "description": "Product description", - "type": "string" + "type": "string", + "description": "Product description" }, "price": { - "description": "Product price", "type": "string", "format": "double", + "description": "Product price", "example": "150.0" }, "vat_rate": { - "description": "VAT rate", "type": "string", "format": "double", + "description": "VAT rate", "example": "0.0" }, "single_vat_amount": { - "description": "VAT amount for a single product", "type": "string", "format": "double", + "description": "VAT amount for a single product", "example": "0.0" }, "price_with_vat": { - "description": "Product price including VAT", "type": "string", "format": "double", + "description": "Product price including VAT", "example": "150.0" }, "vat_amount": { - "description": "VAT amount", "type": "string", "format": "double", + "description": "VAT amount", "example": "0.0" }, "quantity": { - "description": "Product quantity", "type": "integer", "format": "int64", + "description": "Product quantity", "example": 1 }, "total_price": { - "description": "Quantity x product price", "type": "string", "format": "double", + "description": "Quantity x product price", "example": "150.0" }, "total_with_vat": { - "description": "Total price including VAT", "type": "string", "format": "double", + "description": "Total price including VAT", "example": "150.0" } } } }, "vat_rates": { - "description": "Vat rates.", "type": "array", + "description": "Vat rates.", "items": { "type": "object", "properties": { "gross": { - "description": "Gross", "type": "number", - "format": "float" + "format": "float", + "description": "Gross" }, "net": { - "description": "Net", "type": "number", - "format": "float" + "format": "float", + "description": "Net" }, "rate": { - "description": "Rate", "type": "number", - "format": "float" + "format": "float", + "description": "Rate" }, "vat": { - "description": "Vat", "type": "number", - "format": "float" + "format": "float", + "description": "Vat" } } } }, "events": { - "description": "Events", "type": "array", + "description": "Events", "items": { "$ref": "#/components/schemas/ReceiptEvent" } }, "receipt_no": { - "description": "Receipt number", - "type": "string" + "type": "string", + "description": "Receipt number" } - }, - "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.", + "title": "Transaction Event", "type": "object", + "description": "Detailed information about a transaction event.", "properties": { "id": { "$ref": "#/components/schemas/TransactionEventID" @@ -7753,65 +7653,65 @@ "$ref": "#/components/schemas/TransactionEventStatus" }, "amount": { - "description": "Amount of the event.", "type": "number", "format": "decimal", + "description": "Amount of the event.", "example": 58.8 }, "due_date": { - "description": "Date when the transaction event is due to occur.", "type": "string", "format": "date", + "description": "Date when the transaction event is due to occur.", "example": "2020-05-25" }, "date": { - "description": "Date when the transaction event occurred.", "type": "string", "format": "date", + "description": "Date when the transaction event occurred.", "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", + "description": "Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`.", "example": 1 }, "timestamp": { - "description": "Date and time of the transaction event.", "type": "string", "format": "date-time", + "description": "Date and time of the transaction event.", "example": "2020-05-25T10:49:42.784Z" } - }, - "title": "Transaction Event" + } }, "TransactionBase": { - "description": "Details of the transaction.", + "title": "Transaction Base", "type": "object", + "description": "Details of the transaction.", "properties": { "id": { - "description": "Unique ID of the transaction.", "type": "string", + "description": "Unique ID of the transaction.", "example": "6b425463-3e1b-431d-83fa-1e51c2925e99" }, "transaction_code": { - "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", "type": "string", + "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", "example": "TEENSK4W2K" }, "amount": { - "description": "Total amount of the transaction.", "type": "number", "format": "float", + "description": "Total amount of the transaction.", "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", + "example": "2020-02-29T10:56:56.876Z", "format": "date-time", - "example": "2020-02-29T10:56:56.876Z" + "description": "Date and time of the creation of the transaction. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code." }, "status": { "$ref": "#/components/schemas/TransactionStatus" @@ -7820,74 +7720,74 @@ "$ref": "#/components/schemas/PaymentType" }, "installments_count": { - "description": "Current number of the installment for deferred payments.", "type": "integer", + "description": "Current number of the installment for deferred payments.", "minimum": 1 } - }, - "title": "Transaction Base" + } }, "TransactionCheckoutInfo": { + "title": "Transaction Checkout Info", "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", + "description": "Unique code of the registered merchant to whom the payment is made.", "example": "MH4H92C7" }, "vat_amount": { - "description": "Amount of the applicable VAT (out of the total transaction amount).", "type": "number", "format": "float", + "description": "Amount of the applicable VAT (out of the total transaction amount).", "example": 6 }, "tip_amount": { - "description": "Amount of the tip (out of the total transaction amount).", "type": "number", "format": "float", + "description": "Amount of the tip (out of the total transaction amount).", "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", + "description": "Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.", "example": "053201" } - }, - "title": "Transaction Checkout Info" + } }, "TransactionMixinHistory": { + "title": "Transaction Mixin History", "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" + "type": "string", + "description": "Short description of the payment. The value is taken from the `description` property of the related checkout resource." }, "payouts_total": { - "description": "Total number of payouts to the registered user specified in the `user` property.", - "type": "integer" + "type": "integer", + "description": "Total number of payouts to the registered user specified in the `user` property." }, "payouts_received": { - "description": "Number of payouts that are made to the registered user specified in the `user` property.", - "type": "integer" + "type": "integer", + "description": "Number of payouts that are made to the registered user specified in the `user` property." }, "payout_plan": { - "description": "Payout plan of the registered user at the time when the transaction was made.", "type": "string", + "description": "Payout plan of the registered user at the time when the transaction was made.", "enum": [ "SINGLE_PAYMENT", "TRUE_INSTALLMENT", "ACCELERATED_INSTALLMENT" ] } - }, - "title": "Transaction Mixin History" + } }, "TransactionHistory": { + "title": "Transaction History", "description": "Transaction entry returned in history listing responses.", "allOf": [ { @@ -7903,17 +7803,17 @@ "$ref": "#/components/schemas/TransactionID" }, "client_transaction_id": { - "description": "Client-specific ID of the transaction.", - "type": "string" + "type": "string", + "description": "Client-specific ID of the transaction." }, "user": { - "description": "Email address of the registered user (merchant) to whom the payment is made.", "type": "string", - "format": "email" + "format": "email", + "description": "Email address of the registered user (merchant) to whom the payment is made." }, "type": { - "description": "Type of the transaction for the registered user specified in the `user` property.", "type": "string", + "description": "Type of the transaction for the registered user specified in the `user` property.", "enum": [ "PAYMENT", "REFUND", @@ -7924,34 +7824,34 @@ "$ref": "#/components/schemas/CardType" }, "payout_date": { - "description": "Payout date (if paid out at once).", "type": "string", "format": "date", + "description": "Payout date (if paid out at once).", "example": "2019-08-28" }, "payout_type": { - "description": "Payout type.", "type": "string", - "example": "BANK_ACCOUNT", + "description": "Payout type.", "enum": [ "BANK_ACCOUNT", "PREPAID_CARD" - ] + ], + "example": "BANK_ACCOUNT" }, "refunded_amount": { - "description": "Total refunded amount.", "type": "number", "format": "decimal", + "description": "Total refunded amount.", "example": 0 } } } - ], - "title": "Transaction History" + ] }, "PaymentType": { - "description": "Payment type used for the transaction.", + "title": "Payment Type", "type": "string", + "description": "Payment type used for the transaction.", "enum": [ "CASH", "POS", @@ -7964,12 +7864,12 @@ "DIRECT_DEBIT", "APM", "UNKNOWN" - ], - "title": "Payment Type" + ] }, "EntryMode": { - "description": "Entry mode of the payment details.", + "title": "Entry Mode", "type": "string", + "description": "Entry mode of the payment details.", "enum": [ "BOLETO", "SOFORT", @@ -7998,12 +7898,12 @@ "MOTO", "CONTACTLESS_MAGSTRIPE", "N/A" - ], - "title": "Entry Mode" + ] }, "CardType": { - "description": "Issuing card network of the payment card used for the transaction.", + "title": "Card Type", "type": "string", + "description": "Issuing card network of the payment card used for the transaction.", "enum": [ "ALELO", "AMEX", @@ -8029,10 +7929,10 @@ "VPAY", "VR", "UNKNOWN" - ], - "title": "Card Type" + ] }, "TransactionFull": { + "title": "Transaction Full", "description": "Full transaction resource with checkout, payout, and event details.", "allOf": [ { @@ -8048,24 +7948,24 @@ "type": "object", "properties": { "foreign_transaction_id": { - "description": "External/foreign transaction id (passed by clients).", "type": "string", + "description": "External/foreign transaction id (passed by clients).", "example": "J13253253x1" }, "client_transaction_id": { - "description": "Client transaction id.", "type": "string", + "description": "Client transaction id.", "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" + "format": "email", + "description": "Email address of the registered user (merchant) to whom the payment is made." }, "fee_amount": { - "description": "Transaction SumUp total fee amount.", "type": "number", "format": "decimal", + "description": "Transaction SumUp total fee amount.", "example": 8 }, "lat": { @@ -8078,17 +7978,17 @@ "$ref": "#/components/schemas/HorizontalAccuracy" }, "merchant_id": { - "description": "SumUp merchant internal Id.", "type": "integer", "format": "int64", + "description": "SumUp merchant internal Id.", "example": 136902 }, "device_info": { "$ref": "#/components/schemas/Device" }, "simple_payment_type": { - "description": "Simple name of the payment type.", "type": "string", + "description": "Simple name of the payment type.", "enum": [ "CASH", "CC_SIGNATURE", @@ -8107,8 +8007,8 @@ ] }, "verification_method": { - "description": "Verification method used for the transaction.", "type": "string", + "description": "Verification method used for the transaction.", "enum": [ "none", "signature", @@ -8125,83 +8025,83 @@ "$ref": "#/components/schemas/ElvCardAccount" }, "local_time": { - "description": "Local date and time of the creation of the transaction.", "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Local date and time of the creation of the transaction." }, "payout_date": { - "description": "The date of the payout.", "type": "string", "format": "date", + "description": "The date of the payout.", "example": "2019-08-28" }, "payout_type": { - "description": "Payout type for the transaction.", "type": "string", + "description": "Payout type for the transaction.", "enum": [ "BANK_ACCOUNT", "PREPAID_CARD" ] }, "process_as": { - "description": "Debit/Credit.", "type": "string", - "example": "CREDIT", + "description": "Debit/Credit.", "enum": [ "CREDIT", "DEBIT" - ] + ], + "example": "CREDIT" }, "products": { - "description": "List of products from the merchant's catalogue for which the transaction serves as a payment.", "type": "array", + "description": "List of products from the merchant's catalogue for which the transaction serves as a payment.", "items": { "$ref": "#/components/schemas/Product" } }, "vat_rates": { - "description": "List of VAT rates applicable to the transaction.", "type": "array", + "description": "List of VAT rates applicable to the transaction.", "items": { "type": "object", "properties": { "rate": { - "description": "VAT rate.", "type": "number", "format": "decimal", + "description": "VAT rate.", "example": 0.045 }, "net": { - "description": "NET amount of products having this VAT rate applied.", "type": "number", "format": "decimal", + "description": "NET amount of products having this VAT rate applied.", "example": 1.36 }, "vat": { - "description": "VAT amount of this rate applied.", "type": "number", "format": "decimal", + "description": "VAT amount of this rate applied.", "example": 0.06 }, "gross": { - "description": "Gross amount of products having this VAT rate applied.", "type": "number", "format": "decimal", + "description": "Gross amount of products having this VAT rate applied.", "example": 1.42 } } } }, "transaction_events": { - "description": "Detailed list of events related to the transaction.", "type": "array", + "description": "Detailed list of events related to the transaction.", "items": { "$ref": "#/components/schemas/TransactionEvent" } }, "simple_status": { - "description": "High-level status of the transaction from the merchant's perspective.\n\n- `PENDING`: The payment has been initiated and is still being processed. A final outcome is not available yet.\n- `SUCCESSFUL`: The payment was completed successfully.\n- `PAID_OUT`: The payment was completed successfully and the funds have already been included in a payout to the merchant.\n- `FAILED`: The payment did not complete successfully.\n- `CANCELLED`: The payment was cancelled or reversed and is no longer payable or payable to the merchant.\n- `CANCEL_FAILED`: An attempt to cancel or reverse the payment was not completed successfully.\n- `REFUNDED`: The payment was refunded in full or in part.\n- `REFUND_FAILED`: An attempt to refund the payment was not completed successfully.\n- `CHARGEBACK`: The payment was subject to a chargeback.\n- `NON_COLLECTION`: The amount could not be collected from the merchant after a chargeback or related adjustment.", "type": "string", + "description": "High-level status of the transaction from the merchant's perspective.\n\n- `PENDING`: The payment has been initiated and is still being processed. A final outcome is not available yet.\n- `SUCCESSFUL`: The payment was completed successfully.\n- `PAID_OUT`: The payment was completed successfully and the funds have already been included in a payout to the merchant.\n- `FAILED`: The payment did not complete successfully.\n- `CANCELLED`: The payment was cancelled or reversed and is no longer payable or payable to the merchant.\n- `CANCEL_FAILED`: An attempt to cancel or reverse the payment was not completed successfully.\n- `REFUNDED`: The payment was refunded in full or in part.\n- `REFUND_FAILED`: An attempt to refund the payment was not completed successfully.\n- `CHARGEBACK`: The payment was subject to a chargeback.\n- `NON_COLLECTION`: The amount could not be collected from the merchant after a chargeback or related adjustment.", "enum": [ "SUCCESSFUL", "PAID_OUT", @@ -8216,22 +8116,22 @@ ] }, "links": { - "description": "List of hyperlinks for accessing related resources.", "type": "array", + "description": "List of hyperlinks for accessing related resources.", "items": { "$ref": "#/components/schemas/Link" } }, "events": { - "description": "Compact list of events related to the transaction.", "type": "array", + "description": "Compact list of events related to the transaction.", "items": { "$ref": "#/components/schemas/Event" } }, "location": { - "description": "Details of the payment location as received from the payment terminal.", "type": "object", + "description": "Details of the payment location as received from the payment terminal.", "properties": { "lat": { "$ref": "#/components/schemas/Lat" @@ -8245,18 +8145,17 @@ } }, "tax_enabled": { - "description": "Indicates whether tax deduction is enabled for the transaction.", - "type": "boolean" + "type": "boolean", + "description": "Indicates whether tax deduction is enabled for the transaction." } } } - ], - "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.", + "title": "Currency", "type": "string", - "example": "EUR", + "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.", "enum": [ "BGN", "BRL", @@ -8275,34 +8174,35 @@ "SEK", "USD" ], - "title": "Currency" + "example": "EUR" }, "TransactionStatus": { - "description": "Current status of the transaction.\n\n- `PENDING`: The transaction has been created but its final outcome is not known yet.\n- `SUCCESSFUL`: The transaction completed successfully.\n- `CANCELLED`: The transaction was cancelled or otherwise reversed before completion.\n- `FAILED`: The transaction attempt did not complete successfully.\n- `REFUNDED`: The transaction was refunded in full or in part.", + "title": "Transaction Status", "type": "string", + "description": "Current status of the transaction.\n\n- `PENDING`: The transaction has been created but its final outcome is not known yet.\n- `SUCCESSFUL`: The transaction completed successfully.\n- `CANCELLED`: The transaction was cancelled or otherwise reversed before completion.\n- `FAILED`: The transaction attempt did not complete successfully.\n- `REFUNDED`: The transaction was refunded in full or in part.", "enum": [ "SUCCESSFUL", "CANCELLED", "FAILED", "PENDING", "REFUNDED" - ], - "title": "Transaction Status" + ] }, "TransactionEventType": { - "description": "Type of the transaction event.", + "title": "Transaction Event Type", "type": "string", + "description": "Type of the transaction event.", "enum": [ "PAYOUT", "CHARGE_BACK", "REFUND", "PAYOUT_DEDUCTION" - ], - "title": "Transaction Event Type" + ] }, "TransactionEventStatus": { - "description": "Status of the transaction event.\n\nNot every value is used for every event type.\n\n- `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.\n- `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.\n- `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.\n- `PAID_OUT`: The payout event has been completed and the funds were included in a merchant payout.\n- `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.\n- `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`.\n- `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.", + "title": "Transaction Event Status", "type": "string", + "description": "Status of the transaction event.\n\nNot every value is used for every event type.\n\n- `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.\n- `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.\n- `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.\n- `PAID_OUT`: The payout event has been completed and the funds were included in a merchant payout.\n- `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.\n- `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`.\n- `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.", "enum": [ "FAILED", "PAID_OUT", @@ -8311,100 +8211,98 @@ "REFUNDED", "SCHEDULED", "SUCCESSFUL" - ], - "title": "Transaction Event Status" + ] }, "TransactionEventID": { - "description": "Unique ID of the transaction event.", + "title": "Transaction Event ID", "type": "integer", "format": "int64", - "title": "Transaction Event ID" + "description": "Unique ID of the transaction event." }, "HorizontalAccuracy": { - "description": "Indication of the precision of the geographical position received from the payment terminal.", + "title": "Horizontal Accuracy", "type": "number", "format": "float", - "title": "Horizontal Accuracy" + "description": "Indication of the precision of the geographical position received from the payment terminal." }, "Lat": { - "description": "Latitude value from the coordinates of the payment location (as received from the payment terminal reader).", + "title": "Latitude", "type": "number", "format": "float", - "maximum": 90, + "description": "Latitude value from the coordinates of the payment location (as received from the payment terminal reader).", "minimum": 0, - "title": "Latitude" + "maximum": 90 }, "Lon": { - "description": "Longitude value from the coordinates of the payment location (as received from the payment terminal reader).", + "title": "Longitude", "type": "number", "format": "float", - "maximum": 180, + "description": "Longitude value from the coordinates of the payment location (as received from the payment terminal reader).", "minimum": 0, - "title": "Longitude" + "maximum": 180 }, "TransactionID": { - "description": "Unique ID of the transaction.", + "title": "Transaction ID", "type": "string", - "title": "Transaction ID" + "description": "Unique ID of the transaction." }, "Affiliate": { - "type": "object", "properties": { "app_id": { - "type": "string", - "example": "com.example.app" + "example": "com.example.app", + "type": "string" }, "key": { - "type": "string", - "example": "123e4567-e89b-12d3-a456-426614174000" + "example": "123e4567-e89b-12d3-a456-426614174000", + "type": "string" } }, "required": [ "app_id", "key" - ] + ], + "type": "object" }, "Amount": { - "type": "object", "properties": { "currency": { "description": "Currency ISO 4217 code", - "type": "string", - "example": "MXN" + "example": "MXN", + "type": "string" }, "value": { "description": "Amount in minor units (e.g. cents).", - "type": "integer", - "example": 1000 + "example": 1000, + "type": "integer" } }, "required": [ "currency", "value" - ] + ], + "type": "object" }, "ReaderID": { - "description": "Unique identifier of the reader that the payment is initiated on.", "type": "string", + "description": "Unique identifier of the reader that the payment is initiated on.", "example": "rdr_3MSAFM23CK82VSTT4BN6RWSQ65", - "maxLength": 30, - "minLength": 30 + "minLength": 30, + "maxLength": 30 }, "ReaderPaymentRequestParams": { - "type": "object", "properties": { "affiliate": { "$ref": "#/components/schemas/Affiliate" }, "client_transaction_id": { "description": "Caller-supplied correlation identifier, used as the idempotency key.", - "type": "string", - "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f" + "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f", + "type": "string" }, "tip_amount": { "description": "Optional tip amount in minor units, added on top of total_amount.", - "type": "integer", - "example": 100 + "example": 100, + "type": "integer" }, "total_amount": { "$ref": "#/components/schemas/Amount" @@ -8413,34 +8311,35 @@ "required": [ "total_amount", "client_transaction_id" - ] + ], + "type": "object" }, "ReaderPaymentResponse": { - "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReaderPaymentResponseData" } - } + }, + "type": "object" }, "ReaderPaymentResponseData": { - "type": "object", "properties": { "client_transaction_id": { "description": "Caller-supplied correlation identifier that was provided in the request.", - "type": "string", - "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "type": "string" }, "transaction_code": { "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", - "type": "string", - "example": "TEENSK4W2K" + "example": "TEENSK4W2K", + "type": "string" } - } + }, + "type": "object" }, "MembershipStatus": { - "description": "The status of the membership.", "type": "string", + "description": "The status of the membership.", "enum": [ "accepted", "pending", @@ -8450,40 +8349,54 @@ ] }, "ResourceType": { - "description": "The type of the membership resource.\nPossible values are:\n* `merchant` - merchant account(s)\n* `organization` - organization(s)", "type": "string", + "description": "The type of the membership resource.\nPossible values are:\n* `merchant` - merchant account(s)\n* `organization` - organization(s)", "example": "merchant" }, "Membership": { - "description": "A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.", + "title": "Membership", "type": "object", + "description": "A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.", + "required": [ + "id", + "resource_id", + "type", + "roles", + "permissions", + "created_at", + "updated_at", + "status", + "resource" + ], "properties": { "id": { - "description": "ID of the membership.", "type": "string", + "description": "ID of the membership.", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "resource_id": { - "description": "ID of the resource the membership is in.", "type": "string", + "description": "ID of the resource the membership is in.", "example": "M2DDT39A" }, "type": { "$ref": "#/components/schemas/ResourceType" }, "roles": { - "description": "User's roles.", "type": "array", - "items": { - "type": "string" - }, + "description": "User's roles.", "example": [ "role_admin" - ] + ], + "items": { + "type": "string" + } }, "permissions": { - "description": "User's permissions.", "type": "array", + "description": "User's permissions.", + "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.", "items": { "type": "string" }, @@ -8496,19 +8409,17 @@ "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", + "description": "The timestamp of when the membership was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { - "description": "The timestamp of when the membership was last updated.", "type": "string", + "description": "The timestamp of when the membership was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, @@ -8527,91 +8438,90 @@ "resource": { "$ref": "#/components/schemas/MembershipResource" } - }, + } + }, + "MembershipResource": { + "title": "Resource", + "type": "object", + "description": "Information about the resource the membership is in.", "required": [ "id", - "resource_id", "type", - "roles", - "permissions", + "name", "created_at", - "updated_at", - "status", - "resource" + "updated_at" ], - "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", + "description": "ID of the resource the membership is in.", "example": "M2DDT39A" }, "type": { "$ref": "#/components/schemas/ResourceType" }, "name": { - "description": "Display name of the resource.", "type": "string", + "description": "Display name of the resource.", "example": "Acme Corp" }, "logo": { - "description": "Logo fo the resource.", "type": "string", + "description": "Logo fo the resource.", "format": "uri", - "example": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png", - "maxLength": 256 + "maxLength": 256, + "example": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png" }, "created_at": { - "description": "The timestamp of when the membership resource was created.", "type": "string", + "description": "The timestamp of when the membership resource was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { - "description": "The timestamp of when the membership resource was last updated.", "type": "string", + "description": "The timestamp of when the membership resource was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "attributes": { "$ref": "#/components/schemas/Attributes" } - }, + } + }, + "Member": { + "title": "Member", + "type": "object", + "description": "A member is user within specific resource identified by resource id, resource type, and associated roles.", "required": [ "id", - "type", - "name", + "roles", + "permissions", "created_at", - "updated_at" + "updated_at", + "status" ], - "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", + "description": "ID of the member.", "example": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "roles": { - "description": "User's roles.", "type": "array", - "items": { - "type": "string" - }, + "description": "User's roles.", "example": [ "role_admin" - ] + ], + "items": { + "type": "string" + } }, "permissions": { - "description": "User's permissions.", "type": "array", + "description": "User's permissions.", + "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.", "items": { "type": "string" }, @@ -8624,19 +8534,17 @@ "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", + "description": "The timestamp of when the member was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { - "description": "The timestamp of when the member was last updated.", "type": "string", + "description": "The timestamp of when the member was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, @@ -8682,24 +8590,20 @@ "service_account_user": false }, "status": "accepted" - }, - "required": [ - "id", - "roles", - "permissions", - "created_at", - "updated_at", - "status" - ], - "title": "Member" + } }, "Invite": { - "description": "Pending invitation for membership.", + "title": "Invite", "type": "object", + "description": "Pending invitation for membership.", + "required": [ + "email", + "expires_at" + ], "properties": { "email": { - "description": "Email address of the invited user.", "type": "string", + "description": "Email address of the invited user.", "format": "email", "example": "boaty.mcboatface@sumup.com" }, @@ -8708,158 +8612,153 @@ "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", + "description": "Information about the user associated with the membership.", + "required": [ + "id", + "type", + "email", + "mfa_on_login_enabled", + "virtual_user", + "service_account_user" + ], "properties": { "id": { - "description": "Identifier for the End-User (also called Subject).", "type": "string", + "description": "Identifier for the End-User (also called Subject).", "example": "44ca0f5b-813b-46e1-aee7-e6242010662e" }, "type": { "$ref": "#/components/schemas/UserType" }, "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" + "example": "example@sumup.com", + "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." }, "mfa_on_login_enabled": { - "description": "True if the user has enabled MFA on login.", "type": "boolean", - "example": true + "example": true, + "description": "True if the user has enabled MFA on login." }, "virtual_user": { - "description": "True if the user is a virtual user (operator).", "type": "boolean", - "example": false, "deprecated": true, - "x-deprecation-notice": "Rely on `type` instead." + "x-deprecation-notice": "Rely on `type` instead.", + "example": false, + "description": "True if the user is a virtual user (operator)." }, "service_account_user": { - "description": "True if the user is a service account.", "type": "boolean", - "example": false, "deprecated": true, - "x-deprecation-notice": "Rely on `type` instead." + "x-deprecation-notice": "Rely on `type` instead.", + "example": false, + "description": "True if the user is a service account." }, "disabled_at": { - "description": "Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`).", "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`)." }, "nickname": { - "description": "User's nickname. Used for display purposes only.", "type": "string", - "example": "Test User" + "example": "Test User", + "description": "User's nickname. Used for display purposes only." }, "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" + "example": "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png", + "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." }, "classic": { "$ref": "#/components/schemas/MembershipUserClassic" } - }, - "required": [ - "id", - "type", - "email", - "mfa_on_login_enabled", - "virtual_user", - "service_account_user" - ] + } }, "MembershipUserClassic": { - "description": "Classic identifiers of the user.", "type": "object", + "description": "Classic identifiers of the user.", + "deprecated": true, + "required": [ + "user_id" + ], "properties": { "user_id": { "type": "integer", - "maximum": 2147483647, - "minimum": 0 + "minimum": 0, + "maximum": 2147483647 } - }, - "deprecated": true, - "required": [ - "user_id" - ] + } }, "Role": { - "description": "A custom role that can be used to assign set of permissions to members.", + "title": "Role", "type": "object", + "description": "A custom role that can be used to assign set of permissions to members.", + "required": [ + "id", + "name", + "permissions", + "is_predefined", + "created_at", + "updated_at" + ], "properties": { "id": { - "description": "Unique identifier of the role.", "type": "string", + "description": "Unique identifier of the role.", "example": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" }, "name": { - "description": "User-defined name of the role.", "type": "string", - "example": "Senior Shop Manager II" + "example": "Senior Shop Manager II", + "description": "User-defined name of the role." }, "description": { - "description": "User-defined description of the role.", "type": "string", - "example": "Manges the shop and the employees." + "example": "Manges the shop and the employees.", + "description": "User-defined description of the role." }, "permissions": { - "description": "List of permission granted by this role.", "type": "array", + "description": "List of permission granted by this role.", + "maxItems": 100, "items": { "type": "string" }, - "example": [], - "maxItems": 100 + "example": [] }, "is_predefined": { - "description": "True if the role is provided by SumUp.", "type": "boolean", - "example": true + "example": true, + "description": "True if the role is provided by SumUp." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "created_at": { - "description": "The timestamp of when the role was created.", "type": "string", + "description": "The timestamp of when the role was created.", "format": "date-time", "example": "2023-01-20T15:16:17Z" }, "updated_at": { - "description": "The timestamp of when the role was last updated.", "type": "string", + "description": "The timestamp of when the role was last updated.", "format": "date-time", "example": "2023-01-20T15:16:17Z" } - }, - "required": [ - "id", - "name", - "permissions", - "is_predefined", - "created_at", - "updated_at" - ], - "title": "Role" + } }, "Metadata": { "description": "Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.", "type": "object", + "maxProperties": 64, "example": {}, - "additionalProperties": true, - "maxProperties": 64 + "additionalProperties": true }, "Attributes": { "description": "Object attributes that are modifiable only by SumUp applications.\n", @@ -8868,22 +8767,30 @@ "additionalProperties": true }, "UserType": { - "description": "Type of the user account.", "type": "string", - "example": "user", + "description": "Type of the user account.", "enum": [ "user", "managed_user", "service_account", "system_account" - ] + ], + "example": "user" }, "Address": { + "externalDocs": { + "description": "Address documentation", + "url": "https://developer.sumup.com/tools/glossary/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`.\nWhether 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", + "required": [ + "country" + ], "properties": { "street_address": { "type": "array", + "maxItems": 2, "items": { "type": "string", "description": "The first line of the address.", @@ -8892,101 +8799,100 @@ "example": [ "Paul-Linke-Ufer 39-40", "2. Hinterhof" - ], - "maxItems": 2 + ] }, "post_code": { - "description": "The postal code (aka. zip code) of the address.\n", "type": "string", - "example": "10999", - "maxLength": 10 + "description": "The postal code (aka. zip code) of the address.\n", + "maxLength": 10, + "example": "10999" }, "country": { "$ref": "#/components/schemas/CountryCode" }, "city": { - "description": "The city of the address.\n", "type": "string", - "example": "Berlin", - "maxLength": 60 + "description": "The city of the address.\n", + "maxLength": 60, + "example": "Berlin" }, "province": { - "description": "The province where the address is located. This may not be relevant in some countries.\n", "type": "string", - "example": "Berlin", - "maxLength": 60 + "description": "The province where the address is located. This may not be relevant in some countries.\n", + "maxLength": 60, + "example": "Berlin" }, "region": { - "description": "The region where the address is located. This may not be relevant in some countries.\n", "type": "string", - "example": "Baden Wuerttemberg", - "maxLength": 60 + "description": "The region where the address is located. This may not be relevant in some countries.\n", + "maxLength": 60, + "example": "Baden Wuerttemberg" }, "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.\n", "type": "string", - "example": "Dublin County", - "maxLength": 60 + "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.\n", + "maxLength": 60, + "example": "Dublin County" }, "autonomous_community": { - "description": "In Spain, an autonomous community is the first sub-national level of political and administrative division.\n", "type": "string", - "example": "Catalonia", - "maxLength": 60 + "description": "In Spain, an autonomous community is the first sub-national level of political and administrative division.\n", + "maxLength": 60, + "example": "Catalonia" }, "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.\n", "type": "string", - "example": "London", - "maxLength": 60 + "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.\n", + "maxLength": 60, + "example": "London" }, "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.\n", "type": "string", - "example": "California", - "maxLength": 60 + "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.\n", + "maxLength": 60, + "example": "California" }, "neighborhood": { - "description": "Locality level of the address. Used in countries such as Brazil or Chile.\n", "type": "string", - "example": "Copacabana", - "maxLength": 60 + "description": "Locality level of the address. Used in countries such as Brazil or Chile.\n", + "maxLength": 60, + "example": "Copacabana" }, "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.\n", "type": "string", - "example": "Providencia", - "maxLength": 60 + "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.\n", + "maxLength": 60, + "example": "Providencia" }, "department": { - "description": "A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.\n", "type": "string", - "example": "Antioquia", - "maxLength": 60 + "description": "A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.\n", + "maxLength": 60, + "example": "Antioquia" }, "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.\n", "type": "string", - "example": "Medellín", - "maxLength": 60 + "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.\n", + "maxLength": 60, + "example": "Medellín" }, "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.\n", "type": "string", - "example": "Lisbon District", - "maxLength": 60 + "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.\n", + "maxLength": 60, + "example": "Lisbon District" }, "zip_code": { - "description": "A US system of postal codes used by the United States Postal Service (USPS).\n", "type": "string", - "example": "94103", - "maxLength": 10 + "description": "A US system of postal codes used by the United States Postal Service (USPS).\n", + "maxLength": 10, + "example": "94103" }, "eircode": { - "description": "A postal address in Ireland.\n", "type": "string", - "example": "D02 X285", - "maxLength": 10 + "description": "A postal address in Ireland.\n", + "maxLength": 10, + "example": "D02 X285" } }, "example": { @@ -8997,49 +8903,46 @@ "post_code": "10999", "city": "Berlin", "country": "DE" - }, - "externalDocs": { - "description": "Address documentation", - "url": "https://developer.sumup.com/tools/glossary/address" - }, - "required": [ - "country" - ] + } }, "CountryCode": { "description": "An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)\ncountry code. This definition users `oneOf` with a two-character string\ntype to allow for support of future countries in client code.", "type": "string", - "example": "BR", - "maxLength": 2, "minLength": 2, - "pattern": "^[A-Z]{2}$" + "maxLength": 2, + "pattern": "^[A-Z]{2}$", + "example": "BR" }, "PersonalIdentifiers": { - "description": "A list of country-specific personal identifiers.", "type": "array", + "description": "A list of country-specific personal identifiers.", "items": { "$ref": "#/components/schemas/PersonalIdentifier" }, + "maxItems": 32, "example": [ { "ref": "br.cpf", "value": "847.060.136-90" } - ], - "maxItems": 32 + ] }, "PersonalIdentifier": { "type": "object", + "required": [ + "ref", + "value" + ], "properties": { "ref": { - "description": "The unique reference for the personal identifier type.", "type": "string", + "description": "The unique reference for the personal identifier type.", "example": "br.cpf", "maxLength": 32 }, "value": { - "description": "The company identifier value.", "type": "string", + "description": "The company identifier value.", "example": "847.060.136-90", "maxLength": 128 } @@ -9047,14 +8950,13 @@ "example": { "ref": "br.cpf", "value": "847.060.136-90" - }, - "required": [ - "ref", - "value" - ] + } }, "ListPersonsResponseBody": { "type": "object", + "required": [ + "items" + ], "properties": { "items": { "type": "array", @@ -9062,12 +8964,14 @@ "$ref": "#/components/schemas/Person" } } - }, - "required": [ - "items" - ] + } }, "Merchant": { + "title": "Merchant", + "externalDocs": { + "description": "Merchant documentation", + "url": "https://developer.sumup.com/tools/glossary/merchant" + }, "allOf": [ { "type": "object", @@ -9079,19 +8983,19 @@ ], "properties": { "merchant_code": { - "description": "Short unique identifier for the merchant.", "type": "string", - "example": "MK01A8C2", - "readOnly": true + "readOnly": true, + "description": "Short unique identifier for the merchant.", + "example": "MK01A8C2" }, "organization_id": { - "description": "ID of the organization the merchant belongs to (if any).", "type": "string", + "description": "ID of the organization the merchant belongs to (if any).", "example": "G0UZPVAX" }, "business_type": { - "description": "The business type.\n* `sole_trader`: The business is run by an self-employed individual.\n* `company`: The business is run as a company with one or more shareholders\n* `partnership`: The business is run as a company with two or more shareholders that can be also other legal entities\n* `non_profit`: The business is run as a nonprofit organization that operates for public or social benefit\n* `government_entity`: The business is state owned and operated\n", - "type": "string" + "type": "string", + "description": "The business type.\n* `sole_trader`: The business is run by an self-employed individual.\n* `company`: The business is run as a company with one or more shareholders\n* `partnership`: The business is run as a company with two or more shareholders that can be also other legal entities\n* `non_profit`: The business is run as a nonprofit organization that operates for public or social benefit\n* `government_entity`: The business is state owned and operated\n" }, "company": { "$ref": "#/components/schemas/Company" @@ -9103,32 +9007,32 @@ "$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`.\n", "type": "string", - "format": "uri" + "format": "uri", + "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`.\n" }, "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`.\n", - "type": "string" + "type": "string", + "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`.\n" }, "default_currency": { - "description": "Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account.\n", "type": "string", + "readOnly": true, + "description": "Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account.\n", "example": "EUR", - "maxLength": 3, "minLength": 3, - "readOnly": true + "maxLength": 3 }, "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.\nIn 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", + "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.\nIn 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.", "example": "de-DE", - "maxLength": 5, - "minLength": 2 + "minLength": 2, + "maxLength": 5 }, "sandbox": { - "description": "True if the merchant is a sandbox for testing.", "type": "boolean", + "description": "True if the merchant is a sandbox for testing.", "example": false }, "meta": { @@ -9148,52 +9052,47 @@ { "$ref": "#/components/schemas/Timestamps" } - ], - "externalDocs": { - "description": "Merchant documentation", - "url": "https://developer.sumup.com/tools/glossary/merchant" - }, - "title": "Merchant" + ] }, "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.\n\n**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 - } + }, + "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.\n\n**Warning**: Updating Meta will overwrite the existing data. Make sure to always include the complete JSON object.", + "example": {} }, "BusinessProfile": { - "description": "Business information about the merchant. This information will be visible to the merchant's customers.\n", "type": "object", + "description": "Business information about the merchant. This information will be visible to the merchant's customers.\n", "properties": { "name": { - "description": "The customer-facing business name.", "type": "string", - "example": "Example Coffee", + "description": "The customer-facing business name.", + "minLength": 1, "maxLength": 150, - "minLength": 1 + "example": "Example Coffee" }, "dynamic_descriptor": { - "description": "The descriptor is the text that your customer sees on their bank account statement.\nThe more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).\n", "type": "string", - "example": "Example Coffee", - "maxLength": 30, "minLength": 1, - "pattern": "^[a-zA-Z0-9 \\-+\\'_.]{0,30}$" + "maxLength": 30, + "pattern": "^[a-zA-Z0-9 \\-+\\'_.]{0,30}$", + "description": "The descriptor is the text that your customer sees on their bank account statement.\nThe more recognisable your descriptor is, the less risk you have of receiving disputes (e.g. chargebacks).\n", + "example": "Example Coffee" }, "website": { - "description": "The business's publicly available website.", "type": "string", - "example": "https://example.com", - "maxLength": 255 + "description": "The business's publicly available website.", + "maxLength": 255, + "example": "https://example.com" }, "email": { - "description": "A publicly available email address.", "type": "string", - "example": "contact@example.com", - "maxLength": 255 + "description": "A publicly available email address.", + "maxLength": 255, + "example": "contact@example.com" }, "phone_number": { "$ref": "#/components/schemas/PhoneNumber" @@ -9214,42 +9113,42 @@ ] }, "PhoneNumber": { - "description": "A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n", "type": "string", + "description": "A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n", "example": "+420123456789", "maxLength": 16 }, "Branding": { - "description": "Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.", "type": "object", + "description": "Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.", "properties": { "footer_text": { - "description": "Footer text rendered on receipts and other customer-facing products.\n", "type": "string", + "description": "Footer text rendered on receipts and other customer-facing products.\n", + "minLength": 1, + "maxLength": 500, "examples": [ "Thanks for shopping with us." - ], - "maxLength": 500, - "minLength": 1 + ] }, "icon": { - "description": "An icon for the merchant. Must be square.\n", "type": "string", - "format": "uri" + "format": "uri", + "description": "An icon for the merchant. Must be square.\n" }, "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.\n", "type": "string", - "format": "uri" + "format": "uri", + "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.\n" }, "hero": { - "description": "Data-URL encoded hero image for the merchant business.\n", "type": "string", - "format": "uri" + "format": "uri", + "description": "Data-URL encoded hero image for the merchant business.\n" }, "primary_color": { - "description": "A hex color value representing the primary branding color of this merchant (your brand color).\n", "type": "string", + "description": "A hex color value representing the primary branding color of this merchant (your brand color).\n", "examples": [ "#FF4B3A", "#0072C6", @@ -9257,8 +9156,8 @@ ] }, "primary_color_fg": { - "description": "A hex color value representing the color of the text displayed on branding color of this merchant.\n", "type": "string", + "description": "A hex color value representing the color of the text displayed on branding color of this merchant.\n", "examples": [ "#FF4B3A", "#0072C6", @@ -9266,8 +9165,8 @@ ] }, "secondary_color": { - "description": "A hex color value representing the secondary branding color of this merchant (accent color used for buttons).\n", "type": "string", + "description": "A hex color value representing the secondary branding color of this merchant (accent color used for buttons).\n", "examples": [ "#FF4B3A", "#0072C6", @@ -9275,8 +9174,8 @@ ] }, "secondary_color_fg": { - "description": "A hex color value representing the color of the text displayed on secondary branding color of this merchant.\n", "type": "string", + "description": "A hex color value representing the color of the text displayed on secondary branding color of this merchant.\n", "examples": [ "#FF4B3A", "#0072C6", @@ -9284,8 +9183,8 @@ ] }, "background_color": { - "description": "A hex color value representing the preferred background color of this merchant.\n", "type": "string", + "description": "A hex color value representing the preferred background color of this merchant.\n", "examples": [ "#FF4B3A", "#0072C6", @@ -9295,45 +9194,53 @@ } }, "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.\n", + "externalDocs": { + "description": "The country SDK documentation for legal types.", + "url": "https://developer.sumup.com/tools/glossary/merchant#legal-types" + }, "type": "string", + "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.\n", + "minLength": 4, + "maxLength": 64, "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.\n", "type": "array", + "description": "A list of country-specific company identifiers.\n", "items": { "$ref": "#/components/schemas/CompanyIdentifier" } }, "CompanyIdentifier": { + "externalDocs": { + "description": "Company identifier documentation", + "url": "https://developer.sumup.com/tools/glossary/merchant#company-identifiers" + }, "type": "object", + "required": [ + "ref", + "value" + ], "properties": { "ref": { - "description": "The unique reference for the company identifier type as defined in the country SDK.\n", "type": "string", + "description": "The unique reference for the company identifier type as defined in the country SDK.\n", "examples": [ "de.gmbh" ] }, "value": { - "description": "The company identifier value.\n", "type": "string", + "maxLength": 100, + "description": "The company identifier value.\n", "examples": [ "HRB 123456" - ], - "maxLength": 100 + ] } }, "examples": [ @@ -9341,84 +9248,83 @@ "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", + "required": [ + "share" + ], "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.\n", "type": "integer", "format": "int32", - "example": 50000, + "minimum": 25000, "maximum": 100000, - "minimum": 25000 + "example": 50000 } - }, - "required": [ - "share" - ] + } }, "Version": { - "description": "The version of the resource. The version reflects a specific change submitted to the API via one of the `PATCH` endpoints.\n", "type": "string", + "description": "The version of the resource. The version reflects a specific change submitted to the API via one of the `PATCH` endpoints.\n", "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`.\nThe status is only returned after write operations or on read endpoints when the `version` query parameter is provided.\n", "type": "string", - "readOnly": true + "readOnly": true, + "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`.\nThe status is only returned after write operations or on read endpoints when the `version` query parameter is provided.\n" }, "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`.\n", + "externalDocs": { + "description": "Person documentation", + "url": "https://developer.sumup.com/tools/glossary/merchant#persons" + }, "type": "object", + "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`.\n", + "required": [ + "id" + ], "properties": { "id": { - "description": "The unique identifier for the Person. This is a [typeid](https://github.com/sumup/typeid).\n", "type": "string", + "readOnly": true, + "description": "The unique identifier for the Person. This is a [typeid](https://github.com/sumup/typeid).\n", "examples": [ "pers_2EGQ057R6C8J791RVCG5NWAEAB" - ], - "readOnly": true + ] }, "user_id": { - "description": "A corresponding identity user ID for the Person, if they have a user account.\n", "type": "string", + "description": "A corresponding identity user ID for the Person, if they have a user account.\n", "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.\n", "type": "string", "format": "date", - "example": "1980-01-12" + "description": "The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.\n", + "example": "1980-01-12T00:00:00Z" }, "given_name": { - "description": "The first name(s) of the individual.", "type": "string", + "description": "The first name(s) of the individual.", "example": "James Herrald", "maxLength": 60 }, "family_name": { - "description": "The last name(s) of the individual.", "type": "string", + "description": "The last name(s) of the individual.", "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.\n", "type": "string", + "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.\n", "example": "Maria Sophie", "maxLength": 60 }, @@ -9426,8 +9332,10 @@ "$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`.\n", "type": "array", + "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`.\n", + "minItems": 1, + "maxItems": 1, "items": { "type": "string", "description": "* `representative`: The Person is the primary contact for SumUp and has full administrative power over the merchant account.\n* `owner`: The Person is a business owner. If this value is set, the `ownership_percent` should be set as well.\n* `officer`: The Person is an officer at the company.\n", @@ -9436,9 +9344,7 @@ "owner", "officer" ] - }, - "maxItems": 1, - "minItems": 1 + } }, "ownership": { "$ref": "#/components/schemas/Ownership" @@ -9453,15 +9359,15 @@ "$ref": "#/components/schemas/CountryCode" }, "nationality": { - "description": "The Person's 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.\n", "type": "string", + "description": "The Person's 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.\n", "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.\n", "type": "string", - "maxLength": 2, + "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.\n", "minLength": 2, + "maxLength": 2, "nullable": true }, "version": { @@ -9470,25 +9376,22 @@ "change_status": { "$ref": "#/components/schemas/ChangeStatus" } - }, - "externalDocs": { - "description": "Person documentation", - "url": "https://developer.sumup.com/tools/glossary/merchant#persons" - }, - "required": [ - "id" - ] + } }, "Company": { - "description": "Information about the company or business. This is legal information that is used for verification.\n", + "externalDocs": { + "description": "Company documentation", + "url": "https://developer.sumup.com/tools/glossary/merchant#company" + }, "type": "object", + "description": "Information about the company or business. This is legal information that is used for verification.\n", "properties": { "name": { - "description": "The company's legal name.", "type": "string", - "example": "Gin & Doughnuts Bar GmbH", + "description": "The company's legal name.", + "minLength": 1, "maxLength": 150, - "minLength": 1 + "example": "Gin \u0026 Doughnuts Bar GmbH" }, "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.\n", @@ -9514,55 +9417,51 @@ "website": { "description": "HTTP(S) URL of the company's website.\n", "type": "string", + "maxLength": 255, "examples": [ "https://www.sumup.com" - ], - "maxLength": 255 + ] }, "attributes": { "$ref": "#/components/schemas/Attributes" } - }, - "externalDocs": { - "description": "Company documentation", - "url": "https://developer.sumup.com/tools/glossary/merchant#company" } }, "ClassicMerchantIdentifiers": { "type": "object", + "required": [ + "id" + ], "properties": { "id": { - "description": "Classic (serial) merchant ID.", "type": "integer", "format": "int64", + "description": "Classic (serial) merchant ID.", "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).\n", "type": "string", "format": "date-time", + "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).\n", + "readOnly": true, "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).\n", "type": "string", "format": "date-time", + "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).\n", + "readOnly": true, "examples": [ "2021-08-31T12:00:00Z" - ], - "readOnly": true + ] } }, "required": [ @@ -9571,6 +9470,7 @@ ] }, "Reader": { + "title": "Reader", "description": "A physical card reader device that can accept in-person payments.", "type": "object", "properties": { @@ -9590,21 +9490,21 @@ "$ref": "#/components/schemas/Metadata" }, "service_account_id": { - "description": "Identifier of the system-managed service account associated with this reader.\nPresent only for readers that are already paired.\nThis field is currently in beta and may change.", "type": "string", "format": "uuid", - "x-beta": true + "x-beta": true, + "description": "Identifier of the system-managed service account associated with this reader.\nPresent only for readers that are already paired.\nThis field is currently in beta and may change." }, "created_at": { - "description": "The timestamp of when the reader was created.", "type": "string", "format": "date-time", + "description": "The timestamp of when the reader was created.", "example": "2023-01-18T15:16:17Z" }, "updated_at": { - "description": "The timestamp of when the reader was last updated.", "type": "string", "format": "date-time", + "description": "The timestamp of when the reader was last updated.", "example": "2023-01-20T15:16:17Z" } }, @@ -9615,17 +9515,15 @@ "device", "created_at", "updated_at" - ], - "title": "Reader" + ] }, "ReaderName": { - "description": "Custom human-readable, user-defined name for easier identification of the reader.", "type": "string", - "example": "Frontdesk", - "maxLength": 500 + "description": "Custom human-readable, user-defined name for easier identification of the reader.", + "maxLength": 500, + "example": "Frontdesk" }, "ReaderStatus": { - "description": "The status of the reader object gives information about the current state of the reader.\n\nPossible values:\n\n- `unknown` - The reader status is unknown.\n- `processing` - The reader is created and waits for the physical device to confirm the pairing.\n- `paired` - The reader is paired with a merchant account and can be used with SumUp APIs.\n- `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated.", "type": "string", "example": "paired", "enum": [ @@ -9633,25 +9531,26 @@ "processing", "paired", "expired" - ] + ], + "description": "The status of the reader object gives information about the current state of the reader.\n\nPossible values:\n\n- `unknown` - The reader status is unknown.\n- `processing` - The reader is created and waits for the physical device to confirm the pairing.\n- `paired` - The reader is paired with a merchant account and can be used with SumUp APIs.\n- `expired` - The pairing is expired and no longer usable with the account. The resource needs to get recreated." }, "ReaderDevice": { - "description": "Information about the underlying physical device.", "type": "object", + "description": "Information about the underlying physical device.", "properties": { "identifier": { - "description": "A unique identifier of the physical device (e.g. serial number).", "type": "string", + "description": "A unique identifier of the physical device (e.g. serial number).", "example": "U1DT3NA00-CN" }, "model": { - "description": "Identifier of the model of the device.", "type": "string", - "example": "solo", + "description": "Identifier of the model of the device.", "enum": [ "solo", "virtual-solo" - ] + ], + "example": "solo" } }, "required": [ @@ -9660,21 +9559,14 @@ ] }, "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", + "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.", "example": "4WLFDSBF", - "maxLength": 9, - "minLength": 8 + "minLength": 8, + "maxLength": 9 }, "CreateReaderCheckoutUnprocessableEntity": { "description": "Unprocessable entity", - "type": "object", - "properties": { - "errors": { - "type": "object", - "additionalProperties": true - } - }, "example": { "DataValidation": { "description": "Validation errors for the informed fields.", @@ -9727,17 +9619,22 @@ } } }, + "properties": { + "errors": { + "additionalProperties": true, + "type": "object" + } + }, "required": [ "errors" ], - "title": "CreateReaderCheckoutUnprocessableEntity" + "title": "CreateReaderCheckoutUnprocessableEntity", + "type": "object" }, "CreateReaderCheckoutError": { "description": "Error description", - "type": "object", "properties": { "errors": { - "type": "object", "properties": { "detail": { "description": "Error message", @@ -9750,33 +9647,54 @@ }, "required": [ "type" - ] + ], + "type": "object" } }, "required": [ "errors" ], - "title": "CreateReaderCheckoutError" + "title": "CreateReaderCheckoutError", + "type": "object" }, "GetReaderCheckoutResponse": { - "type": "object", + "example": { + "data": { + "card_type": "credit", + "checkout_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", + "client_transaction_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", + "created_at": "2026-07-07T20:41:16.315434Z", + "installments": 1, + "payment_status": "pending", + "payment_type": "card", + "reader_firmware_version": "3.3.3.21", + "reader_serial_number": "1234567890", + "status": "pending", + "total_amount": { + "currency": "EUR", + "minor_unit": 2, + "value": 10000 + }, + "updated_at": "2026-07-07T20:42:18.117244Z", + "valid_until": "2026-07-07T20:41:16.315434Z" + } + }, "properties": { "data": { - "type": "object", "properties": { "card_type": { "description": "Type of the card. Required for some countries", - "type": "string", "enum": [ "credit", "debit" ], - "nullable": true + "nullable": true, + "type": "string" }, "checkout_id": { "description": "Unique identifier for the checkout", - "type": "string", - "format": "uuid" + "format": "uuid", + "type": "string" }, "client_transaction_id": { "description": "Client transaction identifier associated with the checkout", @@ -9784,31 +9702,31 @@ }, "created_at": { "description": "Checkout creation timestamp", - "type": "string", - "format": "date-time" + "format": "date-time", + "type": "string" }, "installments": { "description": "Number of installments for the transaction. Required for some countries.", - "type": "integer", - "nullable": true + "nullable": true, + "type": "integer" }, "payment_failure_reason": { "description": "Payment failure reason", - "type": "string", - "nullable": true + "nullable": true, + "type": "string" }, "payment_status": { "description": "Payment status from payments v2 event", - "type": "string", - "nullable": true + "nullable": true, + "type": "string" }, "payment_type": { "description": "Type of the payment. Required for some countries", - "type": "string", "enum": [ "card", "pix" - ] + ], + "type": "string" }, "reader_firmware_version": { "description": "Reader firmware version", @@ -9820,17 +9738,16 @@ }, "status": { "description": "Current status of the checkout", - "type": "string", "enum": [ "pending", "successful", "failed", "cancelled" - ] + ], + "type": "string" }, "total_amount": { "description": "Amount structure.\n\nThe amount is represented as an integer value altogether with the currency and the minor unit.\n\nFor example, EUR 1.00 is represented as value 100 with minor unit of 2.\n", - "type": "object", "example": { "currency": "EUR", "minor_unit": 2, @@ -9839,20 +9756,20 @@ "properties": { "currency": { "description": "Currency ISO 4217 code", - "type": "string", - "example": "EUR" + "example": "EUR", + "type": "string" }, "minor_unit": { "description": "The minor units of the currency.\nIt represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.\n", - "type": "integer", "example": 2, - "minimum": 0 + "minimum": 0, + "type": "integer" }, "value": { "description": "Integer value of the amount.", - "type": "integer", "example": 1000, - "minimum": 0 + "minimum": 0, + "type": "integer" } }, "required": [ @@ -9860,18 +9777,19 @@ "minor_unit", "value" ], - "title": "Money" + "title": "Money", + "type": "object" }, "updated_at": { "description": "Checkout last update timestamp", - "type": "string", - "format": "date-time" + "format": "date-time", + "type": "string" }, "valid_until": { "description": "Checkout expiration timestamp. After this time, the checkout will be automatically cancelled.", - "type": "string", "format": "date-time", - "nullable": true + "nullable": true, + "type": "string" } }, "required": [ @@ -9888,59 +9806,47 @@ "updated_at", "status", "total_amount" - ] - } - }, - "example": { - "data": { - "card_type": "credit", - "checkout_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", - "client_transaction_id": "00e33a36-c99b-4cb2-b635-b90c1455c9c8", - "created_at": "2026-07-07T20:41:16.315434Z", - "installments": 1, - "payment_status": "pending", - "payment_type": "card", - "reader_firmware_version": "3.3.3.21", - "reader_serial_number": "1234567890", - "status": "pending", - "total_amount": { - "currency": "EUR", - "minor_unit": 2, - "value": 10000 - }, - "updated_at": "2026-07-07T20:42:18.117244Z", - "valid_until": "2026-07-07T20:41:16.315434Z" + ], + "type": "object" } }, "required": [ "data" ], - "title": "GetReaderCheckoutResponse" + "title": "GetReaderCheckoutResponse", + "type": "object" }, "StatusResponse": { "description": "Status of a device", - "type": "object", + "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" + } + }, "properties": { "data": { - "type": "object", "properties": { "battery_level": { "description": "Battery level percentage", - "type": "number", - "format": "float", "example": 10.5, + "format": "float", "maximum": 100, - "minimum": 0 + "minimum": 0, + "type": "number" }, "battery_temperature": { "description": "Battery temperature in Celsius", - "type": "integer", - "example": 35 + "example": 35, + "type": "integer" }, "connection_type": { "description": "Type of connection used by the device", - "type": "string", - "example": "Wi-Fi", "enum": [ "btle", "edge", @@ -9949,23 +9855,23 @@ "umts", "usb", "Wi-Fi" - ] + ], + "example": "Wi-Fi", + "type": "string" }, "firmware_version": { "description": "Firmware version of the device", - "type": "string", - "example": "3.3.3.21" + "example": "3.3.3.21", + "type": "string" }, "last_activity": { "description": "Timestamp of the last activity from the device", - "type": "string", + "example": "2025-09-25T15:20:00Z", "format": "date-time", - "example": "2025-09-25T15:20:00Z" + "type": "string" }, "state": { "description": "Latest state of the device", - "type": "string", - "example": "IDLE", "enum": [ "IDLE", "SELECTING_TIP", @@ -9973,48 +9879,34 @@ "WAITING_FOR_PIN", "WAITING_FOR_SIGNATURE", "UPDATING_FIRMWARE" - ] + ], + "example": "IDLE", + "type": "string" }, "status": { "description": "Status of a device", - "type": "string", - "example": "ONLINE", "enum": [ "ONLINE", "OFFLINE" - ] + ], + "example": "ONLINE", + "type": "string" } }, "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" + ], + "type": "object" } }, "required": [ "data" ], - "title": "StatusResponse" + "title": "StatusResponse", + "type": "object" }, "CreateReaderTerminateUnprocessableEntity": { "description": "Unprocessable entity", - "type": "object", - "properties": { - "errors": { - "type": "object", - "additionalProperties": true - } - }, "example": { "ReaderOffline": { "description": "Error returned when the target device is not online.", @@ -10026,17 +9918,22 @@ } } }, + "properties": { + "errors": { + "additionalProperties": true, + "type": "object" + } + }, "required": [ "errors" ], - "title": "CreateReaderTerminateUnprocessableEntity" + "title": "CreateReaderTerminateUnprocessableEntity", + "type": "object" }, "CreateReaderTerminateError": { "description": "Error description", - "type": "object", "properties": { "errors": { - "type": "object", "properties": { "detail": { "description": "Error message", @@ -10049,20 +9946,26 @@ }, "required": [ "type" - ] + ], + "type": "object" } }, "required": [ "errors" ], - "title": "CreateReaderTerminateError" + "title": "CreateReaderTerminateError", + "type": "object" }, "BadRequest": { "description": "400 Bad Request", - "type": "object", + "example": { + "errors": { + "detail": "Bad request", + "type": "INVALID_BEARER_TOKEN" + } + }, "properties": { "errors": { - "type": "object", "properties": { "detail": { "description": "Fuller message giving context to error", @@ -10070,70 +9973,69 @@ }, "type": { "description": "Key indicating type of error", - "type": "string", "enum": [ "INVALID_BEARER_TOKEN", "INVALID_USER_AGENT", "NOT_ENOUGH_UNPAID_PAYOUTS", "DUPLICATE_HEADERS" - ] + ], + "type": "string" } }, "required": [ "type" - ] - } - }, - "example": { - "errors": { - "detail": "Bad request", - "type": "INVALID_BEARER_TOKEN" + ], + "type": "object" } }, "required": [ "errors" ], - "title": "BadRequest" + "title": "BadRequest", + "type": "object" }, "CreateReaderCheckoutResponse": { - "type": "object", + "example": { + "data": { + "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + } + }, "properties": { "data": { - "type": "object", "properties": { "checkout_id": { "description": "The checkout ID is a unique identifier for the checkout.\n", - "type": "string", - "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "type": "string" }, "client_transaction_id": { "description": "The client transaction ID is a unique identifier for the transaction that is generated for the client.\n\nIt can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", - "type": "string", - "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "type": "string" } }, "required": [ "client_transaction_id" - ] - } - }, - "example": { - "data": { - "checkout_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "client_transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + ], + "type": "object" } }, "required": [ "data" ], - "title": "CreateReaderCheckoutResponse" + "title": "CreateReaderCheckoutResponse", + "type": "object" }, "Unauthorized": { "description": "401 Unauthorized", - "type": "object", + "example": { + "errors": { + "detail": "Unauthorized" + } + }, "properties": { "errors": { - "type": "object", "properties": { "detail": { "description": "Fuller message giving context to error", @@ -10141,86 +10043,109 @@ }, "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" - ] + ], + "type": "string" } }, "required": [ "detail" - ] - } - }, - "example": { - "errors": { - "detail": "Unauthorized" + ], + "type": "object" } }, "required": [ "errors" ], - "title": "Unauthorized" + "title": "Unauthorized", + "type": "object" }, "CreateReaderCheckoutRequest": { "description": "Reader Checkout", - "type": "object", + "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 + } + }, "properties": { "aade": { "description": "Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol.\nWhen such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider.\n", - "type": "object", "properties": { "provider_id": { "description": "The identifier of the AADE signature provider.", - "type": "string", - "example": "123" + "example": "123", + "type": "string" }, "signature": { "description": "The base64 encoded signature of the transaction data.", - "type": "string", - "example": "QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5" + "example": "QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5", + "type": "string" }, "signature_data": { "description": "The string containing the signed transaction data.", - "type": "string", - "example": "B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039" + "example": "B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039", + "type": "string" } }, "required": [ "provider_id", "signature", "signature_data" - ] + ], + "type": "object" }, "affiliate": { "description": "Affiliate metadata for the transaction.\nIt is a field that allow for integrators to track the source of the transaction.\n", - "type": "object", "nullable": true, "properties": { "app_id": { "description": "Application ID of the affiliate.\nIt 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.\n", - "type": "string", - "example": "com.example.app" + "example": "com.example.app", + "type": "string" }, "foreign_transaction_id": { "description": "Foreign transaction ID of the affiliate.\nIt is a unique identifier for the transaction.\nIt can be used later to fetch the transaction details via the [Transactions API](https://developer.sumup.com/api/transactions/get).\n", - "type": "string", - "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f" + "example": "19e12390-72cf-4f9f-80b5-b0c8a67fa43f", + "type": "string" }, "key": { "description": "Key of the affiliate.\nIt 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.\n", - "type": "string", - "example": "123e4567-e89b-12d3-a456-426614174000" + "example": "123e4567-e89b-12d3-a456-426614174000", + "type": "string" }, "tags": { + "additionalProperties": true, "description": "Additional metadata for the transaction.\nIt is key-value object that can be associated with the transaction.\n", - "type": "object", "example": { "custom_key_1": "custom_value_1", "custom_key_2": "custom_value_2" }, - "additionalProperties": true + "type": "object" } }, "required": [ @@ -10228,16 +10153,17 @@ "key", "foreign_transaction_id" ], - "title": "Affiliate" + "title": "Affiliate", + "type": "object" }, "card_type": { "description": "The card type of the card used for the transaction.\nIs is required only for some countries (e.g: Brazil).\n", - "type": "string", - "example": "credit", "enum": [ "credit", "debit" - ] + ], + "example": "credit", + "type": "string" }, "description": { "description": "Description of the checkout to be shown in the Merchant Sales", @@ -10245,37 +10171,36 @@ }, "installments": { "description": "Number of installments for the transaction.\nIt may vary according to the merchant country.\nFor example, in Brazil, the maximum number of installments is 12.\n\nOmit if the merchant country does support installments.\nOtherwise, the checkout will be rejected.\n", - "type": "integer", "example": 1, "minimum": 1, - "nullable": true + "nullable": true, + "type": "integer" }, "return_url": { "description": "Webhook URL to which the payment result will be sent.\nIt must be a HTTPS url.\n", - "type": "string", + "example": "https://www.example.com", "format": "uri", - "example": "https://www.example.com" + "type": "string" }, "tip_rates": { "description": "List of tipping rates to be displayed to the cardholder.\nThe rates are in percentage and should be between 0.01 and 0.99.\nThe list should be sorted in ascending order.\n", - "type": "array", "items": { "format": "float", "multipleOf": 0.01, "type": "number" - } + }, + "type": "array" }, "tip_timeout": { + "default": 30, "description": "Time in seconds the cardholder has to select a tip rate.\nIf not provided, the default value is 30 seconds.\n\nIt can only be set if `tip_rates` is provided.\n\n**Note**: If the target device is a Solo, it must be in version 3.3.38.0 or higher.\n", - "type": "integer", "example": 30, - "default": 30, "maximum": 120, - "minimum": 30 + "minimum": 30, + "type": "integer" }, "total_amount": { "description": "Amount structure.\n\nThe amount is represented as an integer value altogether with the currency and the minor unit.\n\nFor example, EUR 1.00 is represented as value 100 with minor unit of 2.\n", - "type": "object", "example": { "currency": "EUR", "minor_unit": 2, @@ -10284,20 +10209,20 @@ "properties": { "currency": { "description": "Currency ISO 4217 code", - "type": "string", - "example": "EUR" + "example": "EUR", + "type": "string" }, "minor_unit": { "description": "The minor units of the currency.\nIt represents the number of decimals of the currency. For the currencies CLP, COP and HUF, the minor unit is 0.\n", - "type": "integer", "example": 2, - "minimum": 0 + "minimum": 0, + "type": "integer" }, "value": { "description": "Integer value of the amount.", - "type": "integer", "example": 1000, - "minimum": 0 + "minimum": 0, + "type": "integer" } }, "required": [ @@ -10305,100 +10230,73 @@ "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 + "title": "Money", + "type": "object" } }, "required": [ "total_amount" ], - "title": "CreateReaderCheckoutRequest" + "title": "CreateReaderCheckoutRequest", + "type": "object" }, "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" + "example": "solo.transaction.updated", + "type": "string" }, "id": { "description": "Unique identifier for the event.", - "type": "string", + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "format": "uuid", - "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "type": "string" }, "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", + "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "format": "uuid", - "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "type": "string" }, "merchant_code": { "description": "The merchant code associated with the transaction.", - "type": "string", - "example": "M1234567" + "example": "M1234567", + "type": "string" }, "status": { "description": "The current status of the transaction.", - "type": "string", - "example": "successful", "enum": [ "successful", "failed" - ] + ], + "example": "successful", + "type": "string" }, "transaction_id": { + "deprecated": true, "description": "The transaction id. Deprecated: use `client_transaction_id` instead.", - "type": "string", - "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "deprecated": true + "format": "uuid", + "type": "string" } }, "required": [ "client_transaction_id", "merchant_code", "status" - ] + ], + "type": "object" }, "timestamp": { "description": "Timestamp of the event.", - "type": "string", + "example": "2023-10-05T14:48:00Z", "format": "date-time", - "example": "2023-10-05T14:48:00Z" + "type": "string" } }, "required": [ @@ -10407,14 +10305,18 @@ "payload", "timestamp" ], - "title": "ReaderCheckoutStatusChange" + "title": "ReaderCheckoutStatusChange", + "type": "object" }, "NotFound": { "description": "404 Not Found", - "type": "object", + "example": { + "errors": { + "detail": "Not Found" + } + }, "properties": { "errors": { - "type": "object", "properties": { "detail": { "description": "Fuller message giving context to error", @@ -10423,50 +10325,15 @@ }, "required": [ "detail" - ] - } - }, - "example": { - "errors": { - "detail": "Not Found" + ], + "type": "object" } }, "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." + "title": "NotFound", + "type": "object" } }, "requestBodies": { @@ -10676,13 +10543,13 @@ "amount": 5 }, "schema": { - "description": "Optional amount for partial refunds of transactions.", "type": "object", + "description": "Optional amount for partial refunds of transactions.", "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", + "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.", "example": 5 } } @@ -11036,7 +10903,7 @@ "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz", "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5" }, - "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", + "full": "https://r3.girogate.de/ti/simideal?tx=961473700\u0026rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz\u0026cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5", "mechanism": [ "browser" ] @@ -11054,7 +10921,7 @@ "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB", "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc" }, - "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", + "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471\u0026rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB\u0026cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc", "mechanism": [ "browser" ] @@ -11276,6 +11143,10 @@ "application/json": { "schema": { "type": "object", + "required": [ + "total_count", + "items" + ], "properties": { "items": { "type": "array", @@ -11287,11 +11158,7 @@ "type": "integer", "example": 3 } - }, - "required": [ - "total_count", - "items" - ] + } } } } @@ -11302,6 +11169,9 @@ "application/json": { "schema": { "type": "object", + "required": [ + "items" + ], "properties": { "items": { "type": "array", @@ -11313,10 +11183,7 @@ "type": "integer", "example": 3 } - }, - "required": [ - "items" - ] + } } } } @@ -11327,6 +11194,9 @@ "application/json": { "schema": { "type": "object", + "required": [ + "items" + ], "properties": { "items": { "type": "array", @@ -11334,15 +11204,197 @@ "$ref": "#/components/schemas/Role" } } - }, - "required": [ - "items" - ] + } } } } } }, + "parameters": { + "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" + } + }, + "CheckoutID": { + "name": "checkout_id", + "in": "path", + "required": true, + "description": "Unique ID of the checkout resource.", + "schema": { + "type": "string" + } + }, + "CustomerID": { + "name": "customer_id", + "in": "path", + "required": true, + "description": "Unique ID of the saved customer resource.", + "schema": { + "type": "string" + } + }, + "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" + } + }, + "OrderFilter": { + "name": "order", + "in": "query", + "description": "Specifies the order in which the returned results are displayed.", + "schema": { + "type": "string", + "enum": [ + "ascending", + "descending" + ], + "default": "ascending" + } + }, + "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" + } + }, + "UsersFilter": { + "name": "users[]", + "in": "query", + "description": "Filters the returned results by user email.", + "required": false, + "example": [ + "merchant@example.com" + ], + "schema": { + "type": "array", + "example": [ + "merchant@example.com" + ], + "items": { + "type": "string", + "format": "email" + } + } + }, + "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" + ] + } + } + }, + "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" + } + } + }, + "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" + } + } + }, + "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" + ] + } + } + }, + "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" + } + }, + "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" + } + }, + "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" + } + }, + "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" + } + } + }, "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)", @@ -11399,90 +11451,38 @@ } } } - } - }, - "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.\n\nUse this tag to:\n- create a checkout before collecting or confirming payment details\n- process the checkout with a card, saved card, wallet, or supported alternative payment method\n- retrieve or list checkouts to inspect their current state and associated payment attempts\n- deactivate a checkout that should no longer be used\n\nTypical workflow:\n- create a checkout with the order amount, currency, and merchant information\n- process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts)\n- retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record\n\nCheckouts 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.\n\nThis will prevent re-entering payment instrument information for recurring payments on your platform.\n\nDepending 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.\n\nIn 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:\n- `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant\n- `REFUND`: money returned to the payer\n- `CHARGE_BACK`: money reversed after the original payment\n- `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback\n\nFrom an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to:\n- list transactions for reporting, reconciliation, and customer support workflows\n- retrieve a single transaction when you need the latest payment details\n- inspect `simple_status` for the current merchant-facing outcome of the payment\n- inspect `events` or `transaction_events` when you need refund, payout, or chargeback history\n\nTypical workflow:\n- create and process payments through the Checkouts endpoints\n- use the Transactions endpoints to read the resulting payment records\n- 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.\n\nYou 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": "Readers" - }, - { - "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" + "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" } - ], - "x-beta": true + } }, - { - "name": "Merchants", - "description": "A Merchant represents a single business which can use SumUp products like payment processing.", - "x-core-objects": [ - { - "$ref": "#/components/schemas/Merchant" - } - ] + "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." + } } - ] + } } \ No newline at end of file From 1fae1af29e8d4835b3050c3231c4b46a40f40cb0 Mon Sep 17 00:00:00 2001 From: appscisumup Date: Mon, 3 Aug 2026 16:17:25 +0000 Subject: [PATCH 2/2] chore: synced local 'openapi.yaml' with remote 'specs/openapi.yaml' --- openapi.yaml | 4852 ++++++++++++++++++++++++++------------------------ 1 file changed, 2526 insertions(+), 2326 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index b000c84a..4a78baf9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.1 +openapi: 3.0.3 info: title: SumUp REST API version: 1.0.0 @@ -7,36 +7,126 @@ info: 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 + name: "Apache 2.0" + url: "https://www.apache.org/licenses/LICENSE-2.0.html" servers: - url: https://api.sumup.com description: Production server +tags: + - name: 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: Readers + - 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: >- + A Merchant represents a single business which can use SumUp products like payment processing. + x-core-objects: + - $ref: "#/components/schemas/Merchant" 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. + description: |- + Get payment methods available for the given merchant to use with a checkout. + tags: + - Checkouts + x-codegen: + method_name: list_available_payment_methods + x-scopes: [] parameters: - - name: merchant_code - in: path - description: The SumUp merchant code. + - in: path + name: merchant_code required: true + description: The SumUp merchant code. schema: type: string example: MH4H92C7 - - name: amount - in: query - description: The amount for which the payment methods should be eligible, in major units. + - in: query + name: amount required: false + description: |- + The amount for which the payment methods should be eligible, in major units. schema: type: number example: 9.99 - - name: currency - in: query - description: The currency for which the payment methods should be eligible. + - in: query + name: currency required: false + description: The currency for which the payment methods should be eligible. schema: type: string example: EUR @@ -50,18 +140,18 @@ paths: properties: available_payment_methods: type: array + example: + - id: apple_pay + - id: blik items: type: object required: - id properties: id: - description: The ID of the payment method. type: string + description: The ID of the payment method. example: qr_code_pix - example: - - id: apple_pay - - id: blik examples: success: description: Available payment methods @@ -80,18 +170,14 @@ paths: description: One or more of the parameters are invalid. value: failed_constraints: - - message: Currency must also be specified when filtering by amount + - 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 @@ -103,9 +189,21 @@ paths: 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. + tags: + - Checkouts + security: + - apiKey: [] + - oauth2: + - payments + - checkouts.write + x-codegen: + method_name: create + x-scopes: + - payments + - checkouts.write requestBody: - description: Details for creating a checkout resource. required: true + description: Details for creating a checkout resource. content: application/json: schema: @@ -119,7 +217,7 @@ paths: currency: EUR merchant_code: MH4H92C7 description: Purchase - valid_until: 2020-02-29T10:56:56+00:00 + valid_until: '2020-02-29T10:56:56+00:00' redirect_url: https://sumup.com Checkout3DS: description: Create a 3DS checkout @@ -171,8 +269,8 @@ paths: 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 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent @@ -183,7 +281,7 @@ paths: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -202,8 +300,8 @@ paths: 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 + 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: @@ -211,7 +309,7 @@ paths: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -231,7 +329,7 @@ paths: return_url: http://example.com id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING - date: 2021-06-29T11:08:36.000+00:00 + date: '2021-06-29T11:08:36.000+00:00' merchant_name: My company merchant_country: DE redirect_url: https://sumup.com @@ -241,7 +339,7 @@ paths: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -262,7 +360,7 @@ paths: description: A sample checkout id: 64553e20-3f0e-49e4-8af3-fd0eca86ce91 status: PENDING - date: 2000-01-01T12:49:24.899+00:00 + date: '2000-01-01T12:49:24.899+00:00' purpose: CHECKOUT hosted_checkout: enabled: true @@ -304,7 +402,8 @@ paths: $ref: '#/components/schemas/ErrorForbidden' examples: Forbidden: - description: You do not have the required permission for making this request. + description: |- + You do not have the required permission for making this request. value: error_message: checkout_payments_not_allowed error_code: FORBIDDEN @@ -317,26 +416,29 @@ paths: $ref: '#/components/schemas/Error' examples: Existing_Checkout: - description: A resource with the specified parameters already exists on the server. + 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 + message: >- + Checkout with this checkout reference and pay to email already exists + get: + operationId: ListCheckouts + summary: List checkouts + description: |- + Lists created checkout resources according to the applied `checkout_reference`. + tags: + - Checkouts security: - apiKey: [] - oauth2: - payments - - checkouts.write - tags: - - Checkouts + - checkouts.read x-codegen: - method_name: create + method_name: list x-scopes: - payments - - checkouts.write - get: - operationId: ListCheckouts - summary: List checkouts - description: Lists created checkout resources according to the applied `checkout_reference`. + - checkouts.read parameters: - name: checkout_reference in: query @@ -361,7 +463,7 @@ paths: description: Purchase id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' '401': description: The request is not authorized. content: @@ -377,30 +479,31 @@ paths: title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: https://developer.sumup.com/problem/unauthorized - security: - - apiKey: [] - - oauth2: - - payments - - checkouts.read - tags: - - Checkouts - x-codegen: - method_name: list - x-scopes: - - payments - - checkouts.read /v0.1/checkouts/{checkout_id}: parameters: - name: checkout_id in: path - description: Unique ID of the checkout resource. required: true + description: Unique ID of the checkout resource. 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. + description: |- + Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively. + tags: + - Checkouts + security: + - apiKey: [] + - oauth2: + - payments + - checkouts.read + x-codegen: + method_name: get + x-scopes: + - payments + - checkouts.read responses: '200': description: Returns the requested checkout resource. @@ -416,7 +519,7 @@ paths: description: Purchase id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 '401': @@ -446,25 +549,26 @@ paths: value: error_code: NOT_FOUND message: Resource not found + patch: + operationId: UpdateCheckout + summary: Update a checkout + description: |- + Updates an identified checkout resource. + tags: + - Checkouts security: - apiKey: [] - oauth2: - payments - - checkouts.read - tags: - - Checkouts + - checkouts.write x-codegen: - method_name: get + method_name: update x-scopes: - payments - - checkouts.read - patch: - operationId: UpdateCheckout - summary: Update a checkout - description: Updates an identified checkout resource. + - checkouts.write requestBody: - description: Details for updating a checkout resource. required: true + description: Details for updating a checkout resource. content: application/json: schema: @@ -474,7 +578,7 @@ paths: currency: EUR description: Updated purchase checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 - valid_until: 2020-02-29T10:56:56+00:00 + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 responses: '200': @@ -492,8 +596,8 @@ paths: description: Updated purchase 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 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 transactions: [] '401': @@ -523,28 +627,28 @@ paths: value: error_code: NOT_FOUND message: Resource not found + 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. + tags: + - Checkouts security: - apiKey: [] - oauth2: - payments - checkouts.write - tags: - - Checkouts x-codegen: - method_name: update + method_name: process x-scopes: - payments - checkouts.write - 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 + description: Details of the payment instrument for processing the checkout. content: application/json: schema: @@ -557,7 +661,8 @@ paths: 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_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 @@ -628,8 +733,8 @@ paths: 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 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent @@ -640,7 +745,7 @@ paths: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -661,7 +766,7 @@ paths: description: Purchase with token id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_name: Sample Merchant @@ -674,7 +779,7 @@ paths: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -693,11 +798,12 @@ paths: description: Boleto checkout id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2021-07-06T12:34:02.000+00:00 + 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 + url: >- + https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto redirect_url: https://website.com purpose: CHECKOUT transactions: @@ -708,7 +814,7 @@ paths: vat_amount: 6 tip_amount: 3 currency: BRL - timestamp: 2021-07-06T12:34:16.460+00:00 + timestamp: '2021-07-06T12:34:16.460+00:00' status: PENDING payment_type: BOLETO entry_mode: BOLETO @@ -722,8 +828,10 @@ paths: payload: tx: '961473700' rs: ILnaUeQTKJ184fVrjGILrLjePX9E4rmz - cs: c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 - full: https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 + cs: >- + c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 + full: >- + https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 mechanism: - browser CheckoutSuccessBancontact: @@ -735,8 +843,10 @@ paths: payload: tx: '624788471' rs: 5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB - cs: 697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc - full: https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc + cs: >- + 697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc + full: >- + https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc mechanism: - browser '202': @@ -814,22 +924,23 @@ paths: value: error_code: CHECKOUT_PROCESSED message: Checkout is already processed + 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. + tags: + - Checkouts security: - apiKey: [] - oauth2: - payments - checkouts.write - tags: - - Checkouts x-codegen: - method_name: process + method_name: deactivate x-scopes: - payments - checkouts.write - 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. @@ -846,8 +957,8 @@ paths: description: Deletion example purpose: CHECKOUT status: EXPIRED - date: 2020-02-29T10:56:56+00:00 - valid_until: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' merchant_name: Sample Merchant transactions: [] '401': @@ -889,18 +1000,6 @@ paths: value: error_code: CHECKOUT_PROCESSED message: Checkout is already processed - security: - - apiKey: [] - - oauth2: - - payments - - checkouts.write - tags: - - Checkouts - x-codegen: - method_name: deactivate - x-scopes: - - payments - - checkouts.write /v0.2/checkouts/{checkout_id}/apple-pay-session: put: operationId: CreateApplePaySession @@ -912,33 +1011,38 @@ paths: `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. + tags: + - Checkouts parameters: - name: checkout_id in: path - description: Unique ID of the checkout resource. required: true + description: Unique ID of the checkout resource. schema: type: string + x-codegen: + method_name: create_apple_pay_session + x-scopes: [] requestBody: description: The data needed to create an apple pay session for a checkout. content: application/json: schema: type: object + required: + - context + - target properties: context: - description: the context to create this apple pay session. type: string + description: the context to create this apple pay session. format: hostname example: example.com target: - description: The target url to create this apple pay session. type: string + description: The target url to create this apple pay session. format: uri example: https://apple-pay-gateway-cert.apple.com/paymentservices/startSession - required: - - context - - target responses: '200': description: | @@ -990,27 +1094,35 @@ paths: 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: + description: |- + Creates a new saved customer resource which you can later manipulate and save payment instruments to. + tags: + - Customers + security: + - apiKey: [] + - oauth2: + - payment_instruments + - customers.write + x-codegen: + method_name: create + x-scopes: + - payment_instruments + - customers.write + requestBody: + required: true + description: Details of the customer. + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + responses: + '201': + description: Returns the customer resource. + content: application/json: schema: $ref: '#/components/schemas/Customer' @@ -1076,34 +1188,36 @@ paths: $ref: '#/components/schemas/Error' examples: Existing_Customer: - description: A resource with the specified identifier already exists on the server. + 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 - - customers.write - tags: - - Customers - x-codegen: - method_name: create - x-scopes: - - payment_instruments - - customers.write /v0.1/customers/{customer_id}: parameters: - name: customer_id in: path - description: Unique ID of the saved customer resource. required: true + description: Unique ID of the saved customer resource. 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. + description: |- + Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation. + tags: + - Customers + security: + - apiKey: [] + - oauth2: + - payment_instruments + - customers.read + x-codegen: + method_name: get + x-scopes: + - payment_instruments + - customers.read responses: '200': description: Returns the customer resource. @@ -1151,18 +1265,6 @@ paths: value: error_code: NOT_FOUND message: Resource not found - security: - - apiKey: [] - - oauth2: - - payment_instruments - - customers.read - tags: - - Customers - x-codegen: - method_name: get - x-scopes: - - payment_instruments - - customers.read put: operationId: UpdateCustomer summary: Update a customer @@ -1170,9 +1272,21 @@ paths: 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. + tags: + - Customers + security: + - apiKey: [] + - oauth2: + - payment_instruments + - customers.write + x-codegen: + method_name: update + x-scopes: + - payment_instruments + - customers.write requestBody: - description: Customer fields to update. required: true + description: Customer fields to update. content: application/json: schema: @@ -1227,30 +1341,31 @@ paths: value: error_code: NOT_FOUND message: Resource not found - security: - - apiKey: [] - - oauth2: - - payment_instruments - - customers.write - tags: - - Customers - x-codegen: - method_name: update - x-scopes: - - payment_instruments - - customers.write /v0.1/customers/{customer_id}/payment-instruments: parameters: - name: customer_id in: path - description: Unique ID of the saved customer resource. required: true + description: Unique ID of the saved customer resource. schema: type: string get: operationId: ListPaymentInstruments summary: List payment instruments - description: Lists all payment instrument resources that are saved for an identified customer. + description: |- + Lists all payment instrument resources that are saved for an identified customer. + tags: + - Customers + security: + - apiKey: [] + - oauth2: + - payment_instruments + - customers.read + x-codegen: + method_name: list_payment_instruments + x-scopes: + - payment_instruments + - customers.read responses: '200': description: Returns the list of saved payment instruments for the customer. @@ -1300,36 +1415,38 @@ paths: value: error_code: NOT_FOUND message: Resource not found - security: - - apiKey: [] - - oauth2: - - payment_instruments - - customers.read - tags: - - Customers - x-codegen: - method_name: list_payment_instruments - x-scopes: - - payment_instruments - - customers.read /v0.1/customers/{customer_id}/payment-instruments/{token}: parameters: - name: customer_id in: path - description: Unique ID of the saved customer resource. required: true + description: Unique ID of the saved customer resource. schema: type: string - name: token in: path - description: Unique token identifying the card saved as a payment instrument resource. required: true + description: |- + Unique token identifying the card saved as a payment instrument resource. schema: type: string delete: operationId: DeactivatePaymentInstrument summary: Deactivate a payment instrument - description: Deactivates an identified card payment instrument resource for a customer. + description: |- + Deactivates an identified card payment instrument resource for a customer. + tags: + - Customers + security: + - apiKey: [] + - oauth2: + - payment_instruments + - customers.write + x-codegen: + method_name: deactivate_payment_instrument + x-scopes: + - payment_instruments + - customers.write responses: '204': description: Returns an empty response body when the operation succeeds. @@ -1385,18 +1502,6 @@ paths: value: error_code: NOT_FOUND message: Resource not found - security: - - apiKey: [] - - oauth2: - - payment_instruments - - customers.write - tags: - - Customers - x-codegen: - method_name: deactivate_payment_instrument - x-scopes: - - payment_instruments - - customers.write /v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds: parameters: - name: merchant_code @@ -1408,14 +1513,26 @@ paths: example: MH4H92C7 - name: transaction_id in: path - description: Unique ID of the transaction. required: true + description: Unique ID of the transaction. schema: type: string post: operationId: RefundTransaction summary: Refund a transaction description: Refunds an identified transaction either in full or partially. + tags: + - Transactions + security: + - apiKey: [] + - oauth2: + - payments + - refunds.write + x-codegen: + method_name: refund + x-scopes: + - payments + - refunds.write requestBody: description: Optional amount for partial refunds. content: @@ -1423,13 +1540,14 @@ paths: example: amount: 5 schema: - description: Optional amount for partial refunds of transactions. type: object + description: Optional amount for partial refunds of transactions. 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 + 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. example: 5 responses: '201': @@ -1489,7 +1607,8 @@ paths: $ref: '#/components/schemas/Problem' examples: Transaction_Not_Refundable: - description: The state of the identified transaction resource does not permit the requested operation. + description: |- + The state of the identified transaction resource does not permit the requested operation. value: type: https://developer.sumup.com/problem/conflict title: Conflict @@ -1514,18 +1633,6 @@ paths: detail: Amount exceeds the refundable amount reason: amount_too_high max_refundable_amount: 1000 - security: - - apiKey: [] - - oauth2: - - payments - - refunds.write - tags: - - Transactions - x-codegen: - method_name: refund - x-scopes: - - payments - - refunds.write /v2.1/merchants/{merchant_code}/transactions: get: operationId: GetTransactionV2.1 @@ -1536,6 +1643,18 @@ paths: - `transaction_code` - `foreign_transaction_id` - `client_transaction_id` + tags: + - Transactions + security: + - apiKey: [] + - oauth2: + - transactions.history + - transactions.read + x-codegen: + method_name: get + x-scopes: + - transactions.history + - transactions.read parameters: - name: merchant_code in: path @@ -1546,7 +1665,8 @@ paths: example: MH4H92C7 - name: id in: query - description: Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource). + description: |- + Retrieves the transaction resource with the specified transaction ID (the `id` parameter in the transaction resource). required: false schema: type: string @@ -1578,7 +1698,7 @@ paths: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -1614,23 +1734,24 @@ paths: value: error_code: NOT_FOUND message: Resource not found + /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. + tags: + - Transactions security: - apiKey: [] - oauth2: - transactions.history - transactions.read - tags: - - Transactions x-codegen: - method_name: get + method_name: list x-scopes: - transactions.history - transactions.read - /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 @@ -1650,31 +1771,33 @@ paths: description: Specifies the order in which the returned results are displayed. schema: type: string - default: ascending enum: - ascending - descending + default: ascending - 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. + 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 + example: + - merchant@example.com schema: type: array + example: + - merchant@example.com 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. + description: |- + Filters the returned results by the specified list of final statuses of the transactions. required: false schema: type: array @@ -1688,7 +1811,8 @@ paths: - CHARGE_BACK - name: payment_types[] in: query - description: Filters the returned results by the specified list of payment types used for the transactions. + description: |- + Filters the returned results by the specified list of payment types used for the transactions. required: false schema: type: array @@ -1716,34 +1840,39 @@ paths: - 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). + 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). + 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). + 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). + 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). + 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 @@ -1757,13 +1886,11 @@ paths: 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 + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -1771,20 +1898,22 @@ paths: transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 user: merchant@example.com type: PAYMENT - payout_date: 2019-08-28 + payout_date: '2019-08-28' payout_type: BANK_ACCOUNT refunded_amount: 0 + items: + $ref: '#/components/schemas/TransactionHistory' links: type: array + example: [] items: $ref: '#/components/schemas/TransactionsHistoryLink' - example: [] example: items: - transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -1792,7 +1921,7 @@ paths: transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 user: merchant@example.com type: PAYMENT - payout_date: 2019-08-28 + payout_date: '2019-08-28' payout_type: BANK_ACCOUNT refunded_amount: 0 links: [] @@ -1823,22 +1952,10 @@ paths: title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: https://developer.sumup.com/problem/unauthorized - security: - - apiKey: [] - - oauth2: - - transactions.history - - transactions.read - tags: - - Transactions - x-codegen: - method_name: list - x-scopes: - - transactions.history - - transactions.read /v1.0/merchants/{merchant_code}/payouts: get: - operationId: ListPayoutsV1 summary: List payouts + operationId: ListPayoutsV1 description: |- Lists payout and payout-deduction records for the specified merchant account within the requested date range. @@ -1847,6 +1964,20 @@ paths: - deduction records for refunds, chargebacks, direct debit returns, or balance adjustments Results are sorted by payout date in the requested `order`. + tags: + - Payouts + security: + - apiKey: [] + - oauth2: + - user.profile + - user.profile_readonly + - payouts.read + x-codegen: + method_name: list + x-scopes: + - user.profile + - user.profile_readonly + - payouts.read parameters: - name: merchant_code in: path @@ -1855,53 +1986,55 @@ paths: 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`). + - in: query + name: start_date + 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`. + example: '2024-02-01' + - in: query + name: end_date + 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 + example: '2024-02-29' + - in: query + name: format description: Response format for the payout list. required: false schema: type: string - example: json - default: json enum: - json - csv - - name: limit - in: query + default: json + example: json + - in: query + name: limit description: Maximum number of payout records to return. required: false schema: type: integer - example: 10 - maximum: 9999 minimum: 1 - - name: order - in: query + maximum: 9999 + example: 10 + - in: query + name: order description: Sort direction for the returned payouts. required: false schema: type: string - example: desc - default: asc enum: - asc - desc + default: asc + example: desc responses: '200': description: Returns the list of payout and deduction records for the requested period. @@ -1912,7 +2045,7 @@ paths: example: - amount: 132.45 currency: EUR - date: 2024-02-29 + date: '2024-02-29' fee: 3.12 id: 123456789 reference: payout-2024-02-29 @@ -1921,8 +2054,8 @@ paths: type: PAYOUT text/plain: schema: - description: CSV-formatted payout export returned when `format=csv`. type: string + description: CSV-formatted payout export returned when `format=csv`. 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 @@ -1945,7 +2078,7 @@ paths: message: 'Validation error: required' param: end_date Invalid date range: - description: '`start_date` cannot be later than `end_date`.' + description: "`start_date` cannot be later than `end_date`." value: - error_code: INVALID message: negative date range @@ -1964,40 +2097,36 @@ paths: title: Unauthorized trace_id: 3c77294349d3b5647ea2d990f0d8f017 type: https://developer.sumup.com/problem/unauthorized - security: - - apiKey: [] - - oauth2: - - user.profile - - user.profile_readonly - - payouts.read - tags: - - Payouts - x-codegen: - method_name: list - x-scopes: - - user.profile - - user.profile_readonly - - payouts.read /v1.1/receipts/{transaction_id}: get: operationId: GetReceipt summary: Retrieve receipt details description: Retrieves receipt specific data for a transaction. + tags: + - Receipts + security: + - apiKey: [] + - oauth2: + - receipts.read + x-codegen: + method_name: get + x-scopes: + - receipts.read parameters: - - name: transaction_id - in: path + - in: path + name: transaction_id description: SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD. required: true schema: type: string - - name: mid - in: query + - in: query + name: mid description: Merchant code. required: true schema: type: string - - name: tx_event_id - in: query + - in: query + name: tx_event_id description: The ID of the transaction event (refund). required: false schema: @@ -2018,7 +2147,7 @@ paths: vat_amount: '6.00' tip_amount: '3.00' currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM entry_mode: CUSTOMER_ENTRY @@ -2068,34 +2197,23 @@ paths: value: message: No such tx event (ID=9567461191) for transaction 4ffb8dfc-7f2b-413d-a497-2ad00766585e error_code: NOT_FOUND - security: - - apiKey: [] - - oauth2: - - receipts.read - tags: - - Receipts - x-codegen: - method_name: get - x-scopes: - - receipts.read /v0/merchants/{merchant_code}/readers/{reader_id}/go-checkout: post: - operationId: CreateGoReaderCheckout - summary: Create a Go Reader Payment description: |- Initiates a payment on the SumUp Go terminal identified by the reader ID. Use `client_transaction_id` as an idempotency key: retrying the request with the same value returns the result of the original payment instead of creating a duplicate. + operationId: CreateGoReaderCheckout parameters: - - name: Authorization + - description: Access token in the format 'Bearer {token}'. in: header - description: Access token in the format 'Bearer {token}'. + name: Authorization required: true schema: type: string - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string @@ -2107,20 +2225,20 @@ paths: schema: $ref: '#/components/schemas/ReaderID' requestBody: - description: Payment details to initiate on the reader. required: true + description: Payment details to initiate on the reader. content: application/json: schema: $ref: '#/components/schemas/ReaderPaymentRequestParams' responses: - '200': + "200": description: Returns the result of the payment initiated on the reader. content: application/json: schema: $ref: '#/components/schemas/ReaderPaymentResponse' - '400': + "400": description: The request is invalid. content: application/problem+json: @@ -2131,7 +2249,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '401': + "401": description: Authentication failed or missing required scope. content: application/problem+json: @@ -2142,7 +2260,7 @@ paths: title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. - '404': + "404": description: The requested Reader resource does not exist. content: application/problem+json: @@ -2153,7 +2271,7 @@ paths: title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. - '422': + "422": description: The request could not be processed as it violates a business rule. content: application/problem+json: @@ -2164,7 +2282,7 @@ paths: title: Unprocessable Entity status: 422 detail: Validation failed. - '500': + "500": description: An unexpected error occurred while processing the request. content: application/problem+json: @@ -2175,44 +2293,53 @@ paths: title: Internal Server Error status: 500 detail: An unexpected error occurred while processing the request. - security: - - apiKey: [] - - oauth2: - - payments - - readers.write + summary: Create a Go Reader Payment tags: - Readers + x-scopes: [payments, readers.write] + x-permissions: + - readers_checkout_create x-codegen: method_name: create_go_checkout ignore: true - x-permissions: - - readers_checkout_create - x-scopes: - - payments - - readers.write + security: + - apiKey: [] + - oauth2: + - payments + - readers.write /v0.1/memberships: get: - operationId: ListMemberships summary: List memberships description: List memberships of the current user. + tags: + - Memberships + operationId: ListMemberships + x-codegen: + method_name: list + x-scopes: ["user.profile", "user.profile_readonly"] + security: + - apiKey: [] + - oauth2: + - user.profile + - user.profile_readonly parameters: - name: offset in: query description: Offset of the first member to return. schema: type: integer - example: 0 default: 0 minimum: 0 + example: 0 - name: limit in: query description: Maximum number of members to return. schema: type: integer - example: 10 default: 10 - maximum: 25 minimum: 1 + maximum: 25 + example: 10 - name: kind in: query description: Filter memberships by resource kind. @@ -2240,21 +2367,23 @@ paths: type: string - name: resource.parent.id in: query - description: |- + 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: |- + 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: + nullable: true allOf: - $ref: '#/components/schemas/ResourceType' - nullable: true - name: roles in: query description: Filter the returned memberships by role. @@ -2262,18 +2391,19 @@ paths: type: array items: type: string - example: - - role_employee - - role_accountant - explode: true + example: [role_employee, role_accountant] style: form + explode: true responses: - '200': + "200": description: Returns a list of Membership objects. content: application/json: schema: type: object + required: + - total_count + - items properties: items: type: array @@ -2282,10 +2412,7 @@ paths: total_count: type: integer example: 3 - required: - - total_count - - items - '400': + "400": description: Invalid query parameter combination. content: application/problem+json: @@ -2296,7 +2423,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '401': + "401": description: Authentication failed or missing required scope. content: application/problem+json: @@ -2307,49 +2434,34 @@ paths: title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. - security: - - apiKey: [] - - oauth2: - - user.profile - - user.profile_readonly - tags: - - Memberships - x-codegen: - method_name: list - x-scopes: - - user.profile - - user.profile_readonly /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 + example: 0 - name: limit in: query description: Maximum number of members to return. schema: type: integer - example: 10 default: 10 - maximum: 25 minimum: 1 + maximum: 25 + example: 10 - name: scroll in: query description: Indicates to skip count query. + x-document: false schema: type: boolean - example: true default: false - x-document: false + example: true - name: email in: query description: Filter the returned members by email address prefix. @@ -2375,25 +2487,42 @@ paths: type: array items: type: string - example: - - role_employee - - role_accountant - explode: true + example: [role_employee, role_accountant] style: form + explode: true - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string example: MK10CL2A + summary: List members + description: Lists merchant members. + tags: + - Members + operationId: ListMerchantMembers + x-codegen: + method_name: list + x-permissions: + - relation: merchant_read + object_type: merchant + object_id_param: merchant_code + x-scopes: [user.subaccounts, members.read] + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - members.read responses: - '200': + "200": description: Returns a list of Member objects. content: application/json: schema: type: object + required: + - items properties: items: type: array @@ -2402,9 +2531,7 @@ paths: total_count: type: integer example: 3 - required: - - items - '404': + "404": description: Merchant not found. content: application/problem+json: @@ -2415,85 +2542,88 @@ paths: title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. + post: + operationId: CreateMerchantMember + summary: Create a member + description: Create a merchant member. + tags: + - Members security: - apiKey: [] - oauth2: - user.subaccounts - - members.read - tags: - - Members + - members.write x-codegen: - method_name: list + method_name: create x-permissions: - - relation: merchant_read + - relation: members_create object_type: merchant object_id_param: merchant_code - x-scopes: - - user.subaccounts - - members.read - 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 + x-scopes: [user.subaccounts, members.write] requestBody: required: true content: application/json: schema: type: object + required: + - email + - roles 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 + 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. email: - description: Email address of the member to add. type: string format: email + description: Email address of the member to add. maxLength: 256 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 + format: 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. 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 + example: "Test User" + description: >- + Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only. maxLength: 64 roles: - description: List of roles to assign to the new member. type: array + description: List of roles to assign to the new member. + maxItems: 124 items: type: string maxLength: 64 - maxItems: 124 metadata: $ref: '#/components/schemas/Metadata' attributes: $ref: '#/components/schemas/Attributes' example: email: karl.berg@example.com - roles: - - role_employee - required: - - email - - roles + roles: [role_employee] + # Not supported in 3.0, can be enabled once we move to 3.1 + # examples: + # "Invite a user": + # email: karl.berg@example.com + # roles: [role_employee] + # "Create a managed user": + # email: employee123@mycompany.com + # roles: [role_employee] + # nickname: "Employee 123" + # is_managed: true + # metadata: + # external_id: ced70a99-89d1-42c4-81e7-63f81cad805d responses: - '201': + "201": description: Returns the Member object if the creation succeeded. content: application/json: schema: $ref: '#/components/schemas/Member' - '400': + "400": description: Invalid request. content: application/problem+json: @@ -2504,7 +2634,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '404': + "404": description: Merchant not found. content: application/problem+json: @@ -2515,8 +2645,9 @@ paths: 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. + "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: @@ -2526,95 +2657,84 @@ paths: title: Too Many Requests status: 429 detail: Too many requests were sent. Please try again later. - security: - - apiKey: [] - - oauth2: - - user.subaccounts - - members.write - tags: - - Members - x-codegen: - method_name: create - x-permissions: - - relation: members_create - object_type: merchant - object_id_param: merchant_code - x-scopes: - - user.subaccounts - - members.write - /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: - - user.subaccounts - - members.read + example: MK10CL2A + /v0.1/merchants/{merchant_code}/members/{member_id}: + get: + summary: Retrieve a member + description: Retrieve a merchant member. tags: - Members + operationId: GetMerchantMember x-codegen: method_name: get x-permissions: - relation: members_view object_type: merchant object_id_param: merchant_code - x-scopes: - - user.subaccounts - - members.read - put: - operationId: UpdateMerchantMember - summary: Update a member - description: Update the merchant member. + x-scopes: [user.subaccounts, members.read] + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - members.read + 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. parameters: - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string example: MK10CL2A - - name: member_id - in: path + - in: path + name: member_id description: The ID of the member to retrieve. required: true schema: type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP + put: + summary: Update a member + description: Update the merchant member. + tags: + - Members + operationId: UpdateMerchantMember + x-codegen: + method_name: update + x-permissions: + - relation: members_update + object_type: merchant + object_id_param: merchant_code + x-scopes: [user.subaccounts, members.write] + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - members.write requestBody: required: true content: @@ -2624,43 +2744,43 @@ paths: properties: roles: type: array + maxItems: 124 items: type: string maxLength: 64 - maxItems: 124 metadata: $ref: '#/components/schemas/Metadata' attributes: $ref: '#/components/schemas/Attributes' user: - description: Allows you to update user data of managed users. type: object + description: Allows you to update user data of managed users. properties: nickname: - description: User's nickname. Used for display purposes only. type: string - example: Test User + example: "Test User" + description: >- + User's nickname. Used for display purposes only. maxLength: 64 password: - description: Password of the member to add. Only used if `is_managed_user` is true. type: string format: password minLength: 8 + description: Password of the member to add. Only used if `is_managed_user` is true. example: - Update member's role: - roles: - - role_manager - Update managed user: + "Update member's role": + roles: [role_manager] + "Update managed user": user: nickname: New Employee Name responses: - '200': + "200": description: Returns the updated Member object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Member' - '400': + "400": description: Cannot set password or nickname for an invited user. content: application/problem+json: @@ -2671,7 +2791,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '403': + "403": description: Cannot change password for managed user. Password was already used before. content: application/problem+json: @@ -2682,7 +2802,7 @@ paths: title: Forbidden status: 403 detail: You do not have permission to perform this action. - '404': + "404": description: Merchant or member not found. content: application/problem+json: @@ -2693,7 +2813,7 @@ paths: title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. - '409': + "409": description: Cannot update member as some data conflict with existing members. content: application/problem+json: @@ -2704,45 +2824,43 @@ paths: title: Conflict status: 409 detail: The request conflicts with the current state of the resource. - security: - - apiKey: [] - - oauth2: - - user.subaccounts - - members.write - tags: - - Members - x-codegen: - method_name: update - x-permissions: - - relation: members_update - object_type: merchant - object_id_param: merchant_code - x-scopes: - - user.subaccounts - - members.write - 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. + in: path required: true schema: type: string example: MK10CL2A - - name: member_id - in: path + - in: path + name: member_id description: The ID of the member to retrieve. required: true schema: type: string example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP + delete: + summary: Delete a member + description: Deletes a merchant member. + tags: + - Members + operationId: DeleteMerchantMember + x-codegen: + method_name: delete + x-permissions: + - relation: members_delete + object_type: merchant + object_id_param: merchant_code + x-scopes: [user.subaccounts, members.write] + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - members.write responses: - '200': + "200": description: Returns an empty response if the deletion succeeded. - '403': + "403": description: Member deletion was forbidden. content: application/problem+json: @@ -2753,7 +2871,7 @@ paths: title: Forbidden status: 403 detail: You do not have permission to perform this action. - '404': + "404": description: Merchant or member not found. content: application/problem+json: @@ -2764,50 +2882,55 @@ paths: 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: - - user.subaccounts - - members.write - tags: - - Members - x-codegen: - method_name: delete - x-permissions: - - relation: members_delete - object_type: merchant - object_id_param: merchant_code - x-scopes: - - user.subaccounts - - members.write - /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. + in: path required: true schema: type: string example: MK10CL2A + - in: path + name: member_id + description: The ID of the member to retrieve. + required: true + schema: + type: string + example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP + /v0.1/merchants/{merchant_code}/roles: + get: + summary: List roles + description: List merchant's custom roles. + tags: + - Roles + operationId: ListMerchantRoles + x-codegen: + method_name: list + x-permissions: + - relation: roles_list + object_type: merchant + object_id_param: merchant_code + x-scopes: [user.subaccounts, roles.read] + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - roles.read responses: - '200': + "200": description: Returns a list of Role objects. content: application/json: schema: type: object + required: + - items properties: items: type: array items: $ref: '#/components/schemas/Role' - required: - - items - '404': + "404": description: Merchant not found. content: application/problem+json: @@ -2818,72 +2941,73 @@ paths: title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. + parameters: + - name: merchant_code + description: Short unique identifier for the merchant. + in: path + required: true + schema: + type: string + example: MK10CL2A + 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. + tags: + - Roles security: - apiKey: [] - oauth2: - user.subaccounts - - roles.read - tags: - - Roles + - roles.write x-codegen: - method_name: list + method_name: create x-permissions: - - relation: roles_list + - relation: roles_create object_type: merchant object_id_param: merchant_code - x-scopes: - - user.subaccounts - - roles.read - 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 + x-scopes: [user.subaccounts, roles.write] requestBody: required: true content: application/json: schema: type: object + required: + - name + - permissions properties: name: - description: User-defined name of the role. type: string example: Senior Shop Manager II + description: >- + User-defined name of the role. permissions: - description: User's permissions. type: array + description: User's permissions. + maxItems: 100 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 + example: "Manges the shop and the employees." + description: >- + User-defined description of the role. responses: - '201': + "201": description: Returns the Role object after successful custom role creation. content: application/json: schema: $ref: '#/components/schemas/Role' - '400': + "400": description: Invalid request. content: application/problem+json: @@ -2894,7 +3018,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '404': + "404": description: Merchant not found. content: application/problem+json: @@ -2905,99 +3029,88 @@ paths: 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: - - user.subaccounts - - roles.write - tags: - - Roles - x-codegen: - method_name: create - x-permissions: - - relation: roles_create - object_type: merchant - object_id_param: merchant_code - x-scopes: - - user.subaccounts - - roles.write - /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: - - user.subaccounts - - roles.read + example: MK10CL2A + /v0.1/merchants/{merchant_code}/roles/{role_id}: + get: + summary: Retrieve a role + description: Retrieve a custom role by ID. tags: - Roles + operationId: GetMerchantRole x-codegen: method_name: get x-permissions: - relation: roles_view object_type: merchant object_id_param: merchant_code - x-scopes: - - user.subaccounts - - roles.read - delete: - operationId: DeleteMerchantRole - summary: Delete a role - description: Delete a custom role. + x-scopes: [user.subaccounts, roles.read] + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - roles.read + 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. parameters: - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string example: MK10CL2A - - name: role_id - in: path + - in: path + name: role_id description: The ID of the role to retrieve. required: true schema: type: string example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP + delete: + operationId: DeleteMerchantRole + summary: Delete a role + description: Delete a custom role. + tags: + - Roles + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - roles.write + x-codegen: + method_name: delete + x-permissions: + - relation: roles_delete + object_type: merchant + object_id_param: merchant_code + x-scopes: [user.subaccounts, roles.write] responses: - '200': + "200": description: Returns an empty response if the role deletion succeeded. - '400': + "400": description: Invalid request. content: application/problem+json: @@ -3008,7 +3121,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '404': + "404": description: Merchant not found. content: application/problem+json: @@ -3019,41 +3132,39 @@ paths: 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: - - user.subaccounts - - roles.write - tags: - - Roles - x-codegen: - method_name: delete - x-permissions: - - relation: roles_delete - object_type: merchant - object_id_param: merchant_code - x-scopes: - - user.subaccounts - - roles.write - 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. + in: path required: true schema: type: string example: MK10CL2A - - name: role_id - in: path + - in: path + name: role_id description: The ID of the role to retrieve. required: true schema: type: string example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP + patch: + operationId: UpdateMerchantRole + summary: Update a role + description: Update a custom role. + tags: + - Roles + security: + - apiKey: [] + - oauth2: + - user.subaccounts + - roles.write + x-codegen: + method_name: update + x-permissions: + - relation: roles_update + object_type: merchant + object_id_param: merchant_code + x-scopes: [user.subaccounts, roles.write] requestBody: required: true content: @@ -3062,37 +3173,39 @@ paths: type: object properties: name: - description: User-defined name of the role. type: string example: Senior Shop Manager II + description: >- + User-defined name of the role. permissions: - description: User's permissions. type: array + description: User's permissions. + maxItems: 100 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: "Manges the shop and the employees." + description: >- + User-defined description of the role. example: - name: Senior Shop Manager III + name: 'Senior Shop Manager III' permissions: - catalog_edit - taxes_access - members_edit responses: - '200': + "200": description: Returns the updated Role object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Role' - '400': + "400": description: Invalid request. content: application/problem+json: @@ -3103,7 +3216,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '404': + "404": description: Merchant not found. content: application/problem+json: @@ -3114,148 +3227,149 @@ paths: 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: - - user.subaccounts - - roles.write - tags: - - Roles - x-codegen: - method_name: update - x-permissions: - - relation: roles_update - object_type: merchant - object_id_param: merchant_code - x-scopes: - - user.subaccounts - - roles.write + parameters: + - name: merchant_code + description: Short unique identifier for the merchant. + in: path + required: true + schema: + type: string + example: MK10CL2A + - in: path + name: role_id + description: The ID of the role to retrieve. + required: true + schema: + type: string + example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP /v1/merchants/{merchant_code}: get: operationId: GetMerchant summary: Get Merchant - description: Returns a Merchant for a valid Merchant code. + description: >- + Returns a Merchant for a valid Merchant code. + tags: + - Merchants parameters: - name: version - in: query - description: | + 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. + + in: query schema: type: string examples: - latest - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string example: MK10CL2A + externalDocs: + description: Merchant documentation + url: https://developer.sumup.com/tools/models/merchant + x-codegen: + method_name: get + x-scopes: ["user.profile", "user.profile_readonly"] + x-permissions: [merchant_read] + security: + - apiKey: [] + - oauth2: + - user.profile + - user.profile_readonly responses: - '200': + "200": description: Returns a Merchant for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Merchant' - '404': + "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 the Persons related to a Merchant. + description: >- + Returns the Persons related to a Merchant. + tags: + - Merchants parameters: - name: version - in: query - description: | + 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. + + in: query schema: type: string examples: - latest - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string example: MK10CL2A + externalDocs: + description: Persons documentation + url: https://developer.sumup.com/tools/models/merchant#persons + x-scopes: ["user.profile", "user.profile_readonly"] + x-permissions: [persons_read] + x-codegen: + method_name: list_persons + security: + - apiKey: [] + - oauth2: + - user.profile + - user.profile_readonly responses: - '200': + "200": description: Returns a list of Persons for a valid Merchant identifier. content: application/json: schema: $ref: '#/components/schemas/ListPersonsResponseBody' - '404': + "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: Get Person - description: Returns a single Person related to a Merchant. + description: >- + Returns a single Person related to a Merchant. + tags: + - Merchants parameters: - name: version - in: query - description: | + 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. + + in: query schema: type: string examples: - latest - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string example: MK10CL2A - name: person_id - in: path description: Person ID + in: path required: true schema: type: string @@ -3263,64 +3377,65 @@ paths: x-go-type: merchants.PersonID x-go-type-import: path: github.com/sumup/merchants/internal/domain/merchants + externalDocs: + description: Persons documentation + url: https://developer.sumup.com/tools/models/merchant#persons + x-scopes: ["user.profile", "user.profile_readonly"] + x-permissions: [persons_read] + x-codegen: + method_name: get_person + security: + - apiKey: [] + - oauth2: + - user.profile + - user.profile_readonly responses: - '200': + "200": description: Returns a Person for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Person' - '404': + "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: + operationId: ListReaders + tags: + - Readers + x-codegen: + method_name: list + x-permissions: + - relation: readers_list + object_type: merchant + object_id_param: merchant_code + x-scopes: [readers.read, terminals.read] + security: + - apiKey: [] + - oauth2: + - readers.read + - terminals.read + responses: + "200": + description: Returns a list Reader objects. + content: + application/json: schema: type: object + required: + - items properties: items: type: array items: $ref: '#/components/schemas/Reader' - required: - - items - '401': + "401": description: Authentication failed or missing required scope. content: application/problem+json: @@ -3331,40 +3446,41 @@ paths: title: Unauthorized status: 401 detail: Authentication credentials are missing or invalid. - security: - - apiKey: [] - - oauth2: - - readers.read - - terminals.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 - - terminals.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. + in: path required: true schema: type: string example: MK10CL2A + post: + summary: Create a Reader + operationId: CreateReader + description: Create a new Reader for the merchant account. + tags: + - Readers + x-codegen: + method_name: create + x-permissions: + - relation: readers_create + object_type: merchant + object_id_param: merchant_code + x-scopes: [readers.write, terminals.write] + security: + - apiKey: [] + - oauth2: + - readers.write + - terminals.write requestBody: required: true content: application/json: schema: type: object + required: + - pairing_code + - name properties: pairing_code: $ref: '#/components/schemas/ReaderPairingCode' @@ -3372,11 +3488,8 @@ paths: $ref: '#/components/schemas/ReaderName' metadata: $ref: '#/components/schemas/Metadata' - required: - - pairing_code - - name responses: - '201': + "201": description: Returns the Reader object if the creation succeeded. content: application/json: @@ -3392,20 +3505,22 @@ paths: device: identifier: U1DT3NA00-CN model: solo - created_at: 2023-05-09T14:50:20.214Z - updated_at: 2023-05-09T14:52:58.714Z + 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. + 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': + reader_id: "$response.body#/id" + description: >- + Delete the reader. + "400": description: The request is invalid. content: application/problem+json: @@ -3416,7 +3531,7 @@ paths: title: Bad Request status: 400 detail: Request validation failed. - '404': + "404": description: There's no pending reader for the submitted pairing code. content: application/problem+json: @@ -3427,7 +3542,7 @@ paths: title: Requested resource couldn't be found. status: 404 detail: The requested resource doesn't exist or does not belong to you. - '409': + "409": description: The Reader is not in a pending state. content: application/problem+json: @@ -3438,30 +3553,36 @@ paths: title: Conflict status: 409 detail: The request conflicts with the current state of the resource. - security: - - apiKey: [] - - oauth2: - - readers.write - - terminals.write + parameters: + - name: merchant_code + description: Short unique identifier for the merchant. + in: path + required: true + schema: + type: string + example: MK10CL2A + /v0.1/merchants/{merchant_code}/readers/{reader_id}: + get: + summary: Retrieve a Reader + description: Retrieve a Reader. + operationId: GetReader tags: - Readers x-codegen: - method_name: create + method_name: get x-permissions: - - relation: readers_create + - relation: readers_view object_type: merchant object_id_param: merchant_code - x-scopes: - - readers.write - - terminals.write - /v0.1/merchants/{merchant_code}/readers/{reader_id}: - get: - operationId: GetReader - summary: Retrieve a Reader - description: Retrieve a Reader. + x-scopes: [readers.read, terminals.read] + security: + - apiKey: [] + - oauth2: + - readers.read + - terminals.read parameters: - - name: If-Modified-Since - in: header + - in: header + name: If-Modified-Since description: |- Return the reader only if it has been modified after the specified timestamp given in the headers. @@ -3480,8 +3601,8 @@ paths: type: string example: 2023-05-30T10:38:01+00:00 - name: merchant_code - in: path description: Short unique identifier for the merchant. + in: path required: true schema: type: string @@ -3493,13 +3614,13 @@ paths: schema: $ref: '#/components/schemas/ReaderID' responses: - '200': + "200": description: Returns a Reader object for a valid identifier. content: application/json: schema: $ref: '#/components/schemas/Reader' - '404': + "404": description: The requested Reader resource does not exist. content: application/problem+json: @@ -3510,44 +3631,28 @@ paths: 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 - - terminals.read + delete: + summary: Delete a reader + description: Delete a reader. + operationId: DeleteReader tags: - Readers x-codegen: - method_name: get + method_name: delete x-permissions: - - relation: readers_view + - relation: readers_delete object_type: merchant object_id_param: merchant_code - x-scopes: - - readers.read - - terminals.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' + x-scopes: [readers.write, terminals.write] + security: + - apiKey: [] + - oauth2: + - readers.write + - terminals.write responses: - '200': + "200": description: Returns an empty response if the deletion succeeded. - '404': + "404": description: The requested Reader resource does not exist. content: application/problem+json: @@ -3558,30 +3663,10 @@ paths: 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 - - terminals.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 - - terminals.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. + in: path required: true schema: type: string @@ -3592,6 +3677,24 @@ paths: required: true schema: $ref: '#/components/schemas/ReaderID' + patch: + summary: Update a Reader + description: Update a Reader. + operationId: UpdateReader + tags: + - Readers + x-codegen: + method_name: update + x-permissions: + - relation: readers_update + object_type: merchant + object_id_param: merchant_code + x-scopes: [readers.write, terminals.write] + security: + - apiKey: [] + - oauth2: + - readers.write + - terminals.write requestBody: required: true content: @@ -3604,13 +3707,13 @@ paths: metadata: $ref: '#/components/schemas/Metadata' responses: - '200': + "200": description: Returns the updated Reader object if the update succeeded. content: application/json: schema: $ref: '#/components/schemas/Reader' - '403': + "403": description: The request isn't sufficiently authorized to modify the reader. content: application/problem+json: @@ -3621,7 +3724,7 @@ paths: title: Forbidden status: 403 detail: You do not have permission to perform this action. - '404': + "404": description: The requested Reader resource does not exist. content: application/problem+json: @@ -3632,26 +3735,38 @@ paths: 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 - - terminals.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 - - terminals.write + parameters: + - name: merchant_code + description: Short unique identifier for the merchant. + in: path + 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' /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout: post: - operationId: CreateReaderCheckout - summary: Create a Reader Checkout + callbacks: + ReaderCheckoutStatusChange: + '{$request.body#/return_url}': + post: + callbacks: {} + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ReaderCheckoutStatusChange' + required: true + 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. description: | Creates a Checkout for a Reader. @@ -3664,37 +3779,37 @@ paths: **Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher. + operationId: CreateReaderCheckout parameters: - - name: merchant_code + - description: Merchant Code + example: MC0X0ABC in: path - description: Merchant Code + name: merchant_code required: true schema: type: string - example: MC0X0ABC - - name: reader_id + - description: The unique identifier of the Reader + example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 in: path - description: The unique identifier of the Reader + name: reader_id required: true schema: type: string - example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 requestBody: - description: A checkout initial attributes - required: true content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutRequest' + description: A checkout initial attributes + required: true responses: '201': - description: The Checkout got successfully created for the given reader. content: application/json: schema: $ref: '#/components/schemas/CreateReaderCheckoutResponse' + description: The Checkout got successfully created for the given reader. '400': - description: Response when given params (or one of them) are invalid content: application/json: schema: @@ -3707,8 +3822,8 @@ paths: type: https://developer.sumup.com/problem/bad-request schema: $ref: '#/components/schemas/Problem' + description: Response when given params (or one of them) are invalid '401': - description: Unauthorized content: application/json: schema: @@ -3721,8 +3836,8 @@ paths: type: https://developer.sumup.com/problem/unauthorized schema: $ref: '#/components/schemas/Problem' + description: Unauthorized '404': - description: Response when given reader is not found content: application/json: schema: @@ -3735,8 +3850,8 @@ paths: type: https://developer.sumup.com/problem/not-found schema: $ref: '#/components/schemas/Problem' + description: Response when given reader is not found '422': - description: Response when given params (or one of them) are invalid content: application/json: schema: @@ -3749,26 +3864,12 @@ paths: 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: {} + description: Response when given params (or one of them) are invalid security: - apiKey: [] - oauth2: - readers.write + summary: Create a Reader Checkout tags: - Readers x-codegen: @@ -3779,8 +3880,7 @@ paths: - readers.write /v0.1/merchants/{merchant_code}/readers/{reader_id}/status: get: - operationId: GetReaderStatus - summary: Get a Reader Status + callbacks: {} description: | Provides the last known status for a Reader. @@ -3801,30 +3901,30 @@ paths: * `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. + operationId: GetReaderStatus parameters: - - name: merchant_code + - description: Merchant Code + example: MC0X0ABC in: path - description: Merchant Code + name: merchant_code required: true schema: type: string - example: MC0X0ABC - - name: reader_id + - description: The unique identifier of the Reader + example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 in: path - description: The unique identifier of the Reader + name: reader_id required: true schema: type: string - example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 responses: '200': - description: Response with the device status. content: application/json: schema: $ref: '#/components/schemas/StatusResponse' + description: Response with the device status. '400': - description: Response when given params (or one of them) are invalid content: application/json: schema: @@ -3837,8 +3937,8 @@ paths: type: https://developer.sumup.com/problem/bad-request schema: $ref: '#/components/schemas/Problem' + description: Response when given params (or one of them) are invalid '401': - description: Response when given merchant's token is invalid content: application/json: schema: @@ -3851,8 +3951,8 @@ paths: type: https://developer.sumup.com/problem/unauthorized schema: $ref: '#/components/schemas/Problem' + description: Response when given merchant's token is invalid '404': - description: Response when given reader is not found content: application/json: schema: @@ -3865,11 +3965,12 @@ paths: type: https://developer.sumup.com/problem/not-found schema: $ref: '#/components/schemas/Problem' - callbacks: {} + description: Response when given reader is not found security: - apiKey: [] - oauth2: - readers.read + summary: Get a Reader Status tags: - Readers x-codegen: @@ -3880,8 +3981,7 @@ paths: - readers.read /v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate: post: - operationId: CreateReaderTerminate - summary: Terminate a Reader Checkout + callbacks: {} description: | Terminate a Reader Checkout stops the current transaction on the target device. @@ -3897,33 +3997,33 @@ paths: **Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher. + operationId: CreateReaderTerminate parameters: - - name: merchant_code + - description: Merchant Code + example: MC0X0ABC in: path - description: Merchant Code + name: merchant_code required: true schema: type: string - example: MC0X0ABC - - name: reader_id + - description: The unique identifier of the Reader + example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 in: path - description: The unique identifier of the Reader + name: reader_id required: true schema: type: string - example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 requestBody: - description: A checkout initial attributes - required: false content: application/json: {} + description: A checkout initial attributes + required: false responses: '202': - description: The Terminate action was successfully dispatched for the given reader. content: application/json: {} + description: The Terminate action was successfully dispatched for the given reader. '400': - description: Response when given params (or one of them) are invalid content: application/json: schema: @@ -3936,334 +4036,200 @@ paths: 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 - /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout/{checkout_id}: - get: - operationId: GetReaderCheckout - summary: Get a Reader Checkout - description: | - Get a Checkout for a Reader. - 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 - - name: checkout_id - in: path - description: The unique identifier of the Checkout - required: true - schema: - type: string - example: 74ecff66-1655-43ed-8ce3-193f49fa602f - responses: - '200': - description: The Checkout got successfully retrieved for the given reader. - content: - application/json: - schema: - $ref: '#/components/schemas/GetReaderCheckoutResponse' '401': - description: Unauthorized content: application/json: schema: - $ref: '#/components/schemas/CreateReaderCheckoutError' + $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 or checkout 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_checkout - x-permissions: - - readers_checkout_view - x-scopes: - - readers.read -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 + title: Unauthorized + type: https://developer.sumup.com/problem/unauthorized + schema: + $ref: '#/components/schemas/Problem' + description: Unauthorized + '404': + 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' + description: Response when given reader is not found + '422': + 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' + description: Response when given params (or one of them) are invalid + security: + - apiKey: [] + - oauth2: + - readers.write + summary: Terminate a Reader Checkout + tags: + - Readers + x-codegen: + method_name: terminate_checkout + x-permissions: + - readers_checkout_create + x-scopes: + - readers.write + /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout/{checkout_id}: + get: + callbacks: {} + description: | + Get a Checkout for a Reader. + operationId: GetReaderCheckout + parameters: + - description: Merchant Code + example: MC0X0ABC + in: path + name: merchant_code + required: true + schema: + type: string + - description: The unique identifier of the Reader + example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 + in: path + name: reader_id + required: true + schema: + type: string + - description: The unique identifier of the Checkout + example: 74ecff66-1655-43ed-8ce3-193f49fa602f + in: path + name: checkout_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetReaderCheckoutResponse' + description: The Checkout got successfully retrieved for the given reader. + '401': + 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' + description: Unauthorized + '404': + 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' + description: Response when given reader or checkout is not found + security: + - apiKey: [] + - oauth2: + - readers.read + summary: Get a Reader Checkout + tags: + - Readers + x-codegen: + method_name: get_checkout + x-permissions: + - readers_checkout_view + x-scopes: + - readers.read +components: schemas: AddressLegacy: - description: Profile's personal address information. + title: Address Legacy type: object + description: Profile's personal address information. properties: city: - description: City name from the address. type: string + description: City name from the address. 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 + description: |- + Two letter country code formatted according to [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: DE line_1: - description: First line of the address with details of the street name and number. type: string + description: |- + First line of the address with details of the street name and number. example: Sample street line_2: - description: Second line of the address with details of the building, unit, apartment, and floor numbers. type: string + description: |- + Second line of the address with details of the building, unit, apartment, and floor numbers. example: ap. 5 postal_code: - description: Postal code from the address. type: string + description: Postal code from the address. example: '10115' state: - description: State name or abbreviation from the address. type: string + description: State name or abbreviation from the address. example: Berlin - title: Address Legacy Card: - description: __Required when payment type is `card`.__ Details of the payment card. + title: Card type: object + description: __Required when payment type is `card`.__ Details of the payment card. properties: name: - description: Name of the cardholder as it appears on the payment card. type: string - example: FIRSTNAME LASTNAME + description: Name of the cardholder as it appears on the payment card. writeOnly: true + example: FIRSTNAME LASTNAME number: - description: Number of the payment card (without spaces). type: string - example: '1234567890123456' + description: Number of the payment card (without spaces). writeOnly: true + example: '1234567890123456' 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 + description: |- + Year from the expiration time of the payment card. Accepted formats are `YY` and `YYYY`. writeOnly: true + minLength: 2 + maxLength: 4 + example: '2023' expiry_month: - description: Month from the expiration time of the payment card. Accepted format is `MM`. type: string + description: |- + Month from the expiration time of the payment card. Accepted format is `MM`. + writeOnly: true enum: - '01' - '02' @@ -4277,21 +4243,22 @@ components: - '10' - '11' - '12' - writeOnly: true cvv: - description: Three or four-digit card verification value (security code) of the payment card. type: string - example: '123' + description: |- + Three or four-digit card verification value (security code) of the payment card. + writeOnly: true maxLength: 4 minLength: 3 - writeOnly: true + example: '123' zip_code: - description: Required five-digit ZIP code. Applicable only to merchant users in the USA. type: string - example: '12345' + description: |- + Required five-digit ZIP code. Applicable only to merchant users in the USA. + writeOnly: true maxLength: 5 minLength: 5 - writeOnly: true + example: '12345' type: $ref: '#/components/schemas/CardType' required: @@ -4301,157 +4268,164 @@ components: - expiry_year - cvv - type - title: Card CardResponse: - description: Details of the payment card. + title: Card Response type: object + description: Details of the payment card. properties: last_4_digits: - description: Last 4 digits of the payment card number. type: string - example: '3456' - maxLength: 4 - minLength: 4 + description: Last 4 digits of the payment card number. readOnly: true + minLength: 4 + maxLength: 4 + example: '3456' type: $ref: '#/components/schemas/CardType' - title: Card Response Device: + title: Device description: Details of the device used to create the transaction. type: object properties: name: - description: Device name. type: string + description: Device name. example: m0xx system_name: - description: Device OS. type: string + description: Device OS. example: Android model: - description: Device model. type: string + description: Device model. example: GT-I9300 system_version: - description: Device OS version. type: string + description: Device OS version. example: '4.3' uuid: - description: Device UUID. type: string + description: Device UUID. example: 3ae2a6b7-fb0d-3b50-adbf-cb7e2db30cd2 - title: Device ElvCardAccount: + title: ELV Card Account description: Details of the ELV card account associated with the transaction. type: object properties: sort_code: - description: ELV card sort code. type: string + description: ELV card sort code. example: '87096214' last_4_digits: - description: ELV card account number last 4 digits. type: string + description: ELV card account number last 4 digits. example: '5674' sequence_no: - description: ELV card sequence number. type: integer + description: ELV card sequence number. example: 1 iban: - description: ELV IBAN. type: string + description: ELV IBAN. 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. + title: Hosted Checkout type: object + description: |- + Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response. properties: enabled: - description: Whether the checkout should include a SumUp-hosted payment page. type: boolean + description: Whether the checkout should include a SumUp-hosted payment page. 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 + title: 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. 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 + 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. + example: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: - description: Amount to be charged to the payer, expressed in major units. type: number format: float + description: Amount to be charged to the payer, expressed in major units. example: 10.1 currency: $ref: '#/components/schemas/Currency' merchant_code: - description: Merchant account that receives the payment. type: string + description: Merchant account that receives the payment. 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 + 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. 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 + description: |- + Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout. example: http://example.com id: - description: Unique SumUp identifier of the checkout resource. type: string - example: 4e425463-3e1b-431d-83fa-1e51c2925e99 + description: Unique SumUp identifier of the checkout resource. readOnly: true + example: 4e425463-3e1b-431d-83fa-1e51c2925e99 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 + 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. enum: - PENDING - FAILED - PAID - EXPIRED + example: PENDING 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 + example: '2020-02-29T10:56:56+00:00' format: date-time - example: 2020-02-29T10:56:56+00:00 + 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. 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 + example: '2020-02-29T10:56:56+00:00' format: date-time - example: 2020-02-29T10:56:56+00:00 + 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. 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 + 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. 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 + description: |- + URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout. readOnly: true + example: https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676 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' + 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. example: - id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -4461,57 +4435,69 @@ components: entry_mode: CUSTOMER_ENTRY auth_code: '012345' uniqueItems: true - title: Checkout + items: + allOf: + - $ref: '#/components/schemas/TransactionBase' + - $ref: '#/components/schemas/TransactionCheckoutInfo' CheckoutCreateRequest: - description: Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here. + title: Checkout Create Request type: object + description: |- + Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here. 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 + description: |- + Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems. + example: f00a8f74-b05d-4605-bd73-2a901bae5802 amount: - description: Amount to be charged to the payer, expressed in major units. type: number format: float + description: Amount to be charged to the payer, expressed in major units. example: 10.1 currency: $ref: '#/components/schemas/Currency' merchant_code: - description: Merchant account that should receive the payment. type: string + description: Merchant account that should receive the payment. example: MH4H92C7 description: - description: Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout. type: string + description: |- + Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout. 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 + description: |- + Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout. 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 + description: |- + Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer. 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 + 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. 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 + example: '2020-02-29T10:56:56+00:00' format: date-time - example: 2020-02-29T10:56:56+00:00 + 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. 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 + 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. hosted_checkout: $ref: '#/components/schemas/HostedCheckout' required: @@ -4519,46 +4505,52 @@ components: - amount - currency - merchant_code - title: Checkout Create Request CheckoutUpdateRequest: - description: Request body for updating an existing checkout. Include only the fields that should be changed. + title: Checkout Update Request type: object + description: |- + Request body for updating an existing checkout. Include only the fields that should be changed. properties: amount: - description: Updated amount to be charged to the payer, expressed in major units. type: number format: float + description: Updated amount to be charged to the payer, expressed in major units. example: 12.5 currency: $ref: '#/components/schemas/Currency' description: - description: Updated short merchant-defined description shown in SumUp tools and reporting. type: string + description: |- + Updated short merchant-defined description shown in SumUp tools and reporting. example: Updated purchase checkout_reference: - description: Updated merchant-defined reference for the checkout. type: string - example: f00a8f74-b05d-4605-bd73-2a901bae5802 maxLength: 90 + description: |- + Updated merchant-defined reference for the checkout. + example: f00a8f74-b05d-4605-bd73-2a901bae5802 valid_until: - description: Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. type: string + example: '2020-02-29T10:56:56+00:00' format: date-time - example: 2020-02-29T10:56:56+00:00 + description: |- + Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. nullable: true customer_id: - description: Updated merchant-scoped customer identifier associated with the checkout. type: string + description: |- + Updated merchant-scoped customer identifier associated with the checkout. example: 831ff8d4cd5958ab5670 - title: Checkout Update 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. + title: Process Checkout type: object + 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. properties: payment_type: - description: Payment method used for this processing attempt. It determines which additional request fields are required. type: string - example: card + description: |- + Payment method used for this processing attempt. It determines which additional request fields are required. enum: - card - boleto @@ -4567,19 +4559,22 @@ components: - bancontact - google_pay - apple_pay + example: card installments: - description: Number of installments for deferred payments. Available only to merchant users in Brazil. type: integer - example: 1 - maximum: 12 + description: |- + Number of installments for deferred payments. Available only to merchant users in Brazil. minimum: 1 + maximum: 12 + example: 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 + description: |- + Raw `PaymentData` object received from Google Pay. Send the Google Pay response payload as-is. example: apiVersionMinor: 0 apiVersion: 2 @@ -4593,8 +4588,9 @@ components: 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 + description: |- + Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is. example: token: paymentData: @@ -4611,115 +4607,126 @@ components: 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 + description: |- + Saved-card token to use instead of raw card details when processing with a previously stored payment instrument. example: ba85dfee-c3cf-48a6-84f5-d7d761fbba50 customer_id: - description: Customer identifier associated with the saved payment instrument. Required when `token` is provided. type: string + description: |- + Customer identifier associated with the saved payment instrument. Required when `token` is provided. 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. + title: Checkout Success + 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 + description: |- + Transaction code of the successful transaction with which the payment for the checkout is completed. readOnly: true + example: TEENSK4W2K 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 + description: |- + Transaction ID of the successful transaction with which the payment for the checkout is completed. readOnly: true + example: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_name: - description: Name of the merchant type: string + description: Name of the merchant 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 + description: |- + URL where the payer is redirected after a redirect-based payment or SCA flow completes. payment_instrument: - description: Details of the saved payment instrument created or reused during checkout processing. type: object + description: |- + Details of the saved payment instrument created or reused during checkout processing. properties: token: - description: Token value type: string + description: Token value 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. + title: Checkout Accepted type: object + 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. properties: next_step: - description: Instructions for the next action the payer or client must take. type: object + description: Instructions for the next action the payer or client must take. 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 + description: URL to open or submit in order to continue processing. method: - description: HTTP method to use when following the next step. type: string example: POST + description: HTTP method to use when following the next step. redirect_url: - description: Merchant URL where the payer returns after the external flow finishes. type: string example: https://mysite.com/completed_purchase + description: |- + Merchant URL where the payer returns after the external flow finishes. 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 + 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. payload: - description: Parameters required to complete the next step. The exact keys depend on the payment provider and flow type. type: object + description: |- + Parameters required to complete the next step. The exact keys depend on the payment provider and flow type. + additionalProperties: + type: string example: - PaReq: eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw== + 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 + title: Customer + description: Saved customer details. + required: + - customer_id properties: customer_id: - description: Unique ID of the customer. type: string + description: Unique ID of the customer. example: 831ff8d4cd5958ab5670 personal_details: $ref: '#/components/schemas/PersonalDetails' - required: - - customer_id - title: Customer Error: - description: Error message structure. + title: Error type: object + description: Error message structure. properties: message: - description: Short description of the error. type: string + description: Short description of the error. example: Resource not found error_code: - description: Platform code for the error. type: string + description: Platform code for the error. example: NOT_FOUND - title: Error Problem: description: |- A RFC 9457 problem details object. @@ -4731,9 +4738,9 @@ components: description: A URI reference that identifies the problem type. type: string format: uri - example: https://developer.sumup.com/problem/not-found + example: 'https://developer.sumup.com/problem/not-found' title: - description: A short, human-readable summary of the problem type. + description: 'A short, human-readable summary of the problem type.' type: string example: Requested resource couldn't be found. status: @@ -4753,51 +4760,56 @@ components: - type title: Problem ErrorExtended: + title: Error Extended 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 + 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. ErrorForbidden: - description: Error message for forbidden requests. + title: Error Forbidden type: object + description: Error message for forbidden requests. properties: error_message: - description: Short description of the error. type: string + description: Short description of the error. example: request_not_allowed error_code: - description: Platform code for the error. type: string + description: Platform code for the error. example: FORBIDDEN status_code: - description: HTTP status code for the error. type: string + description: HTTP status code for the error. example: '403' - title: Error Forbidden DetailsError: - description: Error message structure. + title: Details Error type: object + description: Error message structure. properties: title: - description: Short title of the error. type: string + description: Short title of the error. example: Bad Request details: - description: Details of the error. type: string + description: Details of the error. example: One or more of the parameters are invalid. status: - description: The status code. type: number + description: The status code. example: 400 failed_constraints: - description: List of violated validation constraints. type: array + description: List of violated validation constraints. + example: + - message: Currency must also be specified when filtering by amount + reference: currency items: type: object properties: @@ -4805,11 +4817,8 @@ components: type: string reference: type: string - example: - - message: Currency must also be specified when filtering by amount - reference: currency - title: Details Error Event: + title: Event description: High-level transaction event details. type: object properties: @@ -4822,36 +4831,36 @@ components: status: $ref: '#/components/schemas/TransactionEventStatus' amount: - description: Amount of the event. type: number format: float + description: Amount of the event. timestamp: - description: Date and time of the transaction event. type: string format: date-time + description: Date and time of the transaction event. fee_amount: - description: Amount of the fee related to the event. type: number format: float + description: Amount of the fee related to the event. installment_number: - description: Consecutive number of the installment. type: integer + description: Consecutive number of the installment. deducted_amount: - description: Amount deducted for the event. type: number format: float + description: Amount deducted for the event. deducted_fee_amount: - description: Amount of the fee deducted for the event. type: number format: float - title: Event + description: Amount of the fee deducted for the event. FinancialPayouts: + title: Financial Payouts description: Ordered list of payout and payout-deduction records. type: array items: $ref: '#/components/schemas/FinancialPayout' - title: Financial Payouts FinancialPayout: + title: Financial Payout description: |- A single payout-related record. @@ -4859,190 +4868,194 @@ components: - 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 + required: + - id + - type + - amount + - date + - currency + - fee + - status + - reference + - transaction_code properties: id: - description: Unique identifier of the payout-related record. type: integer + description: Unique identifier of the payout-related record. example: 123456789 type: - description: High-level payout record category. type: string - example: PAYOUT + description: High-level payout record category. enum: - PAYOUT - CHARGE_BACK_DEDUCTION - REFUND_DEDUCTION - DD_RETURN_DEDUCTION - BALANCE_DEDUCTION + example: PAYOUT amount: - description: Amount of the payout or deduction in major units. type: number format: float + description: Amount of the payout or deduction in major units. example: 132.45 date: - description: Payout date associated with the record, in `YYYY-MM-DD` format. type: string format: date - example: 2024-02-29 + description: Payout date associated with the record, in `YYYY-MM-DD` format. + example: '2024-02-29' currency: - description: Three-letter ISO 4217 currency code of the payout. type: string + description: Three-letter ISO 4217 currency code of the payout. example: EUR fee: - description: Fee amount associated with the payout record, in major units. type: number format: float + description: Fee amount associated with the payout record, in major units. example: 3.12 status: - description: Merchant-facing outcome of the payout record. type: string - example: SUCCESSFUL + description: Merchant-facing outcome of the payout record. enum: - SUCCESSFUL - FAILED + example: SUCCESSFUL reference: - description: Processor or payout reference associated with the record. type: string + description: Processor or payout reference associated with the record. example: payout-2024-02-29 transaction_code: - description: Transaction code of the original sale associated with the payout or deduction. type: string + description: Transaction code of the original sale associated with the payout or deduction. 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. + title: Link type: object + description: Details of a link to a related resource. properties: rel: - description: Specifies the relation to the current resource. type: string + description: Specifies the relation to the current resource. href: - description: URL for accessing the related resource. type: string format: uri + description: URL for accessing the related resource. type: - description: Specifies the media type of the related resource. type: string + description: Specifies the media type of the related resource. min_amount: - description: Minimum allowed amount for the refund. type: number format: float + description: Minimum allowed amount for the refund. max_amount: - description: Maximum allowed amount for the refund. type: number format: float - title: Link + description: Maximum allowed amount for the refund. TransactionsHistoryLink: + title: Transactions History Link description: Hypermedia link used for transaction history pagination. type: object properties: rel: - description: Relation. type: string + description: Relation. example: next href: - description: Location. type: string + description: Location. 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. + title: Mandate Payload type: object + description: |- + Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments. properties: type: - description: Type of mandate to create for the saved payment instrument. type: string - example: recurrent + description: Type of mandate to create for the saved payment instrument. enum: - recurrent + example: recurrent user_agent: - description: Browser or client user agent observed when consent was collected. type: string + description: Browser or client user agent observed when consent was collected. 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 + description: IP address of the payer when the mandate was accepted. 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 + 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 MandateResponse: - description: Details of the mandate linked to the saved payment instrument. + title: Mandate Response type: object + description: Details of the mandate linked to the saved payment instrument. properties: type: - description: Type of mandate stored for the checkout or payment instrument. type: string + description: Type of mandate stored for the checkout or payment instrument. status: - description: Current lifecycle status of the mandate. type: string - example: active + description: Current lifecycle status of the mandate. enum: - active - inactive + example: active merchant_code: - description: Merchant account for which the mandate is valid. type: string + description: Merchant account for which the mandate is valid. example: MH4H92C7 example: type: recurrent status: active merchant_code: MH4H92C7 - title: Mandate Response PaymentInstrumentResponse: - description: Payment Instrument Response + title: Payment Instrument Response type: object + description: Payment Instrument Response properties: token: - description: Unique token identifying the saved payment card for a customer. type: string + description: Unique token identifying the saved payment card for a customer. 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 + 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. readOnly: true + default: true type: - description: Type of the payment instrument. type: string + description: Type of the payment instrument. enum: - card card: - description: Details of the payment card. type: object + description: Details of the payment card. properties: last_4_digits: - description: Last 4 digits of the payment card number. type: string - example: '3456' - maxLength: 4 - minLength: 4 + description: Last 4 digits of the payment card number. readOnly: true + minLength: 4 + maxLength: 4 + example: '3456' 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 + description: |- + Creation date of payment instrument. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code. format: date-time example: token: bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3 @@ -5055,102 +5068,102 @@ components: card: last_4_digits: '0001' type: VISA - created_at: 2021-03-30T10:06:07.000+00:00 - title: Payment Instrument Response + created_at: '2021-03-30T10:06:07.000+00:00' PersonalDetails: - description: Personal details for the customer. + title: Personal Details type: object + description: Personal details for the customer. properties: first_name: - description: First name of the customer. type: string + description: First name of the customer. example: John last_name: - description: Last name of the customer. type: string + description: Last name of the customer. example: Doe email: - description: Email address of the customer. type: string + description: Email address of the customer. example: user@example.com phone: - description: Phone number of the customer. type: string + description: Phone number of the customer. example: '+491635559723' birth_date: - description: Date of birth of the customer. type: string + description: Date of birth of the customer. format: date - example: 1993-12-31 + example: '1993-12-31' tax_id: - description: An identification number user for tax purposes (e.g. CPF) type: string - example: 423.378.593-47 + description: An identification number user for tax purposes (e.g. CPF) maxLength: 255 + example: '423.378.593-47' address: $ref: '#/components/schemas/AddressLegacy' - title: Personal Details Product: - description: Purchase product. + title: Product type: object + description: Purchase product. properties: name: - description: Product name. type: string + description: Product name. example: Purchase reader for merchant with code ME3FCAVF price_label: - description: Product description. type: string + description: Product description. price: - description: Product price. type: number format: decimal - example: 100 + description: Product price. + example: 100.0 vat_rate: - description: VAT percentage. type: number format: decimal + description: VAT percentage. single_vat_amount: - description: VAT amount for a single product. type: number format: decimal + description: VAT amount for a single product. price_with_vat: - description: Product price incl. VAT. type: number format: decimal + description: Product price incl. VAT. vat_amount: - description: VAT amount. type: number format: decimal + description: VAT amount. quantity: - description: Product quantity. type: integer + description: Product quantity. example: 1 total_price: - description: Quantity x product price. type: number format: decimal - example: 100 + description: Quantity x product price. + example: 100.0 total_with_vat: - description: Total price incl. VAT. type: number format: decimal - title: Product + description: Total price incl. VAT. Receipt: - description: Receipt details for a transaction. type: object + title: Receipt + description: Receipt details for a transaction. 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 + description: EMV-specific metadata returned for card-present payments. example: {} acquirer_data: - description: Acquirer-specific metadata related to the card authorization. type: object + description: Acquirer-specific metadata related to the card authorization. example: authorization_code: '053201' return_code: '00' @@ -5163,8 +5176,8 @@ components: type: string local_time: type: string - title: Receipt ReceiptEvent: + title: Receipt Event description: Transaction event details as rendered on the receipt. type: object properties: @@ -5177,46 +5190,46 @@ components: status: $ref: '#/components/schemas/TransactionEventStatus' amount: - description: Amount of the event. type: string format: double + description: Amount of the event. timestamp: - description: Date and time of the transaction event. type: string format: date-time + description: Date and time of the transaction event. receipt_no: - description: Receipt number associated with the event. type: string - title: Receipt Event + description: Receipt number associated with the event. ReceiptCard: + title: Receipt Card description: Payment card details displayed on the receipt. type: object properties: last_4_digits: - description: Card last 4 digits. type: string + description: Card last 4 digits. type: - description: Card Scheme. type: string - title: Receipt Card + description: Card Scheme. ReceiptReader: + title: Receipt Reader description: Card reader details displayed on the receipt. type: object properties: code: - description: Reader serial number. type: string + description: Reader serial number. type: - description: Reader type. type: string - title: Receipt Reader + description: Reader type. ReceiptMerchantData: - description: Receipt merchant data + title: Receipt Merchant Data type: object + description: Receipt merchant data properties: merchant_profile: - description: Merchant profile details displayed on the receipt. type: object + description: Merchant profile details displayed on the receipt. properties: merchant_code: type: string @@ -5255,164 +5268,164 @@ components: landline: type: string locale: - description: Locale used for rendering localized receipt fields. type: string - title: Receipt Merchant Data + description: Locale used for rendering localized receipt fields. ReceiptTransaction: - description: Transaction information. + title: Receipt Transaction type: object + description: Transaction information. + 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 properties: transaction_code: - description: Transaction code. type: string + description: Transaction code. transaction_id: $ref: '#/components/schemas/TransactionID' merchant_code: - description: Merchant code. type: string + description: Merchant code. amount: - description: Transaction amount. type: string + description: Transaction amount. vat_amount: - description: Transaction VAT amount. type: string + description: Transaction VAT amount. tip_amount: - description: Tip amount (included in transaction amount). type: string + description: Tip amount (included in transaction amount). currency: - description: Transaction currency. type: string + description: Transaction currency. timestamp: - description: Time created at. type: string format: date-time + description: Time created at. status: - description: Transaction processing status. type: string + description: Transaction processing status. payment_type: - description: Transaction type. type: string + description: Transaction type. entry_mode: - description: Transaction entry mode. type: string + description: Transaction entry mode. verification_method: - description: Cardholder verification method. type: string + description: Cardholder verification method. card_reader: $ref: '#/components/schemas/ReceiptReader' card: $ref: '#/components/schemas/ReceiptCard' installments_count: - description: Number of installments. type: integer + description: Number of installments. process_as: - description: Debit/Credit. type: string - example: CREDIT + description: Debit/Credit. enum: - CREDIT - DEBIT + example: CREDIT products: - description: Products type: array + description: Products items: type: object properties: name: - description: Product name type: string + description: Product name example: Coffee description: - description: Product description type: string + description: Product description price: - description: Product price type: string format: double + description: Product price example: '150.0' vat_rate: - description: VAT rate type: string format: double + description: VAT rate example: '0.0' single_vat_amount: - description: VAT amount for a single product type: string format: double + description: VAT amount for a single product example: '0.0' price_with_vat: - description: Product price including VAT type: string format: double + description: Product price including VAT example: '150.0' vat_amount: - description: VAT amount type: string format: double + description: VAT amount example: '0.0' quantity: - description: Product quantity type: integer format: int64 + description: Product quantity example: 1 total_price: - description: Quantity x product price type: string format: double + description: Quantity x product price example: '150.0' total_with_vat: - description: Total price including VAT type: string format: double + description: Total price including VAT example: '150.0' vat_rates: - description: Vat rates. type: array + description: Vat rates. items: type: object properties: gross: - description: Gross type: number format: float + description: Gross net: - description: Net type: number format: float + description: Net rate: - description: Rate type: number format: float + description: Rate vat: - description: Vat type: number format: float + description: Vat events: - description: Events type: array + description: Events 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 + description: Receipt number TransactionEvent: - description: Detailed information about a transaction event. + title: Transaction Event type: object + description: Detailed information about a transaction event. properties: id: $ref: '#/components/schemas/TransactionEventID' @@ -5421,110 +5434,118 @@ components: status: $ref: '#/components/schemas/TransactionEventStatus' amount: - description: Amount of the event. type: number format: decimal + description: Amount of the event. example: 58.8 due_date: - description: Date when the transaction event is due to occur. type: string format: date - example: 2020-05-25 + description: Date when the transaction event is due to occur. + example: '2020-05-25' date: - description: Date when the transaction event occurred. type: string format: date - example: 2020-05-25 + description: Date when the transaction event occurred. + 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 + description: |- + Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`. 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 + description: Date and time of the transaction event. + example: '2020-05-25T10:49:42.784Z' TransactionBase: - description: Details of the transaction. + title: Transaction Base type: object + description: Details of the transaction. properties: id: - description: Unique ID of the transaction. type: string + description: Unique ID of the transaction. example: 6b425463-3e1b-431d-83fa-1e51c2925e99 transaction_code: - description: Transaction code returned by the acquirer/processing entity after processing the transaction. type: string + description: |- + Transaction code returned by the acquirer/processing entity after processing the transaction. example: TEENSK4W2K amount: - description: Total amount of the transaction. type: number format: float + description: Total amount of the transaction. 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 + example: '2020-02-29T10:56:56.876Z' format: date-time - example: 2020-02-29T10:56:56.876Z + description: |- + Date and time of the creation of the transaction. Response format expressed according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) code. status: $ref: '#/components/schemas/TransactionStatus' payment_type: $ref: '#/components/schemas/PaymentType' installments_count: - description: Current number of the installment for deferred payments. type: integer + description: Current number of the installment for deferred payments. minimum: 1 - title: Transaction Base TransactionCheckoutInfo: + title: Transaction Checkout Info 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 + description: Unique code of the registered merchant to whom the payment is made. example: MH4H92C7 vat_amount: - description: Amount of the applicable VAT (out of the total transaction amount). type: number format: float + description: Amount of the applicable VAT (out of the total transaction amount). example: 6 tip_amount: - description: Amount of the tip (out of the total transaction amount). type: number format: float + description: Amount of the tip (out of the total transaction amount). 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 + description: |- + Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. example: '053201' - title: Transaction Checkout Info TransactionMixinHistory: + title: Transaction Mixin History 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 + description: |- + Short description of the payment. The value is taken from the `description` property of the related checkout resource. payouts_total: - description: Total number of payouts to the registered user specified in the `user` property. type: integer + description: |- + Total number of payouts to the registered user specified in the `user` property. payouts_received: - description: Number of payouts that are made to the registered user specified in the `user` property. type: integer + description: |- + Number of payouts that are made to the registered user specified in the `user` property. payout_plan: - description: Payout plan of the registered user at the time when the transaction was made. type: string + description: |- + Payout plan of the registered user at the time when the transaction was made. enum: - SINGLE_PAYMENT - TRUE_INSTALLMENT - ACCELERATED_INSTALLMENT - title: Transaction Mixin History TransactionHistory: + title: Transaction History description: Transaction entry returned in history listing responses. allOf: - $ref: '#/components/schemas/TransactionBase' @@ -5534,15 +5555,17 @@ components: transaction_id: $ref: '#/components/schemas/TransactionID' client_transaction_id: - description: Client-specific ID of the transaction. type: string + description: Client-specific ID of the transaction. user: - description: Email address of the registered user (merchant) to whom the payment is made. type: string format: email + description: |- + Email address of the registered user (merchant) to whom the payment is made. type: - description: Type of the transaction for the registered user specified in the `user` property. type: string + description: |- + Type of the transaction for the registered user specified in the `user` property. enum: - PAYMENT - REFUND @@ -5550,26 +5573,26 @@ components: card_type: $ref: '#/components/schemas/CardType' payout_date: - description: Payout date (if paid out at once). type: string format: date - example: 2019-08-28 + description: Payout date (if paid out at once). + example: '2019-08-28' payout_type: - description: Payout type. type: string - example: BANK_ACCOUNT + description: Payout type. enum: - BANK_ACCOUNT - PREPAID_CARD + example: BANK_ACCOUNT refunded_amount: - description: Total refunded amount. type: number format: decimal + description: Total refunded amount. example: 0 - title: Transaction History PaymentType: - description: Payment type used for the transaction. + title: Payment Type type: string + description: Payment type used for the transaction. enum: - CASH - POS @@ -5582,10 +5605,10 @@ components: - DIRECT_DEBIT - APM - UNKNOWN - title: Payment Type EntryMode: - description: Entry mode of the payment details. + title: Entry Mode type: string + description: Entry mode of the payment details. enum: - BOLETO - SOFORT @@ -5614,10 +5637,11 @@ components: - MOTO - CONTACTLESS_MAGSTRIPE - N/A - title: Entry Mode CardType: - description: Issuing card network of the payment card used for the transaction. + title: Card Type type: string + description: |- + Issuing card network of the payment card used for the transaction. enum: - ALELO - AMEX @@ -5643,8 +5667,8 @@ components: - VPAY - VR - UNKNOWN - title: Card Type TransactionFull: + title: Transaction Full description: Full transaction resource with checkout, payout, and event details. allOf: - $ref: '#/components/schemas/TransactionBase' @@ -5653,22 +5677,23 @@ components: - type: object properties: foreign_transaction_id: - description: External/foreign transaction id (passed by clients). type: string + description: External/foreign transaction id (passed by clients). example: J13253253x1 client_transaction_id: - description: Client transaction id. type: string + description: Client transaction id. 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 + description: |- + Email address of the registered user (merchant) to whom the payment is made. fee_amount: - description: Transaction SumUp total fee amount. type: number format: decimal - example: 8 + description: Transaction SumUp total fee amount. + example: 8.0 lat: $ref: '#/components/schemas/Lat' lon: @@ -5676,15 +5701,15 @@ components: horizontal_accuracy: $ref: '#/components/schemas/HorizontalAccuracy' merchant_id: - description: SumUp merchant internal Id. type: integer format: int64 + description: SumUp merchant internal Id. example: 136902 device_info: $ref: '#/components/schemas/Device' simple_payment_type: - description: Simple name of the payment type. type: string + description: Simple name of the payment type. enum: - CASH - CC_SIGNATURE @@ -5701,8 +5726,8 @@ components: - BITCOIN - CARD verification_method: - description: Verification method used for the transaction. type: string + description: Verification method used for the transaction. enum: - none - signature @@ -5715,64 +5740,66 @@ components: elv_account: $ref: '#/components/schemas/ElvCardAccount' local_time: - description: Local date and time of the creation of the transaction. type: string format: date-time + description: Local date and time of the creation of the transaction. payout_date: - description: The date of the payout. type: string format: date - example: 2019-08-28 + description: The date of the payout. + example: '2019-08-28' payout_type: - description: Payout type for the transaction. type: string + description: Payout type for the transaction. enum: - BANK_ACCOUNT - PREPAID_CARD process_as: - description: Debit/Credit. type: string - example: CREDIT + description: Debit/Credit. enum: - CREDIT - DEBIT + example: CREDIT products: - description: List of products from the merchant's catalogue for which the transaction serves as a payment. type: array + description: |- + List of products from the merchant's catalogue for which the transaction serves as a payment. items: $ref: '#/components/schemas/Product' vat_rates: - description: List of VAT rates applicable to the transaction. type: array + description: List of VAT rates applicable to the transaction. items: type: object properties: rate: - description: VAT rate. type: number format: decimal + description: VAT rate. example: 0.045 net: - description: NET amount of products having this VAT rate applied. type: number format: decimal + description: NET amount of products having this VAT rate applied. example: 1.36 vat: - description: VAT amount of this rate applied. type: number format: decimal + description: VAT amount of this rate applied. example: 0.06 gross: - description: Gross amount of products having this VAT rate applied. type: number format: decimal + description: Gross amount of products having this VAT rate applied. example: 1.42 transaction_events: - description: Detailed list of events related to the transaction. type: array + description: Detailed list of events related to the transaction. items: $ref: '#/components/schemas/TransactionEvent' simple_status: + type: string description: |- High-level status of the transaction from the merchant's perspective. @@ -5786,7 +5813,6 @@ components: - `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 @@ -5799,18 +5825,19 @@ components: - NON_COLLECTION - PENDING links: - description: List of hyperlinks for accessing related resources. type: array + description: List of hyperlinks for accessing related resources. items: $ref: '#/components/schemas/Link' events: - description: Compact list of events related to the transaction. type: array + description: Compact list of events related to the transaction. items: $ref: '#/components/schemas/Event' location: - description: Details of the payment location as received from the payment terminal. type: object + description: |- + Details of the payment location as received from the payment terminal. properties: lat: $ref: '#/components/schemas/Lat' @@ -5819,13 +5846,13 @@ components: horizontal_accuracy: $ref: '#/components/schemas/HorizontalAccuracy' tax_enabled: - description: Indicates whether tax deduction is enabled for the transaction. type: boolean - title: Transaction Full + description: Indicates whether tax deduction is enabled for the transaction. 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. + title: Currency type: string - example: EUR + 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. enum: - BGN - BRL @@ -5843,8 +5870,10 @@ components: - RON - SEK - USD - title: Currency + example: EUR TransactionStatus: + title: Transaction Status + type: string description: |- Current status of the transaction. @@ -5853,24 +5882,24 @@ components: - `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 TransactionEventType: - description: Type of the transaction event. + title: Transaction Event Type type: string + description: Type of the transaction event. enum: - PAYOUT - CHARGE_BACK - REFUND - PAYOUT_DEDUCTION - title: Transaction Event Type TransactionEventStatus: + title: Transaction Event Status + type: string description: |- Status of the transaction event. @@ -5883,7 +5912,6 @@ components: - `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 @@ -5892,104 +5920,108 @@ components: - REFUNDED - SCHEDULED - SUCCESSFUL - title: Transaction Event Status TransactionEventID: - description: Unique ID of the transaction event. + title: Transaction Event ID type: integer format: int64 - title: Transaction Event ID + description: Unique ID of the transaction event. HorizontalAccuracy: - description: Indication of the precision of the geographical position received from the payment terminal. + title: Horizontal Accuracy type: number format: float - title: Horizontal Accuracy + description: |- + Indication of the precision of the geographical position received from the payment terminal. Lat: - description: Latitude value from the coordinates of the payment location (as received from the payment terminal reader). + title: Latitude type: number format: float - maximum: 90 + description: |- + Latitude value from the coordinates of the payment location (as received from the payment terminal reader). minimum: 0 - title: Latitude + maximum: 90 Lon: - description: Longitude value from the coordinates of the payment location (as received from the payment terminal reader). + title: Longitude type: number format: float - maximum: 180 + description: |- + Longitude value from the coordinates of the payment location (as received from the payment terminal reader). minimum: 0 - title: Longitude + maximum: 180 TransactionID: - description: Unique ID of the transaction. - type: string title: Transaction ID + type: string + description: Unique ID of the transaction. Affiliate: - type: object properties: app_id: - type: string example: com.example.app - key: type: string + key: example: 123e4567-e89b-12d3-a456-426614174000 + type: string required: - app_id - key - Amount: type: object + Amount: properties: currency: description: Currency ISO 4217 code - type: string example: MXN + type: string value: description: Amount in minor units (e.g. cents). - type: integer example: 1000 + type: integer required: - currency - value + type: object ReaderID: - description: Unique identifier of the reader that the payment is initiated on. type: string + description: >- + Unique identifier of the reader that the payment is initiated on. example: rdr_3MSAFM23CK82VSTT4BN6RWSQ65 - maxLength: 30 minLength: 30 + maxLength: 30 ReaderPaymentRequestParams: - type: object properties: affiliate: $ref: '#/components/schemas/Affiliate' client_transaction_id: description: Caller-supplied correlation identifier, used as the idempotency key. - type: string example: 19e12390-72cf-4f9f-80b5-b0c8a67fa43f + type: string tip_amount: description: Optional tip amount in minor units, added on top of total_amount. - type: integer example: 100 + type: integer total_amount: $ref: '#/components/schemas/Amount' required: - total_amount - client_transaction_id - ReaderPaymentResponse: type: object + ReaderPaymentResponse: properties: data: $ref: '#/components/schemas/ReaderPaymentResponseData' - ReaderPaymentResponseData: type: object + ReaderPaymentResponseData: properties: client_transaction_id: description: Caller-supplied correlation identifier that was provided in the request. - type: string example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + type: string transaction_code: description: Transaction code returned by the acquirer/processing entity after processing the transaction. - type: string example: TEENSK4W2K + type: string + type: object MembershipStatus: - description: The status of the membership. type: string + description: >- + The status of the membership. enum: - accepted - pending @@ -5997,37 +6029,55 @@ components: - disabled - unknown ResourceType: - description: |- + type: string + 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. + title: Membership type: object + description: >- + A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles. + required: + - id + - resource_id + - type + - roles + - permissions + - created_at + - updated_at + - status + - resource properties: id: - description: ID of the membership. type: string + description: ID of the membership. example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP resource_id: - description: ID of the resource the membership is in. type: string + description: ID of the resource the membership is in. example: M2DDT39A type: $ref: '#/components/schemas/ResourceType' roles: - description: User's roles. type: array - items: - type: string + description: User's roles. example: - role_admin + items: + type: string permissions: - description: User's permissions. type: array + description: User's permissions. + 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. items: type: string example: @@ -6039,16 +6089,14 @@ components: - 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 + description: The timestamp of when the membership was created. format: date-time example: 2023-01-20T15:16:17Z updated_at: - description: The timestamp of when the membership was last updated. type: string + description: The timestamp of when the membership was last updated. format: date-time example: 2023-01-20T15:16:17Z invite: @@ -6061,74 +6109,76 @@ components: $ref: '#/components/schemas/Attributes' resource: $ref: '#/components/schemas/MembershipResource' + MembershipResource: + title: Resource + type: object + description: >- + Information about the resource the membership is in. required: - id - - resource_id - type - - roles - - permissions + - name - 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 + description: ID of the resource the membership is in. example: M2DDT39A type: $ref: '#/components/schemas/ResourceType' name: - description: Display name of the resource. type: string + description: Display name of the resource. example: Acme Corp logo: - description: Logo fo the resource. type: string + description: Logo fo the resource. format: uri - example: https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png maxLength: 256 + example: https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png created_at: - description: The timestamp of when the membership resource was created. type: string + description: The timestamp of when the membership resource was created. format: date-time example: 2023-01-20T15:16:17Z updated_at: - description: The timestamp of when the membership resource was last updated. type: string + description: The timestamp of when the membership resource was last updated. format: date-time example: 2023-01-20T15:16:17Z attributes: $ref: '#/components/schemas/Attributes' + Member: + title: Member + type: object + description: >- + A member is user within specific resource identified by resource id, resource type, and associated roles. required: - id - - type - - name + - roles + - permissions - 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 + - status properties: id: - description: ID of the member. type: string + description: ID of the member. example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP roles: - description: User's roles. type: array - items: - type: string + description: User's roles. example: - role_admin + items: + type: string permissions: - description: User's permissions. type: array + description: User's permissions. + 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. items: type: string example: @@ -6140,16 +6190,14 @@ components: - 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 + description: The timestamp of when the member was created. format: date-time example: 2023-01-20T15:16:17Z updated_at: - description: The timestamp of when the member was last updated. type: string + description: The timestamp of when the member was last updated. format: date-time example: 2023-01-20T15:16:17Z user: @@ -6185,170 +6233,181 @@ components: 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. + title: Invite type: object + description: >- + Pending invitation for membership. + required: + - email + - expires_at properties: email: - description: Email address of the invited user. type: string + description: Email address of the invited user. 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 + description: Information about the user associated with the membership. + required: + - id + - type + - email + - mfa_on_login_enabled + - virtual_user + - service_account_user properties: id: - description: Identifier for the End-User (also called Subject). type: string + description: Identifier for the End-User (also called Subject). example: 44ca0f5b-813b-46e1-aee7-e6242010662e type: $ref: '#/components/schemas/UserType' 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 + 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. mfa_on_login_enabled: - description: True if the user has enabled MFA on login. type: boolean example: true + description: >- + True if the user has enabled MFA on login. virtual_user: - description: True if the user is a virtual user (operator). type: boolean - example: false deprecated: true x-deprecation-notice: Rely on `type` instead. + example: false + description: >- + True if the user is a virtual user (operator). service_account_user: - description: True if the user is a service account. type: boolean - example: false deprecated: true x-deprecation-notice: Rely on `type` instead. + example: false + description: >- + True if the user is a service account. disabled_at: - description: 'Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`).' type: string format: date-time + description: >- + Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`). nickname: - description: User's nickname. Used for display purposes only. type: string - example: Test User + example: "Test User" + description: >- + User's nickname. Used for display purposes only. 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 + 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. classic: $ref: '#/components/schemas/MembershipUserClassic' - required: - - id - - type - - email - - mfa_on_login_enabled - - virtual_user - - service_account_user MembershipUserClassic: - description: Classic identifiers of the user. type: object + description: Classic identifiers of the user. + deprecated: true + required: + - user_id properties: user_id: type: integer - maximum: 2147483647 minimum: 0 - deprecated: true - required: - - user_id + maximum: 2147483647 Role: - description: A custom role that can be used to assign set of permissions to members. + title: Role type: object + description: A custom role that can be used to assign set of permissions to members. + required: + - id + - name + - permissions + - is_predefined + - created_at + - updated_at properties: id: - description: Unique identifier of the role. type: string + description: Unique identifier of the role. example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP name: - description: User-defined name of the role. type: string example: Senior Shop Manager II + description: >- + User-defined name of the role. description: - description: User-defined description of the role. type: string - example: Manges the shop and the employees. + example: "Manges the shop and the employees." + description: >- + User-defined description of the role. permissions: - description: List of permission granted by this role. type: array + description: List of permission granted by this role. + maxItems: 100 items: type: string example: [] - maxItems: 100 is_predefined: - description: True if the role is provided by SumUp. type: boolean example: true + description: True if the role is provided by SumUp. metadata: $ref: '#/components/schemas/Metadata' created_at: - description: The timestamp of when the role was created. type: string + description: The timestamp of when the role was created. format: date-time example: 2023-01-20T15:16:17Z updated_at: - description: The timestamp of when the role was last updated. type: string + description: The timestamp of when the role was last updated. format: date-time example: 2023-01-20T15:16:17Z - required: - - id - - name - - permissions - - is_predefined - - created_at - - updated_at - title: Role Metadata: - description: Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object. + 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 + maxProperties: 64 example: {} additionalProperties: true - maxProperties: 64 Attributes: - description: | + description: > Object attributes that are modifiable only by SumUp applications. + type: object example: {} additionalProperties: true UserType: - description: Type of the user account. type: string - example: user + description: Type of the user account. enum: - user - managed_user - service_account - system_account + example: user Address: - description: |- + externalDocs: + description: Address documentation + url: https://developer.sumup.com/tools/glossary/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 + required: + - country properties: street_address: type: array + maxItems: 2 items: type: string description: The first line of the address. @@ -6356,159 +6415,173 @@ components: example: - Paul-Linke-Ufer 39-40 - 2. Hinterhof - maxItems: 2 post_code: - description: | - The postal code (aka. zip code) of the address. type: string - example: '10999' + description: > + The postal code (aka. zip code) of the address. + maxLength: 10 + example: "10999" country: $ref: '#/components/schemas/CountryCode' city: - description: | - The city of the address. type: string - example: Berlin + description: > + The city of the address. + maxLength: 60 + example: Berlin province: - description: | - The province where the address is located. This may not be relevant in some countries. type: string - example: Berlin + description: > + The province where the address is located. This may not be relevant in some countries. + maxLength: 60 + example: Berlin region: - description: | - The region where the address is located. This may not be relevant in some countries. type: string - example: Baden Wuerttemberg + description: > + The region where the address is located. This may not be relevant in some countries. + maxLength: 60 + example: Baden Wuerttemberg county: - description: | - A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc. type: string - example: Dublin County + 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. + maxLength: 60 + example: Dublin County autonomous_community: - description: | - In Spain, an autonomous community is the first sub-national level of political and administrative division. type: string - example: Catalonia + description: > + In Spain, an autonomous community is the first sub-national level of political and administrative division. + maxLength: 60 + example: Catalonia 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 + 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. + maxLength: 60 + example: London 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 + 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. + maxLength: 60 + example: California neighborhood: - description: | - Locality level of the address. Used in countries such as Brazil or Chile. type: string - example: Copacabana + description: > + Locality level of the address. Used in countries such as Brazil or Chile. + maxLength: 60 + example: Copacabana 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 + 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. + maxLength: 60 + example: Providencia 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 + description: > + A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia. + maxLength: 60 + example: Antioquia municipality: - description: | - A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia. type: string - example: Medellín + 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. + maxLength: 60 + example: Medellín district: - description: | - A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal. type: string - example: Lisbon District + 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. + maxLength: 60 + example: Lisbon District zip_code: - description: | - A US system of postal codes used by the United States Postal Service (USPS). type: string - example: '94103' + description: > + A US system of postal codes used by the United States Postal Service (USPS). + maxLength: 10 + example: "94103" eircode: - description: | - A postal address in Ireland. type: string - example: D02 X285 + description: > + A postal address in Ireland. + maxLength: 10 + example: "D02 X285" example: street_address: - Paul-Linke-Ufer 39-40 - 2. Hinterhof - post_code: '10999' + post_code: "10999" city: Berlin - country: DE - externalDocs: - description: Address documentation - url: https://developer.sumup.com/tools/glossary/address - required: - - country + country: "DE" CountryCode: description: |- An [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This definition users `oneOf` with a two-character string type to allow for support of future countries in client code. type: string - example: BR - maxLength: 2 minLength: 2 - pattern: ^[A-Z]{2}$ + maxLength: 2 + pattern: "^[A-Z]{2}$" + example: BR PersonalIdentifiers: - description: A list of country-specific personal identifiers. type: array + description: A list of country-specific personal identifiers. items: $ref: '#/components/schemas/PersonalIdentifier' - example: - - ref: br.cpf - value: 847.060.136-90 maxItems: 32 + example: + - ref: "br.cpf" + value: "847.060.136-90" PersonalIdentifier: type: object + required: + - ref + - value properties: ref: - description: The unique reference for the personal identifier type. type: string - example: br.cpf + description: The unique reference for the personal identifier type. + example: "br.cpf" maxLength: 32 value: - description: The company identifier value. type: string - example: 847.060.136-90 + description: >- + The company identifier value. + example: "847.060.136-90" maxLength: 128 example: - ref: br.cpf - value: 847.060.136-90 - required: - - ref - - value + ref: "br.cpf" + value: "847.060.136-90" ListPersonsResponseBody: type: object + required: + - items properties: items: type: array items: $ref: '#/components/schemas/Person' - required: - - items Merchant: + title: Merchant + externalDocs: + description: Merchant documentation + url: https://developer.sumup.com/tools/glossary/merchant allOf: - type: object required: @@ -6518,23 +6591,29 @@ components: - default_locale properties: merchant_code: - description: Short unique identifier for the merchant. type: string - example: MK01A8C2 readOnly: true + description: Short unique identifier for the merchant. + example: MK01A8C2 organization_id: - description: ID of the organization the merchant belongs to (if any). type: string + description: ID of the organization the merchant belongs to (if any). example: G0UZPVAX business_type: - description: | + type: string + 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: @@ -6542,33 +6621,37 @@ components: 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 + 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`. + 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 + 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`. + default_currency: - description: | - Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account. type: string + readOnly: true + description: > + Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217) representing the default currency for the account. + example: EUR - maxLength: 3 minLength: 3 - readOnly: true + maxLength: 3 default_locale: - description: |- + type: string + 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 + maxLength: 5 sandbox: - description: True if the merchant is a sandbox for testing. type: boolean + description: True if the merchant is a sandbox for testing. example: false meta: $ref: '#/components/schemas/Meta' @@ -6579,50 +6662,50 @@ components: change_status: $ref: '#/components/schemas/ChangeStatus' - $ref: '#/components/schemas/Timestamps' - externalDocs: - description: Merchant documentation - url: https://developer.sumup.com/tools/glossary/merchant - title: Merchant 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 + 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. + example: {} BusinessProfile: - description: | - Business information about the merchant. This information will be visible to the merchant's customers. type: object + description: > + Business information about the merchant. This information will be visible to the merchant's customers. + properties: name: - description: The customer-facing business name. type: string - example: Example Coffee - maxLength: 150 + description: The customer-facing business name. minLength: 1 + maxLength: 150 + example: Example Coffee 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 + maxLength: 30 pattern: ^[a-zA-Z0-9 \-+\'_.]{0,30}$ + 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). + + example: Example Coffee website: - description: The business's publicly available website. type: string - example: https://example.com + description: The business's publicly available website. maxLength: 255 + example: https://example.com email: - description: A publicly available email address. type: string - example: contact@example.com + description: A publicly available email address. maxLength: 255 + example: contact@example.com phone_number: $ref: '#/components/schemas/PhoneNumber' address: @@ -6633,206 +6716,238 @@ components: allOf: - $ref: '#/components/schemas/BasePerson' PhoneNumber: - description: | - A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. type: string - example: '+420123456789' + description: > + A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. + + example: "+420123456789" maxLength: 16 Branding: - description: Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products. type: object + description: Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products. properties: footer_text: - description: | - Footer text rendered on receipts and other customer-facing products. type: string + description: > + Footer text rendered on receipts and other customer-facing products. + + minLength: 1 + maxLength: 500 examples: - Thanks for shopping with us. - maxLength: 500 - minLength: 1 icon: - description: | - An icon for the merchant. Must be square. type: string format: uri + description: > + An icon for the merchant. Must be square. + 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 + 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. + hero: - description: | - Data-URL encoded hero image for the merchant business. type: string format: uri + description: > + Data-URL encoded hero image for the merchant business. + primary_color: - description: | - A hex color value representing the primary branding color of this merchant (your brand color). type: string + description: > + A hex color value representing the primary branding color of this merchant (your brand color). + examples: - - '#FF4B3A' - - '#0072C6' - - '#F68B20' + - "#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 + description: > + A hex color value representing the color of the text displayed on branding color of this merchant. + examples: - - '#FF4B3A' - - '#0072C6' - - '#F68B20' + - "#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 + description: > + A hex color value representing the secondary branding color of this merchant (accent color used for buttons). + examples: - - '#FF4B3A' - - '#0072C6' - - '#F68B20' + - "#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 + description: > + A hex color value representing the color of the text displayed on secondary branding color of this merchant. + examples: - - '#FF4B3A' - - '#0072C6' - - '#F68B20' + - "#FF4B3A" + - "#0072C6" + - "#F68B20" background_color: - description: | - A hex color value representing the preferred background color of this merchant. type: string + description: > + A hex color value representing the preferred background color of this merchant. + examples: - - '#FF4B3A' - - '#0072C6' - - '#F68B20' + - "#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 + type: string + 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. + minLength: 4 + maxLength: 64 + examples: + - de.freiberufler + - br.ltda + - gb.partnership + - bg.private_limited_company CompanyIdentifiers: - description: | - A list of country-specific company identifiers. type: array + description: > + A list of country-specific company identifiers. + items: $ref: '#/components/schemas/CompanyIdentifier' CompanyIdentifier: + externalDocs: + description: Company identifier documentation + url: https://developer.sumup.com/tools/glossary/merchant#company-identifiers type: object + required: + - ref + - value properties: ref: - description: | - The unique reference for the company identifier type as defined in the country SDK. type: string + description: > + The unique reference for the company identifier type as defined in the country SDK. + examples: - - de.gmbh + - "de.gmbh" value: - description: | - The company identifier value. type: string - examples: - - HRB 123456 maxLength: 100 + description: > + The company identifier value. + + examples: + - "HRB 123456" 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 + - ref: "de.gmbh" + value: "HRB 123456" Ownership: type: object + required: + - share properties: share: - description: | + 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 + maximum: 100000 + example: 50000 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 + description: > + The version of the resource. The version reflects a specific change submitted to the API via one of the `PATCH` endpoints. + examples: - - chng_01HS0KG3MPVEVWW85E3KNXH55J + - "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 + 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. + 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`. + externalDocs: + description: Person documentation + url: https://developer.sumup.com/tools/glossary/merchant#persons type: object + 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`. + + required: + - id 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 + description: > + The unique identifier for the Person. This is a [typeid](https://github.com/sumup/typeid). + + examples: + - "pers_2EGQ057R6C8J791RVCG5NWAEAB" user_id: - description: | - A corresponding identity user ID for the Person, if they have a user account. type: string + description: > + A corresponding identity user ID for the Person, if they have a user account. + examples: - - ef263f37-8701-4181-9758-acddbb778ee9 + - "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 + description: > + The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. + example: 1980-01-12 given_name: - description: The first name(s) of the individual. type: string + description: The first name(s) of the individual. example: James Herrald maxLength: 60 family_name: - description: The last name(s) of the individual. type: string + description: The last name(s) of the individual. 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 + 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. + 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 + 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`. + + minItems: 1 + maxItems: 1 items: type: string - description: | + 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: @@ -6842,42 +6957,44 @@ components: citizenship: $ref: '#/components/schemas/CountryCode' nationality: - description: | - The Person's 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 + description: > + The Person's 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. + 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 + 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. + minLength: 2 + maxLength: 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 Company: - description: | - Information about the company or business. This is legal information that is used for verification. + externalDocs: + description: Company documentation + url: https://developer.sumup.com/tools/glossary/merchant#company type: object + description: > + Information about the company or business. This is legal information that is used for verification. + properties: name: - description: The company's legal name. type: string - example: Gin & Doughnuts Bar GmbH - maxLength: 150 + description: The company's legal name. minLength: 1 + maxLength: 150 + example: Gin & Doughnuts Bar GmbH merchant_category_code: - description: | + 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' + example: "1532" pattern: ^[0-9]{4}$ legal_type: $ref: '#/components/schemas/LegalType' @@ -6890,51 +7007,52 @@ components: phone_number: $ref: '#/components/schemas/PhoneNumber' website: - description: | + description: > HTTP(S) URL of the company's website. + type: string + maxLength: 255 examples: - https://www.sumup.com - maxLength: 255 attributes: $ref: '#/components/schemas/Attributes' - externalDocs: - description: Company documentation - url: https://developer.sumup.com/tools/glossary/merchant#company ClassicMerchantIdentifiers: type: object + required: + - id properties: id: - description: Classic (serial) merchant ID. type: integer format: int64 + description: Classic (serial) merchant ID. 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 + 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). + readOnly: true + examples: + - "2021-08-31T12:00:00Z" 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 + 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). + readOnly: true + examples: + - "2021-08-31T12:00:00Z" required: - created_at - updated_at Reader: + title: Reader description: A physical card reader device that can accept in-person payments. type: object properties: @@ -6949,22 +7067,22 @@ components: metadata: $ref: '#/components/schemas/Metadata' service_account_id: + type: string + format: uuid + x-beta: true 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 + description: The timestamp of when the reader was created. example: 2023-01-18T15:16:17Z updated_at: - description: The timestamp of when the reader was last updated. type: string format: date-time + description: The timestamp of when the reader was last updated. example: 2023-01-20T15:16:17Z required: - id @@ -6973,13 +7091,19 @@ components: - device - created_at - updated_at - title: Reader ReaderName: - description: Custom human-readable, user-defined name for easier identification of the reader. type: string - example: Frontdesk + description: Custom human-readable, user-defined name for easier identification of the reader. maxLength: 500 + example: Frontdesk ReaderStatus: + type: string + example: "paired" + enum: + - "unknown" + - "processing" + - "paired" + - "expired" description: |- The status of the reader object gives information about the current state of the reader. @@ -6989,44 +7113,34 @@ components: - `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 + description: >- + Information about the underlying physical device. properties: identifier: - description: A unique identifier of the physical device (e.g. serial number). type: string + description: A unique identifier of the physical device (e.g. serial number). example: U1DT3NA00-CN model: - description: Identifier of the model of the device. type: string - example: solo + description: Identifier of the model of the device. enum: - solo - virtual-solo + example: 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 + 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. example: 4WLFDSBF - maxLength: 9 minLength: 8 + maxLength: 9 CreateReaderCheckoutUnprocessableEntity: description: Unprocessable entity - type: object - properties: - errors: - type: object - additionalProperties: true example: DataValidation: description: Validation errors for the informed fields. @@ -7060,15 +7174,18 @@ components: errors: detail: The device is offline. type: READER_OFFLINE + properties: + errors: + additionalProperties: true + type: object required: - errors title: CreateReaderCheckoutUnprocessableEntity + type: object CreateReaderCheckoutError: description: Error description - type: object properties: errors: - type: object properties: detail: description: Error message @@ -7078,51 +7195,69 @@ components: type: string required: - type + type: object required: - errors title: CreateReaderCheckoutError - GetReaderCheckoutResponse: type: object + GetReaderCheckoutResponse: + example: + data: + card_type: credit + checkout_id: 00e33a36-c99b-4cb2-b635-b90c1455c9c8 + client_transaction_id: 00e33a36-c99b-4cb2-b635-b90c1455c9c8 + created_at: 2026-07-07T20:41:16.315434Z + installments: 1 + payment_status: pending + payment_type: card + reader_firmware_version: 3.3.3.21 + reader_serial_number: '1234567890' + status: pending + total_amount: + currency: EUR + minor_unit: 2 + value: 10000 + updated_at: 2026-07-07T20:42:18.117244Z + valid_until: 2026-07-07T20:41:16.315434Z properties: data: - type: object properties: card_type: description: Type of the card. Required for some countries - type: string enum: - credit - debit nullable: true + type: string checkout_id: description: Unique identifier for the checkout - type: string format: uuid + type: string client_transaction_id: description: Client transaction identifier associated with the checkout type: string created_at: description: Checkout creation timestamp - type: string format: date-time + type: string installments: description: Number of installments for the transaction. Required for some countries. - type: integer nullable: true + type: integer payment_failure_reason: description: Payment failure reason - type: string nullable: true + type: string payment_status: description: Payment status from payments v2 event - type: string nullable: true + type: string payment_type: description: Type of the payment. Required for some countries - type: string enum: - card - pix + type: string reader_firmware_version: description: Reader firmware version type: string @@ -7131,12 +7266,12 @@ components: type: string status: description: Current status of the checkout - type: string enum: - pending - successful - failed - cancelled + type: string total_amount: description: | Amount structure. @@ -7144,7 +7279,6 @@ components: 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 @@ -7152,34 +7286,35 @@ components: properties: currency: description: Currency ISO 4217 code - type: string example: EUR + type: string 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 + type: integer value: description: Integer value of the amount. - type: integer example: 1000 minimum: 0 + type: integer required: - currency - minor_unit - value title: Money + type: object updated_at: description: Checkout last update timestamp - type: string format: date-time + type: string valid_until: description: Checkout expiration timestamp. After this time, the checkout will be automatically cancelled. - type: string format: date-time nullable: true + type: string required: - checkout_id - client_transaction_id @@ -7194,49 +7329,38 @@ components: - updated_at - status - total_amount - example: - data: - card_type: credit - checkout_id: 00e33a36-c99b-4cb2-b635-b90c1455c9c8 - client_transaction_id: 00e33a36-c99b-4cb2-b635-b90c1455c9c8 - created_at: 2026-07-07T20:41:16.315434Z - installments: 1 - payment_status: pending - payment_type: card - reader_firmware_version: 3.3.3.21 - reader_serial_number: '1234567890' - status: pending - total_amount: - currency: EUR - minor_unit: 2 - value: 10000 - updated_at: 2026-07-07T20:42:18.117244Z - valid_until: 2026-07-07T20:41:16.315434Z + type: object required: - data title: GetReaderCheckoutResponse + type: object StatusResponse: description: Status of a device - type: object + example: + data: + battery_level: 10.0 + battery_temperature: 35 + connection_type: Wi-Fi + firmware_version: 3.3.3.21 + last_activity: 2025-09-25T15:20:00Z + state: IDLE + status: ONLINE properties: data: - type: object properties: battery_level: description: Battery level percentage - type: number - format: float example: 10.5 + format: float maximum: 100 minimum: 0 + type: number battery_temperature: description: Battery temperature in Celsius - type: integer example: 35 + type: integer connection_type: description: Type of connection used by the device - type: string - example: Wi-Fi enum: - btle - edge @@ -7245,19 +7369,19 @@ components: - umts - usb - Wi-Fi + example: Wi-Fi + type: string firmware_version: description: Firmware version of the device - type: string example: 3.3.3.21 + type: string last_activity: description: Timestamp of the last activity from the device - type: string - format: date-time example: 2025-09-25T15:20:00Z + format: date-time + type: string state: description: Latest state of the device - type: string - example: IDLE enum: - IDLE - SELECTING_TIP @@ -7265,34 +7389,24 @@ components: - WAITING_FOR_PIN - WAITING_FOR_SIGNATURE - UPDATING_FIRMWARE + example: IDLE + type: string status: description: Status of a device - type: string - example: ONLINE enum: - ONLINE - OFFLINE + example: ONLINE + type: string 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 + type: object required: - data title: StatusResponse + type: object CreateReaderTerminateUnprocessableEntity: description: Unprocessable entity - type: object - properties: - errors: - type: object - additionalProperties: true example: ReaderOffline: description: Error returned when the target device is not online. @@ -7300,15 +7414,18 @@ components: errors: detail: The device is offline. type: READER_OFFLINE + properties: + errors: + additionalProperties: true + type: object required: - errors title: CreateReaderTerminateUnprocessableEntity + type: object CreateReaderTerminateError: description: Error description - type: object properties: errors: - type: object properties: detail: description: Error message @@ -7318,162 +7435,186 @@ components: type: string required: - type + type: object required: - errors title: CreateReaderTerminateError + type: object BadRequest: description: 400 Bad Request - type: object + example: + errors: + detail: Bad request + type: INVALID_BEARER_TOKEN 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 + type: string required: - type - example: - errors: - detail: Bad request - type: INVALID_BEARER_TOKEN + type: object required: - errors title: BadRequest - CreateReaderCheckoutResponse: type: object + CreateReaderCheckoutResponse: + example: + data: + checkout_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + client_transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 properties: data: - type: object properties: checkout_id: description: | The checkout ID is a unique identifier for the checkout. - type: string example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + type: string 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 + type: string required: - client_transaction_id - example: - data: - checkout_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - client_transaction_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + type: object required: - data title: CreateReaderCheckoutResponse + type: object Unauthorized: description: 401 Unauthorized - type: object + example: + errors: + detail: Unauthorized 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 + type: string required: - detail - example: - errors: - detail: Unauthorized + type: object required: - errors title: Unauthorized + type: object CreateReaderCheckoutRequest: description: Reader Checkout - type: object + 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 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' + type: string signature: description: The base64 encoded signature of the transaction data. - type: string example: QjcxRDdBNTU1MDcyRTNFRTREMkZEM0Y0NTdBMjkxMTU4MzBFNkNCQTs7MjAyNTExMTIyMTQ3MTM7Nzk2OzEwNDs5MDA7OTAwOzU0ODg5MDM5 + type: string signature_data: description: The string containing the signed transaction data. - type: string example: B71D7A555072E3EE4D2FD3F457A29115830E6CBA;;20251112214713;796;104;900;900;54889039 + type: string required: - provider_id - signature - signature_data + type: object 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 + type: string 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 + type: string 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 + type: string tags: + additionalProperties: true 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 + type: object required: - app_id - key - foreign_transaction_id title: Affiliate + type: object 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 + example: credit + type: string description: description: Description of the checkout to be shown in the Merchant Sales type: string @@ -7485,28 +7626,29 @@ components: Omit if the merchant country does support installments. Otherwise, the checkout will be rejected. - type: integer example: 1 minimum: 1 nullable: true + type: integer 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 + format: uri + type: string 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 + type: array tip_timeout: + default: 30 description: | Time in seconds the cardholder has to select a tip rate. If not provided, the default value is 30 seconds. @@ -7514,11 +7656,10 @@ components: 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 + type: integer total_amount: description: | Amount structure. @@ -7526,7 +7667,6 @@ components: 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 @@ -7534,146 +7674,102 @@ components: properties: currency: description: Currency ISO 4217 code - type: string example: EUR + type: string 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 + type: integer value: description: Integer value of the amount. - type: integer example: 1000 minimum: 0 + type: integer 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 + type: object required: - total_amount title: CreateReaderCheckoutRequest + type: object 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 + type: string id: description: Unique identifier for the event. - type: string - format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + format: uuid + type: string 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 + format: uuid + type: string merchant_code: description: The merchant code associated with the transaction. - type: string example: M1234567 + type: string status: description: The current status of the transaction. - type: string - example: successful enum: - successful - failed + example: successful + type: string transaction_id: + deprecated: true description: 'The transaction id. Deprecated: use `client_transaction_id` instead.' - type: string - format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - deprecated: true + format: uuid + type: string required: - client_transaction_id - merchant_code - status + type: object timestamp: description: Timestamp of the event. - type: string - format: date-time example: 2023-10-05T14:48:00Z + format: date-time + type: string required: - id - event_type - payload - timestamp title: ReaderCheckoutStatusChange + type: object NotFound: description: 404 Not Found - type: object + example: + errors: + detail: Not Found 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. + description: Fuller message giving context to error + type: string + required: + - detail + type: object + required: + - errors + title: NotFound + type: object requestBodies: CheckoutCreate: required: true @@ -7691,7 +7787,7 @@ components: currency: EUR merchant_code: MH4H92C7 description: Purchase - valid_until: 2020-02-29T10:56:56+00:00 + valid_until: '2020-02-29T10:56:56+00:00' redirect_url: https://sumup.com Checkout3DS: description: Create a 3DS checkout @@ -7735,7 +7831,7 @@ components: currency: EUR description: Updated purchase checkout_reference: f00a8f74-b05d-4605-bd73-2a901bae5802 - valid_until: 2020-02-29T10:56:56+00:00 + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 CheckoutProcess: required: true @@ -7752,7 +7848,8 @@ components: 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_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 @@ -7828,13 +7925,14 @@ components: example: amount: 5 schema: - description: Optional amount for partial refunds of transactions. type: object + description: Optional amount for partial refunds of transactions. 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 + 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. example: 5 responses: Checkout: @@ -7856,8 +7954,8 @@ components: 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 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent @@ -7868,7 +7966,7 @@ components: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -7887,8 +7985,8 @@ components: 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 + 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: @@ -7896,7 +7994,7 @@ components: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -7916,7 +8014,7 @@ components: return_url: http://example.com id: 88fcf8de-304d-4820-8f1c-ec880290eb92 status: PENDING - date: 2021-06-29T11:08:36.000+00:00 + date: '2021-06-29T11:08:36.000+00:00' merchant_name: My company merchant_country: DE redirect_url: https://sumup.com @@ -7926,7 +8024,7 @@ components: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -7947,7 +8045,7 @@ components: description: A sample checkout id: 64553e20-3f0e-49e4-8af3-fd0eca86ce91 status: PENDING - date: 2000-01-01T12:49:24.899+00:00 + date: '2000-01-01T12:49:24.899+00:00' purpose: CHECKOUT hosted_checkout: enabled: true @@ -7968,8 +8066,8 @@ components: description: Updated purchase 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 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 transactions: [] CheckoutList: @@ -7988,7 +8086,7 @@ components: description: Purchase id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' CheckoutRetrieve: description: Returns the requested checkout resource. content: @@ -8003,7 +8101,7 @@ components: description: Purchase id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 CheckoutProcess: @@ -8024,8 +8122,8 @@ components: 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 + date: '2020-02-29T10:56:56+00:00' + valid_until: '2020-02-29T10:56:56+00:00' customer_id: 831ff8d4cd5958ab5670 mandate: type: recurrent @@ -8036,7 +8134,7 @@ components: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -8057,7 +8155,7 @@ components: description: Purchase with token id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2020-02-29T10:56:56+00:00 + date: '2020-02-29T10:56:56+00:00' transaction_code: TEENSK4W2K transaction_id: 410fc44a-5956-44e1-b5cc-19c6f8d727a4 merchant_name: Sample Merchant @@ -8070,7 +8168,7 @@ components: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -8089,11 +8187,12 @@ components: description: Boleto checkout id: 4e425463-3e1b-431d-83fa-1e51c2925e99 status: PENDING - date: 2021-07-06T12:34:02.000+00:00 + 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 + url: >- + https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto redirect_url: https://website.com purpose: CHECKOUT transactions: @@ -8104,7 +8203,7 @@ components: vat_amount: 6 tip_amount: 3 currency: BRL - timestamp: 2021-07-06T12:34:16.460+00:00 + timestamp: '2021-07-06T12:34:16.460+00:00' status: PENDING payment_type: BOLETO entry_mode: BOLETO @@ -8118,8 +8217,10 @@ components: payload: tx: '961473700' rs: ILnaUeQTKJ184fVrjGILrLjePX9E4rmz - cs: c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 - full: https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 + cs: >- + c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 + full: >- + https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5 mechanism: - browser CheckoutSuccessBancontact: @@ -8131,8 +8232,10 @@ components: payload: tx: '624788471' rs: 5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB - cs: 697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc - full: https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc + cs: >- + 697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc + full: >- + https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc mechanism: - browser CheckoutProcessAccepted: @@ -8166,7 +8269,7 @@ components: transaction_code: TEENSK4W2K amount: 10.1 currency: EUR - timestamp: 2020-02-29T10:56:56.876Z + timestamp: '2020-02-29T10:56:56.876Z' status: SUCCESSFUL payment_type: ECOM installments_count: 1 @@ -8279,6 +8382,9 @@ components: application/json: schema: type: object + required: + - total_count + - items properties: items: type: array @@ -8287,15 +8393,14 @@ components: total_count: type: integer example: 3 - required: - - total_count - - items ListMembers: description: Returns a list of Member objects. content: application/json: schema: type: object + required: + - items properties: items: type: array @@ -8304,24 +8409,173 @@ components: total_count: type: integer example: 3 - required: - - items ListRoles: description: Returns a list of Role objects. content: application/json: schema: type: object + required: + - items properties: items: type: array items: $ref: '#/components/schemas/Role' - required: - - items + parameters: + 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 + CheckoutID: + name: checkout_id + in: path + required: true + description: Unique ID of the checkout resource. + schema: + type: string + CustomerID: + name: customer_id + in: path + required: true + description: Unique ID of the saved customer resource. + schema: + type: string + 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 + OrderFilter: + name: order + in: query + description: Specifies the order in which the returned results are displayed. + schema: + type: string + enum: + - ascending + - descending + default: ascending + 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 + UsersFilter: + name: users[] + in: query + description: Filters the returned results by user email. + required: false + example: + - merchant@example.com + schema: + type: array + example: + - merchant@example.com + items: + type: string + format: email + 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 + 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' + 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' + 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 + 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 + 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 + 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 + 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 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) + 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: @@ -8373,82 +8627,28 @@ components: user.payout-settings: View and manage your payout settings. payouts.read: View payouts. 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: Readers - - 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: A Merchant represents a single business which can use SumUp products like payment processing. - x-core-objects: - - $ref: '#/components/schemas/Merchant' + 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.