From 57961ce9a65c9a7f85b4598eecb90f18b8b460ae Mon Sep 17 00:00:00 2001 From: appscisumup Date: Wed, 14 Oct 2026 21:39:11 +0000 Subject: [PATCH 1/2] chore: synced local 'openapi.json' with remote 'specs/openapi31.json' --- openapi.json | 479 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 312 insertions(+), 167 deletions(-) diff --git a/openapi.json b/openapi.json index f514d26..d530258 100644 --- a/openapi.json +++ b/openapi.json @@ -3,7 +3,7 @@ "info": { "title": "SumUp REST API", "version": "1.0.0", - "description": "SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status).\n\nYou 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).", + "description": "SumUp's REST API lets you create and process payments, manage saved customers and payment instruments, and retrieve transactions, payouts, and receipt details. It uses resource-oriented URLs and standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status). Send request bodies as [JSON](https://www.json.org/json-en.html) with `Content-Type: application/json`, unless an endpoint specifies another format.\n\nYou 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" @@ -27,7 +27,7 @@ }, { "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.", + "description": "Customers represent payers in your integration. Create a customer with your own `customer_id` to associate their personal details and saved payment instruments with your business records.\n\nTo save a card, create a checkout for that customer with `purpose = SETUP_RECURRING_PAYMENT`, then process it with the payer's consent and mandate details. See the [tokenization guide](https://developer.sumup.com/online-payments/guides/tokenization-with-payment-sdk/).\n\nUse the Customers endpoints to create, retrieve, or update customer details and to list or deactivate saved payment instruments. For subsequent payments, process a new checkout with the saved instrument's `token` and its associated `customer_id`.", "x-core-objects": [ { "$ref": "#/components/schemas/Customer" @@ -49,7 +49,7 @@ }, { "name": "Receipts", - "description": "The Receipts model obtains receipt-like details for specific transactions.", + "description": "Retrieve structured receipt data for a transaction, including payment, merchant, and acquirer details. Use this data to display a receipt in your application. The response is JSON, rather than a rendered receipt document.", "x-core-objects": [ { "$ref": "#/components/schemas/Receipt" @@ -110,7 +110,7 @@ "get": { "operationId": "GetPaymentMethods", "summary": "Get available payment methods", - "description": "Get payment methods available for the given merchant to use with a checkout.", + "description": "Lists the payment methods available to the merchant for checkout payments. Use the optional amount and currency filters to check eligibility for a particular payment before presenting payment options to the payer.", "tags": [ "Checkouts" ], @@ -133,7 +133,7 @@ "in": "query", "name": "amount", "required": false, - "description": "The amount for which the payment methods should be eligible, in major units.", + "description": "Payment amount in major units, for example `9.99` for EUR 9.99. When filtering by `amount`, also provide `currency`.", "schema": { "type": "number", "example": 9.99 @@ -143,7 +143,7 @@ "in": "query", "name": "currency", "required": false, - "description": "The currency for which the payment methods should be eligible.", + "description": "Three-letter ISO 4217 currency code for which the payment methods should be eligible, for example `EUR`.", "schema": { "type": "string", "example": "EUR" @@ -243,7 +243,7 @@ "post": { "operationId": "CreateCheckout", "summary": "Create a checkout", - "description": "Creates a new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout.\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.", + "description": "Creates a payment checkout for the specified merchant, amount, and currency. Supply a `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout does not charge a payment instrument.\n\nSet `hosted_checkout.enabled` to `true` to receive a [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL where the customer can complete the payment.\nUse `redirect_url` for redirect-based payment and 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback URL.\n\nComplete the payment through [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget).", "tags": [ "Checkouts" ], @@ -282,7 +282,7 @@ "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", - "valid_until": "2020-02-29T10:56:56+00:00", + "valid_until": "2030-12-31T23:59:59Z", "redirect_url": "https://sumup.com" } }, @@ -349,7 +349,7 @@ "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", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", @@ -386,7 +386,7 @@ "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", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase", "transactions": [ @@ -580,7 +580,7 @@ { "name": "checkout_reference", "in": "query", - "description": "Filters the list of checkout resources by the unique reference of the checkout.", + "description": "Filters checkouts by the merchant-defined `checkout_reference` supplied when creating the checkout. This is separate from the SumUp-generated checkout `id`.", "required": false, "schema": { "type": "string", @@ -645,7 +645,7 @@ "name": "checkout_id", "in": "path", "required": true, - "description": "Unique identifier of the checkout resource.", + "description": "SumUp-generated `id` returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.", "schema": { "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" @@ -655,7 +655,7 @@ "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 a checkout by its SumUp `checkout_id`. After processing a payment, returning from a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current `status` before updating your order or displaying the payment outcome to the payer.", "tags": [ "Checkouts" ], @@ -746,7 +746,7 @@ "patch": { "operationId": "UpdateCheckout", "summary": "Update a checkout", - "description": "Updates an identified checkout resource.", + "description": "Updates the amount, currency, description, reference, expiration, or customer associated with an existing checkout. Only the supplied fields are updated.\n\nThis request changes the checkout details; it does not charge a payment instrument. Process the checkout separately to attempt a payment.", "tags": [ "Checkouts" ], @@ -781,7 +781,7 @@ "currency": "EUR", "description": "Updated purchase", "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", - "valid_until": "2020-02-29T10:56:56+00:00", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670" } } @@ -805,7 +805,7 @@ "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", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "transactions": [] } @@ -858,7 +858,7 @@ "put": { "operationId": "ProcessCheckout", "summary": "Process a checkout", - "description": ":::caution[PCI DSS compliance required]\nWhen you submit raw card details directly to the Checkout API, your systems store, process, or transmit cardholder data and are therefore subject to applicable [PCI DSS requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this integration if your environment is appropriately PCI DSS compliant.\n:::\n\nProcessing 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.", + "description": ":::caution[PCI DSS compliance required]\nWhen you submit raw card details directly to the Checkout API, your systems store, process, or transmit cardholder data and are therefore subject to applicable [PCI DSS requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this integration if your environment is appropriately PCI DSS compliant.\n:::\n\nProcessing 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\nA processing response can require an additional payer action, such as a 3DS challenge or a payment-provider redirect. If `next_step` is returned, follow its instructions to continue the payment flow.\n\nRetrieve the checkout afterwards to confirm its payment status. Acceptance of the processing request does not by itself mean the checkout is paid.", "tags": [ "Checkouts" ], @@ -1033,9 +1033,9 @@ "description": "Purchase", "return_url": "http://example.com", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", - "status": "PENDING", + "status": "PAID", "date": "2020-02-29T10:56:56+00:00", - "valid_until": "2020-02-29T10:56:56+00:00", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", @@ -1072,7 +1072,7 @@ "merchant_code": "MH4H92C7", "description": "Purchase with token", "id": "4e425463-3e1b-431d-83fa-1e51c2925e99", - "status": "PENDING", + "status": "PAID", "date": "2020-02-29T10:56:56+00:00", "transaction_code": "TEENSK4W2K", "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4", @@ -1102,7 +1102,7 @@ } }, "CheckoutSuccessBoleto": { - "description": "Successfully processed checkout with Boleto", + "description": "Boleto payment initiated, awaiting payment by the payer", "value": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", "amount": 10.1, @@ -1138,7 +1138,7 @@ } }, "CheckoutSuccessiDeal": { - "description": "Successfully processed checkout with iDeal", + "description": "iDEAL processing response requiring a payer redirect", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simideal", @@ -1156,7 +1156,7 @@ } }, "CheckoutSuccessBancontact": { - "description": "Successfully processed checkout with Bancontact", + "description": "Bancontact processing response requiring a payer redirect", "value": { "next_step": { "url": "https://r3.girogate.de/ti/simbcmc", @@ -1335,7 +1335,7 @@ }, "example": { "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", - "id": "817340ce-f1d9-4609-b90a-6152f8ee267j", + "id": "817340ce-f1d9-4609-b90a-6152f8ee267a", "amount": 2, "currency": "EUR", "merchant_code": "MH4H92C7", @@ -1343,7 +1343,7 @@ "purpose": "CHECKOUT", "status": "EXPIRED", "date": "2020-02-29T10:56:56+00:00", - "valid_until": "2020-02-29T10:56:56+00:00", + "valid_until": "2030-12-31T23:59:59Z", "merchant_name": "Sample Merchant", "transactions": [] } @@ -1426,7 +1426,7 @@ "name": "checkout_id", "in": "path", "required": true, - "description": "Unique identifier of the checkout resource.", + "description": "SumUp-generated `id` returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.", "schema": { "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" @@ -1438,7 +1438,7 @@ }, "x-scopes": [], "requestBody": { - "description": "The data needed to create an apple pay session for a checkout.", + "description": "Merchant validation details from the Apple Pay session in the payer's browser.", "content": { "application/json": { "schema": { @@ -1450,13 +1450,13 @@ "properties": { "context": { "type": "string", - "description": "the context to create this apple pay session.", + "description": "Hostname of the website displaying the Apple Pay payment sheet, without a URL scheme or path. Use the domain registered for Apple Pay.", "format": "hostname", "example": "example.com" }, "target": { "type": "string", - "description": "The target url to create this apple pay session.", + "description": "Apple Pay validation URL received as `validationURL` in the browser's `onvalidatemerchant` event.", "format": "uri", "example": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession" } @@ -1548,7 +1548,7 @@ "post": { "operationId": "CreateCustomer", "summary": "Create a customer", - "description": "Creates a new saved customer resource which you can later manipulate and save payment instruments to.", + "description": "Creates a customer using the `customer_id` you supply. Choose an identifier that maps to the payer in your own system and reuse it when retrieving the customer or associating checkouts and saved payment instruments with them.", "tags": [ "Customers" ], @@ -1711,7 +1711,7 @@ "name": "customer_id", "in": "path", "required": true, - "description": "Unique identifier of the saved customer resource.", + "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" @@ -1721,7 +1721,7 @@ "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 a saved customer using the `customer_id` you supplied when creating the customer.", "tags": [ "Customers" ], @@ -1939,7 +1939,7 @@ "name": "customer_id", "in": "path", "required": true, - "description": "Unique identifier of the saved customer resource.", + "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" @@ -2055,7 +2055,7 @@ "name": "customer_id", "in": "path", "required": true, - "description": "Unique identifier of the saved customer resource.", + "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" @@ -2210,7 +2210,7 @@ "post": { "operationId": "RefundTransaction", "summary": "Refund a transaction", - "description": "Refunds an identified transaction either in full or partially.", + "description": "Refunds a transaction identified by its SumUp transaction ID. Omit the request body to request a full refund, or provide `amount` for a partial refund in the transaction's currency.\n\nRetrieve the transaction afterwards to inspect its refunded amount and refund events. The transaction must be eligible for a refund; see the error responses for invalid amounts, permissions, and processing failures.", "tags": [ "Transactions" ], @@ -2246,7 +2246,7 @@ "amount": { "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.", + "description": "Amount to refund in major units of the transaction's currency, for example `5` for EUR 5.00. It must be greater than zero and cannot exceed the amount eligible for a refund. Eligibility depends on the transaction and country/currency rules. If omitted, the system requests a full refund.", "example": 5 } } @@ -2260,7 +2260,8 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": {} }, "example": {} } @@ -2532,7 +2533,7 @@ "get": { "operationId": "ListTransactionsV2.1", "summary": "List transactions", - "description": "Lists detailed history of all transactions associated with the merchant profile.", + "description": "Lists transaction history for the merchant, with optional filters for payment type, status, and date range. The response contains the current page in `items` and pagination query strings in `links`.\n\nTo request another page, use the query string from the relevant link's `href` with this history endpoint. Use `changes_since` when retrieving transactions modified since a previous synchronization, including transactions created earlier whose status has changed.", "tags": [ "Transactions" ], @@ -2578,7 +2579,7 @@ { "name": "order", "in": "query", - "description": "Specifies the order in which the returned results are displayed.", + "description": "Sort direction for the transaction history. Use `ascending` or `descending`; the default is `ascending`.", "schema": { "type": "string", "enum": [ @@ -2591,7 +2592,7 @@ { "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": "Maximum number of transactions per page. Must be a positive integer. Defaults to `10` when omitted; a page can contain fewer results.", "schema": { "type": "integer", "example": 10 @@ -2600,7 +2601,7 @@ { "name": "users[]", "in": "query", - "description": "Filters the returned results by user email.", + "description": "Filters transactions by user email. For multiple values, repeat the query parameter, for example `users[]=first@example.com\u0026users[]=second@example.com`.", "required": false, "example": [ "merchant@example.com" @@ -2619,7 +2620,7 @@ { "name": "statuses[]", "in": "query", - "description": "Filters the returned results by the specified list of final statuses of the transactions.", + "description": "Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example `statuses[]=SUCCESSFUL\u0026statuses[]=REFUNDED`.", "required": false, "schema": { "type": "array", @@ -2717,7 +2718,7 @@ { "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": "Pagination reference that returns results before the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over `newest_time` when both are provided.", "required": false, "schema": { "type": "string", @@ -2738,7 +2739,7 @@ { "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": "Pagination reference that returns results after the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over `oldest_time` when both are provided.", "required": false, "schema": { "type": "string", @@ -3060,7 +3061,7 @@ "get": { "operationId": "GetReceipt", "summary": "Retrieve receipt details", - "description": "Retrieves receipt specific data for a transaction.", + "description": "Retrieves structured receipt data for a transaction belonging to the merchant specified by `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide `tx_event_id` to include a specific transaction event, such as a refund, on the receipt.", "tags": [ "Receipts" ], @@ -3443,28 +3444,30 @@ "type": "string" } }, + { + "name": "resource.id", + "in": "query", + "description": "Filter memberships by the ID of the resource the membership is in.", + "schema": { + "type": "string" + } + }, { "name": "resource.parent.id", "in": "query", - "description": "Filter memberships by the parent of the resource the membership is in.\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.", + "allowEmptyValue": true, + "description": "Filter memberships by the parent of the resource the membership is in.\nOmit both `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.", "schema": { - "type": [ - "string", - "null" - ] + "type": "string" } }, { "name": "resource.parent.type", "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.", + "allowEmptyValue": true, + "description": "Filter memberships by the parent of the resource the membership is in.\nOmit both `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.", "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/ResourceType" - } - ], - "type": "null" + "$ref": "#/components/schemas/ResourceType" } }, { @@ -3603,19 +3606,6 @@ "example": "245b2ead-85bf-45ff-856f-311a88a5d454" } }, - { - "name": "user.type", - "in": "query", - "description": "Filter the returned members by user type. Repeat this parameter to include multiple user types.", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/UserType" - } - }, - "style": "form", - "explode": true - }, { "name": "status", "in": "query", @@ -3730,7 +3720,7 @@ "post": { "operationId": "CreateMerchantMember", "summary": "Create a member", - "description": "Create a merchant member.", + "description": "Adds a member to the merchant account with the specified roles.\n\nBy default, sends an invitation email to the provided address. The recipient must accept the invitation to join the account.\nWhen `is_managed_user` is `true`, creates a managed user with the provided password and optional nickname and assigns the roles directly, without sending an invitation.", "tags": [ "Members" ], @@ -3795,6 +3785,7 @@ "roles": { "type": "array", "description": "List of roles to assign to the new member.", + "minItems": 1, "maxItems": 124, "items": { "type": "string", @@ -3978,7 +3969,7 @@ }, "put": { "summary": "Update a member", - "description": "Update the merchant member.", + "description": "Updates a merchant member and returns the updated member.\n\nProviding `roles` replaces the member's assigned roles and can grant or revoke access. Providing `metadata` replaces the entire metadata object.\nFor managed users, `user.nickname` changes the display name and `user.password` replaces the password. Updating the password also enables the managed user account.", "tags": [ "Members" ], @@ -4017,6 +4008,7 @@ "properties": { "roles": { "type": "array", + "minItems": 1, "maxItems": 124, "items": { "type": "string", @@ -4392,6 +4384,7 @@ "permissions": { "type": "array", "description": "User's permissions.", + "minItems": 1, "maxItems": 100, "items": { "type": "string" @@ -4652,7 +4645,7 @@ "patch": { "operationId": "UpdateMerchantRole", "summary": "Update a role", - "description": "Update a custom role.", + "description": "Updates a custom role's name, description, or permissions and returns the updated role.\n\nProviding `permissions` replaces the role's permission list and changes the access granted to members assigned to that role. Omitted fields remain unchanged.", "tags": [ "Roles" ], @@ -4696,6 +4689,7 @@ "permissions": { "type": "array", "description": "User's permissions.", + "minItems": 1, "maxItems": 100, "items": { "type": "string" @@ -5438,7 +5432,7 @@ }, "patch": { "summary": "Update a Reader", - "description": "Update a Reader.", + "description": "Updates a reader's name or metadata and returns the updated reader.\n\nProviding `metadata` replaces the entire metadata object; include all entries that should be retained. Omitted fields remain unchanged.", "operationId": "UpdateReader", "tags": [ "Readers" @@ -6246,6 +6240,11 @@ }, "type": { "$ref": "#/components/schemas/CardType" + }, + "payment_account_reference": { + "type": "string", + "description": "Payment Account Reference (PAR) defined by [EMVCo](https://www.emvco.com/emv-technologies/payment-tokenisation/). It links a card's primary account number (PAN) with its affiliated payment tokens, allowing transactions made with the physical card and tokenized versions of that card, such as digital wallets, to be correlated when PAR is available.\n\nThis reference cannot be used to initiate a payment and is separate from the saved payment instrument `token` used to process checkouts. Returned only when available for the card; integrations must handle its absence.", + "example": "5665ABCDEFGHIJKLMNOPQRSTUVWXY" } } }, @@ -6330,7 +6329,7 @@ "properties": { "checkout_reference": { "type": "string", - "maxLength": 90, + "maxLength": 64, "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" }, @@ -6356,7 +6355,7 @@ "return_url": { "type": "string", "format": "uri", - "description": "Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.", + "description": "Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.", "example": "http://example.com" }, "id": { @@ -6387,7 +6386,7 @@ "string", "null" ], - "example": "2020-02-29T10:56:56+00:00", + "example": "2030-12-31T23:59:59Z", "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." }, @@ -6448,7 +6447,7 @@ "checkout_reference": { "type": "string", "maxLength": 64, - "description": "Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems.", + "description": "Merchant-defined reference for the new checkout, up to 64 characters. Use it to correlate the checkout with an order or payment attempt in your own system. If a checkout already exists for the supplied unique parameters, creation returns `409` with `DUPLICATED_CHECKOUT`; see the conflict response.", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, "amount": { @@ -6473,7 +6472,7 @@ "return_url": { "type": "string", "format": "uri", - "description": "Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.", + "description": "Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.", "example": "http://example.com/" }, "customer_id": { @@ -6495,7 +6494,7 @@ "string", "null" ], - "example": "2020-02-29T10:56:56+00:00", + "example": "2030-12-31T23:59:59Z", "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." }, @@ -6536,7 +6535,7 @@ }, "checkout_reference": { "type": "string", - "maxLength": 90, + "maxLength": 64, "description": "Updated merchant-defined reference for the checkout.", "example": "f00a8f74-b05d-4605-bd73-2a901bae5802" }, @@ -6545,7 +6544,7 @@ "string", "null" ], - "example": "2020-02-29T10:56:56+00:00", + "example": "2030-12-31T23:59:59Z", "format": "date-time", "description": "Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable." }, @@ -6634,7 +6633,7 @@ }, "token": { "type": "string", - "description": "Saved-card token to use instead of raw card details when processing with a previously stored payment instrument.", + "description": "Token of a saved payment instrument returned by checkout processing or the customer's payment-instruments endpoint. To charge a saved card, set `payment_type` to `card` and provide both this `token` and the associated `customer_id` instead of raw card details.", "example": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50" }, "customer_id": { @@ -6754,14 +6753,14 @@ "Customer": { "type": "object", "title": "Customer", - "description": "Saved customer details.", + "description": "Saved payer details identified by the `customer_id` supplied by your integration. A customer can have saved payment instruments for subsequent payments.", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", - "description": "Unique identifier of the customer.", + "description": "Identifier you supply when creating the customer. Use an ID from your own system and retain it for subsequent customer, checkout, and saved-payment-instrument requests.", "example": "831ff8d4cd5958ab5670" }, "personal_details": { @@ -7094,12 +7093,12 @@ "properties": { "rel": { "type": "string", - "description": "Relation.", + "description": "Pagination relation indicating which page the link retrieves, for example `next`.", "example": "next" }, "href": { "type": "string", - "description": "Location.", + "description": "Query string to use with the transaction history endpoint when requesting the linked page. Preserve the returned pagination references and query parameters.", "example": "limit=10\u0026oldest_ref=090df9bf-93b7-40f1-8181-fbdb236568a1\u0026order=ascending" } }, @@ -7180,7 +7179,7 @@ "properties": { "token": { "type": "string", - "description": "Unique token identifying the saved payment card for a customer.", + "description": "Token identifying the customer's saved payment card. Pass it as `token`, together with the associated `customer_id` and `payment_type = card`, when processing a checkout with this instrument.", "readOnly": true, "example": "bcfc8e5f-3b47-4cb9-854b-3b7a4cce7be3" }, @@ -7268,7 +7267,7 @@ }, "birth_date": { "type": "string", - "description": "Date of birth of the customer.", + "description": "Date of birth of the customer in `YYYY-MM-DD` format, without a time or timezone.", "format": "date", "example": "1993-12-31" }, @@ -7307,7 +7306,7 @@ "vat_rate": { "type": "number", "format": "decimal", - "description": "VAT rate applied to the product price.", + "description": "VAT rate as a decimal fraction, for example `0.19` for 19%.", "example": 0.19 }, "single_vat_amount": { @@ -7350,7 +7349,7 @@ "Receipt": { "type": "object", "title": "Receipt", - "description": "Receipt details for a transaction.", + "description": "Structured receipt details for a transaction. The transaction's `amount`, `vat_amount`, and `tip_amount`, as well as event amounts, are returned as decimal strings in major currency units, for example `\"10.10\"` for EUR 10.10.", "properties": { "transaction_data": { "$ref": "#/components/schemas/ReceiptTransaction" @@ -7799,7 +7798,7 @@ "amount": { "type": "number", "format": "decimal", - "description": "Amount of the event.", + "description": "Amount of the event in major units of the associated transaction's currency.", "example": 58.8 }, "due_date": { @@ -7816,7 +7815,7 @@ }, "installment_number": { "type": "integer", - "description": "Consecutive number of the installment that is paid. Applicable only payout events, i.e. `event_type = PAYOUT`.", + "description": "Consecutive number of the installment that is paid. Applicable only to payout events, i.e. `event_type = PAYOUT`.", "example": 1 }, "timestamp": { @@ -7839,13 +7838,13 @@ }, "transaction_code": { "type": "string", - "description": "Transaction code returned by the acquirer/processing entity after processing the transaction.", + "description": "SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the `transaction_code` query parameter. This is separate from the transaction's `id` and the card issuer's `auth_code`.", "example": "TEENSK4W2K" }, "amount": { "type": "number", "format": "float", - "description": "Total amount of the transaction.", + "description": "Total amount of the transaction in major units of `currency`, for example `10.1` for EUR 10.10.", "example": 10.1 }, "currency": { @@ -7884,13 +7883,13 @@ "vat_amount": { "type": "number", "format": "float", - "description": "Amount of the applicable VAT (out of the total transaction amount).", + "description": "VAT included in the total transaction amount, in major units of the transaction's currency.", "example": 6 }, "tip_amount": { "type": "number", "format": "float", - "description": "Amount of the tip (out of the total transaction amount).", + "description": "Tip included in the total transaction amount, in major units of the transaction's currency.", "example": 3 }, "entry_mode": { @@ -7993,7 +7992,7 @@ "refunded_amount": { "type": "number", "format": "decimal", - "description": "Total refunded amount.", + "description": "Total amount refunded for this transaction, in major units of the transaction's currency.", "example": 0 } } @@ -8003,7 +8002,7 @@ "PaymentType": { "title": "Payment Type", "type": "string", - "description": "Payment type used for the transaction.", + "description": "Payment category recorded on a transaction, for example `POS` for a point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. These reporting values are separate from the lowercase `payment_type` values used to process checkouts.", "enum": [ "CASH", "POS", @@ -8022,7 +8021,7 @@ "EntryMode": { "title": "Entry Mode", "type": "string", - "description": "Entry mode of the payment details.", + "description": "How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`.", "enum": [ "BOLETO", "SOFORT", @@ -8061,6 +8060,7 @@ "enum": [ "ALELO", "AMEX", + "BANCOMAT", "CONECS", "CUP", "DINERS", @@ -8121,7 +8121,7 @@ "fee_amount": { "type": "number", "format": "decimal", - "description": "Transaction SumUp total fee amount.", + "description": "Total SumUp transaction fee in major units of the transaction's currency.", "example": 8 }, "lat": { @@ -8319,7 +8319,6 @@ "type": "string", "description": "Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount.", "enum": [ - "BGN", "BRL", "CHF", "CLP", @@ -8354,7 +8353,7 @@ "TransactionEventType": { "title": "Transaction Event Type", "type": "string", - "description": "Type of the transaction event.", + "description": "Financial event associated with a transaction.\n\n- `PAYOUT`: Funds from the transaction being prepared for or included in a merchant payout. Check the event status to determine whether they have been paid out.\n- `REFUND`: Money returned to the payer.\n- `CHARGE_BACK`: A reversal of the payment following a chargeback.\n- `PAYOUT_DEDUCTION`: An amount deducted from a merchant payout, for example to cover a refund or chargeback.", "enum": [ "PAYOUT", "CHARGE_BACK", @@ -8382,7 +8381,7 @@ "title": "Transaction Event ID", "type": "integer", "format": "int64", - "description": "Unique identifier of the transaction event.", + "description": "Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting receipt details for a specific event. This is separate from the transaction ID and the transaction history pagination references.", "example": 9567461191 }, "HorizontalAccuracy": { @@ -8397,7 +8396,7 @@ "type": "number", "format": "float", "description": "Latitude value from the coordinates of the payment location (as received from the payment terminal reader).", - "minimum": 0, + "minimum": -90, "maximum": 90, "example": 52.520008 }, @@ -8406,7 +8405,7 @@ "type": "number", "format": "float", "description": "Longitude value from the coordinates of the payment location (as received from the payment terminal reader).", - "minimum": 0, + "minimum": -180, "maximum": 180, "example": 13.404954 }, @@ -8462,7 +8461,15 @@ "ReaderPaymentRequestParams": { "properties": { "affiliate": { - "$ref": "#/components/schemas/Affiliate" + "allOf": [ + { + "description": "Optional caller-supplied context about the integration initiating the payment.", + "type": "object" + }, + { + "$ref": "#/components/schemas/Affiliate" + } + ] }, "client_transaction_id": { "description": "Caller-supplied correlation identifier, used as the idempotency key.", @@ -8470,12 +8477,23 @@ "type": "string" }, "tip_amount": { - "description": "Optional tip amount in minor units, added on top of total_amount.", - "example": 100, + "description": "Portion of total_amount that is a tip, in minor units.", + "example": 200, "type": "integer" }, "total_amount": { - "$ref": "#/components/schemas/Amount" + "allOf": [ + { + "description": "Amount charged on the reader, including any tip. The amount is represented as an integer value altogether with the currency and the minor unit. For example, MXN 10.00 is represented as value 1000 with minor unit of 2.", + "example": { + "currency": "MXN", + "value": 1000 + } + }, + { + "$ref": "#/components/schemas/Amount" + } + ] } }, "required": [ @@ -8923,17 +8941,6 @@ } } }, - "UserType": { - "type": "string", - "description": "Type of the user account.", - "enum": [ - "user", - "managed_user", - "service_account", - "system_account" - ], - "example": "user" - }, "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", @@ -8947,6 +8954,17 @@ "example": {}, "additionalProperties": true }, + "UserType": { + "type": "string", + "description": "Type of the user account.", + "enum": [ + "user", + "managed_user", + "service_account", + "system_account" + ], + "example": "user" + }, "Address": { "externalDocs": { "description": "Address documentation", @@ -8978,7 +8996,15 @@ "example": "10999" }, "country": { - "$ref": "#/components/schemas/CountryCode" + "allOf": [ + { + "description": "The ISO3166-1 Alpha-2 code of the address country.\n", + "example": "DE" + }, + { + "$ref": "#/components/schemas/CountryCode" + } + ] }, "city": { "type": "string", @@ -9507,7 +9533,8 @@ "maxLength": 60 }, "phone_number": { - "$ref": "#/components/schemas/PhoneNumber" + "$ref": "#/components/schemas/PhoneNumber", + "description": "The (mobile) phone number of the individual (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n" }, "relationships": { "type": "array", @@ -9525,16 +9552,19 @@ } }, "ownership": { - "$ref": "#/components/schemas/Ownership" + "$ref": "#/components/schemas/Ownership", + "description": "Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type `owner`.\n" }, "address": { - "$ref": "#/components/schemas/Address" + "$ref": "#/components/schemas/Address", + "description": "The address of the individual." }, "identifiers": { "$ref": "#/components/schemas/PersonalIdentifiers" }, "citizenship": { - "$ref": "#/components/schemas/CountryCode" + "$ref": "#/components/schemas/CountryCode", + "description": "The Alpha-2 ISO code of the country where the Person is a citizen.\n" }, "nationality": { "type": [ @@ -9582,19 +9612,23 @@ "pattern": "^[0-9]{4}$" }, "legal_type": { - "$ref": "#/components/schemas/LegalType" + "$ref": "#/components/schemas/LegalType", + "description": "The category identifying the legal structure of the company or legal entity.\n" }, "address": { - "$ref": "#/components/schemas/Address" + "$ref": "#/components/schemas/Address", + "description": "The company's primary address." }, "trading_address": { - "$ref": "#/components/schemas/Address" + "$ref": "#/components/schemas/Address", + "description": "A trading address is where your suppliers, banks or customers send you correspondence to. Trading address can be different to the company's registered address (`address`).\n" }, "identifiers": { "$ref": "#/components/schemas/CompanyIdentifiers" }, "phone_number": { - "$ref": "#/components/schemas/PhoneNumber" + "$ref": "#/components/schemas/PhoneNumber", + "description": "The company's phone number (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.\n" }, "website": { "description": "HTTP(S) URL of the company's website.\n", @@ -10551,7 +10585,7 @@ "currency": "EUR", "merchant_code": "MH4H92C7", "description": "Purchase", - "valid_until": "2020-02-29T10:56:56+00:00", + "valid_until": "2030-12-31T23:59:59Z", "redirect_url": "https://sumup.com" } }, @@ -10609,7 +10643,7 @@ "currency": "EUR", "description": "Updated purchase", "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802", - "valid_until": "2020-02-29T10:56:56+00:00", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670" } } @@ -10656,7 +10690,7 @@ "amount": { "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.", + "description": "Amount to refund in major units of the transaction's currency, for example `5` for EUR 5.00. It must be greater than zero and cannot exceed the amount eligible for a refund. Eligibility depends on the transaction and country/currency rules. If omitted, the system requests a full refund.", "example": 5 } } @@ -10687,7 +10721,7 @@ "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", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "mandate": { "type": "recurrent", @@ -10724,7 +10758,7 @@ "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", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "redirect_url": "https://mysite.com/completed_purchase", "transactions": [ @@ -10823,7 +10857,7 @@ "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", + "valid_until": "2030-12-31T23:59:59Z", "customer_id": "831ff8d4cd5958ab5670", "transactions": [] } @@ -11143,7 +11177,7 @@ "CheckoutReference": { "name": "checkout_reference", "in": "query", - "description": "Filters the list of checkout resources by the unique reference of the checkout.", + "description": "Filters checkouts by the merchant-defined `checkout_reference` supplied when creating the checkout. This is separate from the SumUp-generated checkout `id`.", "required": false, "schema": { "type": "string", @@ -11154,7 +11188,7 @@ "name": "checkout_id", "in": "path", "required": true, - "description": "Unique identifier of the checkout resource.", + "description": "SumUp-generated `id` returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.", "schema": { "type": "string", "example": "4e425463-3e1b-431d-83fa-1e51c2925e99" @@ -11164,7 +11198,7 @@ "name": "customer_id", "in": "path", "required": true, - "description": "Unique identifier of the saved customer resource.", + "description": "The `customer_id` you supplied when creating the customer.", "schema": { "type": "string", "example": "831ff8d4cd5958ab5670" @@ -11193,7 +11227,7 @@ "OrderFilter": { "name": "order", "in": "query", - "description": "Specifies the order in which the returned results are displayed.", + "description": "Sort direction for the transaction history. Use `ascending` or `descending`; the default is `ascending`.", "schema": { "type": "string", "enum": [ @@ -11206,7 +11240,7 @@ "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.", + "description": "Maximum number of transactions per page. Must be a positive integer. Defaults to `10` when omitted; a page can contain fewer results.", "schema": { "type": "integer", "example": 10 @@ -11215,7 +11249,7 @@ "UsersFilter": { "name": "users[]", "in": "query", - "description": "Filters the returned results by user email.", + "description": "Filters transactions by user email. For multiple values, repeat the query parameter, for example `users[]=first@example.com\u0026users[]=second@example.com`.", "required": false, "example": [ "merchant@example.com" @@ -11234,7 +11268,7 @@ "StatusesFilter": { "name": "statuses[]", "in": "query", - "description": "Filters the returned results by the specified list of final statuses of the transactions.", + "description": "Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example `statuses[]=SUCCESSFUL\u0026statuses[]=REFUNDED`.", "required": false, "schema": { "type": "array", @@ -11332,7 +11366,7 @@ "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).", + "description": "Pagination reference that returns results before the specified reference. Use the value from a returned pagination link rather than constructing it yourself. This parameter takes precedence over `newest_time` when both are provided.", "required": false, "schema": { "type": "string", @@ -11352,13 +11386,13 @@ }, "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": "Authenticate requests with an API key created in the [Dashboard](https://me.sumup.com/settings/api-keys). Send the key in the HTTP `Authorization` header as `Bearer YOUR_API_KEY`. See the [API key guide](https://developer.sumup.com/tools/authorization/api-keys/).", "type": "http", "scheme": "Bearer" }, "oauth2": { "type": "oauth2", - "description": "SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users.\n\nTo integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications).\n\nTo maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.", + "description": "SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users.\n\nRegister an application in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications) to obtain a client ID and client secret. Use the authorization code flow to request a merchant's consent, then send the issued access token in the HTTP `Authorization` header as `Bearer ACCESS_TOKEN`. Request the scopes needed for the endpoints your integration calls.\n\nTo maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.sumup.com/authorize", @@ -11382,27 +11416,6 @@ "payouts.read": "View payouts.", "user.subaccounts": "View and manage the user profile details of your employees." } - }, - "clientCredentials": { - "tokenUrl": "https://api.sumup.com/token", - "scopes": { - "payments": "Make payments by creating and processing checkouts.", - "checkouts.read": "View checkouts.", - "checkouts.write": "Create, process, and deactivate checkouts.", - "transactions.history": "View transactions and transaction history.", - "transactions.read": "View transactions and transaction history.", - "refunds.write": "Refund transactions.", - "receipts.read": "View receipts.", - "user.profile_readonly": "View user profile details.", - "user.profile": "View and manage your user profile.", - "user.app-settings": "View and manage the SumUp mobile application settings.", - "payment_instruments": "Manage customers and their payment instruments.", - "customers.read": "View customers and their payment instruments.", - "customers.write": "Create and manage customers and their payment instruments.", - "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." - } } } } @@ -11660,6 +11673,138 @@ } } } + }, + "roles.created": { + "post": { + "operationId": "RoleCreatedWebhook", + "tags": [ + "Roles" + ], + "summary": "Role created", + "description": "Sent when a role is created for a merchant account.", + "x-object": { + "$ref": "#/components/schemas/Role" + }, + "x-object-type": "role", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + }, + "examples": { + "created": { + "summary": "A role created webhook event.", + "value": { + "id": "evt_role_123", + "type": "roles.created", + "created_at": "2026-05-14T08:30:00Z", + "object": { + "id": "rol_123", + "type": "role", + "url": "https://api.sumup.com/v0.1/merchants/MC0DE/roles/rol_123" + } + } + } + } + } + } + }, + "responses": { + "2XX": { + "description": "Return any 2xx response to acknowledge successful delivery." + } + } + } + }, + "roles.updated": { + "post": { + "operationId": "RoleUpdatedWebhook", + "tags": [ + "Roles" + ], + "summary": "Role updated", + "description": "Sent when a role is updated for a merchant account.", + "x-object": { + "$ref": "#/components/schemas/Role" + }, + "x-object-type": "role", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + }, + "examples": { + "updated": { + "summary": "A role updated webhook event.", + "value": { + "id": "evt_role_123", + "type": "roles.updated", + "created_at": "2026-05-14T08:30:00Z", + "object": { + "id": "rol_123", + "type": "role", + "url": "https://api.sumup.com/v0.1/merchants/MC0DE/roles/rol_123" + } + } + } + } + } + } + }, + "responses": { + "2XX": { + "description": "Return any 2xx response to acknowledge successful delivery." + } + } + } + }, + "roles.deleted": { + "post": { + "operationId": "RoleDeletedWebhook", + "tags": [ + "Roles" + ], + "summary": "Role deleted", + "description": "Sent when a role is deleted for a merchant account.", + "x-object": { + "$ref": "#/components/schemas/Role" + }, + "x-object-type": "role", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Event" + }, + "examples": { + "deleted": { + "summary": "A role deleted webhook event.", + "value": { + "id": "evt_role_123", + "type": "roles.deleted", + "created_at": "2026-05-14T08:30:00Z", + "object": { + "id": "rol_123", + "type": "role", + "url": "https://api.sumup.com/v0.1/merchants/MC0DE/roles/rol_123" + } + } + } + } + } + } + }, + "responses": { + "2XX": { + "description": "Return any 2xx response to acknowledge successful delivery." + } + } + } } } } \ No newline at end of file From fc6d0ec25e63041f3cd040f5d7c9a79444f064e8 Mon Sep 17 00:00:00 2001 From: "sumup-release-bot[bot]" <241716704+sumup-release-bot[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 21:41:13 +0000 Subject: [PATCH 2/2] chore: generate code --- .../sdk/clients/CheckoutsAsyncClient.java | 119 ++++++++++++------ .../sumup/sdk/clients/CheckoutsClient.java | 119 ++++++++++++------ .../sdk/clients/CustomersAsyncClient.java | 44 ++++--- .../sumup/sdk/clients/CustomersClient.java | 44 ++++--- .../sumup/sdk/clients/MembersAsyncClient.java | 35 +++--- .../com/sumup/sdk/clients/MembersClient.java | 35 +++--- .../sdk/clients/MembershipsAsyncClient.java | 27 ++-- .../sumup/sdk/clients/MembershipsClient.java | 27 ++-- .../sumup/sdk/clients/ReadersAsyncClient.java | 8 +- .../com/sumup/sdk/clients/ReadersClient.java | 8 +- .../sdk/clients/ReceiptsAsyncClient.java | 16 ++- .../com/sumup/sdk/clients/ReceiptsClient.java | 16 ++- .../sumup/sdk/clients/RolesAsyncClient.java | 8 +- .../com/sumup/sdk/clients/RolesClient.java | 8 +- .../sdk/clients/TransactionsAsyncClient.java | 56 ++++++--- .../sumup/sdk/clients/TransactionsClient.java | 56 ++++++--- .../sumup/sdk/events/AsyncEventsHandler.java | 36 ++++++ .../sumup/sdk/events/EventNotification.java | 3 + .../com/sumup/sdk/events/EventsHandler.java | 48 +++++++ .../sumup/sdk/events/RoleCreatedEvent.java | 13 ++ .../sumup/sdk/events/RoleDeletedEvent.java | 13 ++ .../sumup/sdk/events/RoleUpdatedEvent.java | 13 ++ .../java/com/sumup/sdk/models/Address.java | 10 +- .../java/com/sumup/sdk/models/BasePerson.java | 39 +++--- .../com/sumup/sdk/models/CardResponse.java | 32 ++++- .../java/com/sumup/sdk/models/CardType.java | 1 + .../java/com/sumup/sdk/models/Checkout.java | 14 ++- .../sdk/models/CheckoutCreateRequest.java | 26 ++-- .../com/sumup/sdk/models/CheckoutSuccess.java | 14 ++- .../sumup/sdk/models/CheckoutSuccess2.java | 14 ++- .../CheckoutSuccessTransactionsItem.java | 54 ++++++-- .../sdk/models/CheckoutTransactionsItem.java | 54 ++++++-- .../java/com/sumup/sdk/models/Company.java | 46 +++---- .../models/CreateApplePaySessionRequest.java | 16 ++- .../java/com/sumup/sdk/models/Currency.java | 1 - .../java/com/sumup/sdk/models/Customer.java | 14 ++- .../java/com/sumup/sdk/models/EntryMode.java | 6 +- src/main/java/com/sumup/sdk/models/Event.java | 24 +++- .../sdk/models/PaymentInstrumentResponse.java | 6 +- .../com/sumup/sdk/models/PaymentType.java | 6 +- .../java/com/sumup/sdk/models/Person.java | 39 +++--- .../com/sumup/sdk/models/PersonalDetails.java | 5 +- .../com/sumup/sdk/models/ProcessCheckout.java | 11 +- .../java/com/sumup/sdk/models/Product.java | 4 +- .../models/ReaderPaymentRequestParams.java | 17 +-- .../ReaderPaymentRequestParamsAffiliate.java | 56 +++++++++ ...ReaderPaymentRequestParamsTotalAmount.java | 60 +++++++++ .../java/com/sumup/sdk/models/Receipt.java | 6 +- .../com/sumup/sdk/models/ReceiptEvent.java | 24 +++- .../sdk/models/RefundTransactionRequest.java | 14 ++- .../com/sumup/sdk/models/TransactionBase.java | 29 +++-- .../sdk/models/TransactionCheckoutInfo.java | 25 +++- .../sumup/sdk/models/TransactionEvent.java | 32 +++-- .../sdk/models/TransactionEventType.java | 8 +- .../com/sumup/sdk/models/TransactionFull.java | 58 ++++++--- .../sumup/sdk/models/TransactionHistory.java | 34 +++-- .../sdk/models/TransactionsHistoryLink.java | 12 +- 57 files changed, 1120 insertions(+), 443 deletions(-) create mode 100644 src/main/java/com/sumup/sdk/events/RoleCreatedEvent.java create mode 100644 src/main/java/com/sumup/sdk/events/RoleDeletedEvent.java create mode 100644 src/main/java/com/sumup/sdk/events/RoleUpdatedEvent.java create mode 100644 src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsAffiliate.java create mode 100644 src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsTotalAmount.java diff --git a/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java index bef0ab9..99e9c00 100644 --- a/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java @@ -43,12 +43,15 @@ public CheckoutsAsyncClient(ApiClient apiClient) { /** * Create a checkout * - *

Creates a new payment checkout resource. The unique `checkout_reference` created by this - * request, is used for further manipulation of the checkout. For 3DS checkouts, add the - * `redirect_url` parameter to your request body schema. To use the [Hosted - * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the - * `hosted_checkout.enabled` to `true`. Follow by processing a checkout to charge the provided - * payment instrument. + *

Creates a payment checkout for the specified merchant, amount, and currency. Supply a + * `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout + * does not charge a payment instrument. Set `hosted_checkout.enabled` to `true` to receive a + * [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL + * where the customer can complete the payment. Use `redirect_url` for redirect-based payment and + * 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback + * URL. Complete the payment through [Hosted + * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the + * [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget). * *

Operation ID: CreateCheckout * @@ -66,12 +69,15 @@ public CompletableFuture create( /** * Create a checkout * - *

Creates a new payment checkout resource. The unique `checkout_reference` created by this - * request, is used for further manipulation of the checkout. For 3DS checkouts, add the - * `redirect_url` parameter to your request body schema. To use the [Hosted - * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the - * `hosted_checkout.enabled` to `true`. Follow by processing a checkout to charge the provided - * payment instrument. + *

Creates a payment checkout for the specified merchant, amount, and currency. Supply a + * `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout + * does not charge a payment instrument. Set `hosted_checkout.enabled` to `true` to receive a + * [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL + * where the customer can complete the payment. Use `redirect_url` for redirect-based payment and + * 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback + * URL. Complete the payment through [Hosted + * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the + * [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget). * *

Operation ID: CreateCheckout * @@ -108,8 +114,9 @@ public CompletableFuture create( * *

Operation ID: CreateApplePaySession * - * @param checkoutId Unique identifier of the checkout resource. - * @param request The data needed to create an apple pay session for a checkout. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. + * @param request Merchant validation details from the Apple Pay session in the payer's browser. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return CompletableFuture resolved with {@code java.util.Map} parsed response. @@ -132,8 +139,9 @@ public CompletableFuture> createApplePaySession( * *

Operation ID: CreateApplePaySession * - * @param checkoutId Unique identifier of the checkout resource. - * @param request The data needed to create an apple pay session for a checkout. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. + * @param request Merchant validation details from the Apple Pay session in the payer's browser. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return CompletableFuture resolved with {@code java.util.Map} parsed response. @@ -166,7 +174,8 @@ public CompletableFuture> createApplePaySession( * *

Operation ID: DeactivateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return CompletableFuture resolved with com.sumup.sdk.models.Checkout parsed response. @@ -185,7 +194,8 @@ public CompletableFuture deactivate(String checko * *

Operation ID: DeactivateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return CompletableFuture resolved with com.sumup.sdk.models.Checkout parsed response. @@ -210,12 +220,14 @@ public CompletableFuture deactivate( /** * Retrieve a checkout * - *

Retrieves an identified checkout resource. Use this request after processing a checkout to - * confirm its status and inform the end user respectively. + *

Retrieves a checkout by its SumUp `checkout_id`. After processing a payment, returning from + * a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current + * `status` before updating your order or displaying the payment outcome to the payer. * *

Operation ID: GetCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return CompletableFuture resolved with com.sumup.sdk.models.CheckoutSuccess parsed response. @@ -229,12 +241,14 @@ public CompletableFuture get(String checko /** * Retrieve a checkout * - *

Retrieves an identified checkout resource. Use this request after processing a checkout to - * confirm its status and inform the end user respectively. + *

Retrieves a checkout by its SumUp `checkout_id`. After processing a payment, returning from + * a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current + * `status` before updating your order or displaying the payment outcome to the payer. * *

Operation ID: GetCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return CompletableFuture resolved with com.sumup.sdk.models.CheckoutSuccess parsed response. @@ -329,7 +343,9 @@ public CompletableFuture> l /** * Get available payment methods * - *

Get payment methods available for the given merchant to use with a checkout. + *

Lists the payment methods available to the merchant for checkout payments. Use the optional + * amount and currency filters to check eligibility for a particular payment before presenting + * payment options to the payer. * *

Operation ID: GetPaymentMethods * @@ -348,7 +364,9 @@ public CompletableFuture> l /** * Get available payment methods * - *

Get payment methods available for the given merchant to use with a checkout. + *

Lists the payment methods available to the merchant for checkout payments. Use the optional + * amount and currency filters to check eligibility for a particular payment before presenting + * payment options to the payer. * *

Operation ID: GetPaymentMethods * @@ -369,7 +387,9 @@ public CompletableFuture> l /** * Get available payment methods * - *

Get payment methods available for the given merchant to use with a checkout. + *

Lists the payment methods available to the merchant for checkout payments. Use the optional + * amount and currency filters to check eligibility for a particular payment before presenting + * payment options to the payer. * *

Operation ID: GetPaymentMethods * @@ -416,12 +436,16 @@ public CompletableFuture> l * requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this * integration if your environment is appropriately PCI DSS compliant. ::: 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. + * resource initiated in the `Create a checkout` endpoint. A processing response can require an + * additional payer action, such as a 3DS challenge or a payment-provider redirect. If `next_step` + * is returned, follow its instructions to continue the payment flow. Retrieve the checkout + * afterwards to confirm its payment status. Acceptance of the processing request does not by + * itself mean the checkout is paid. * *

Operation ID: ProcessCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details of the payment instrument for processing the checkout. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -442,12 +466,16 @@ public CompletableFuture process( * requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this * integration if your environment is appropriately PCI DSS compliant. ::: 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. + * resource initiated in the `Create a checkout` endpoint. A processing response can require an + * additional payer action, such as a 3DS challenge or a payment-provider redirect. If `next_step` + * is returned, follow its instructions to continue the payment flow. Retrieve the checkout + * afterwards to confirm its payment status. Acceptance of the processing request does not by + * itself mean the checkout is paid. * *

Operation ID: ProcessCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details of the payment instrument for processing the checkout. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. @@ -477,11 +505,15 @@ public CompletableFuture process( /** * Update a checkout * - *

Updates an identified checkout resource. + *

Updates the amount, currency, description, reference, expiration, or customer associated + * with an existing checkout. Only the supplied fields are updated. This request changes the + * checkout details; it does not charge a payment instrument. Process the checkout separately to + * attempt a payment. * *

Operation ID: UpdateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details for updating a checkout resource. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -496,11 +528,15 @@ public CompletableFuture update( /** * Update a checkout * - *

Updates an identified checkout resource. + *

Updates the amount, currency, description, reference, expiration, or customer associated + * with an existing checkout. Only the supplied fields are updated. This request changes the + * checkout details; it does not charge a payment instrument. Process the checkout separately to + * attempt a payment. * *

Operation ID: UpdateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details for updating a checkout resource. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. @@ -534,7 +570,8 @@ public static final class ListCheckoutsQueryParams { /** * Sets the checkout_reference query parameter. * - * @param value Filters the list of checkout resources by the unique reference of the checkout. + * @param value Filters checkouts by the merchant-defined `checkout_reference` supplied when + * creating the checkout. This is separate from the SumUp-generated checkout `id`. * @return This ListCheckoutsQueryParams instance. */ public ListCheckoutsQueryParams checkoutReference(String value) { @@ -559,7 +596,8 @@ public static final class GetPaymentMethodsQueryParams { /** * Sets the amount query parameter. * - * @param value The amount for which the payment methods should be eligible, in major units. + * @param value Payment amount in major units, for example `9.99` for EUR 9.99. When filtering + * by `amount`, also provide `currency`. * @return This GetPaymentMethodsQueryParams instance. */ public GetPaymentMethodsQueryParams amount(Double value) { @@ -570,7 +608,8 @@ public GetPaymentMethodsQueryParams amount(Double value) { /** * Sets the currency query parameter. * - * @param value The currency for which the payment methods should be eligible. + * @param value Three-letter ISO 4217 currency code for which the payment methods should be + * eligible, for example `EUR`. * @return This GetPaymentMethodsQueryParams instance. */ public GetPaymentMethodsQueryParams currency(String value) { diff --git a/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java b/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java index 8f66982..8c40d2d 100644 --- a/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java +++ b/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java @@ -42,12 +42,15 @@ public CheckoutsClient(ApiClient apiClient) { /** * Create a checkout * - *

Creates a new payment checkout resource. The unique `checkout_reference` created by this - * request, is used for further manipulation of the checkout. For 3DS checkouts, add the - * `redirect_url` parameter to your request body schema. To use the [Hosted - * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the - * `hosted_checkout.enabled` to `true`. Follow by processing a checkout to charge the provided - * payment instrument. + *

Creates a payment checkout for the specified merchant, amount, and currency. Supply a + * `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout + * does not charge a payment instrument. Set `hosted_checkout.enabled` to `true` to receive a + * [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL + * where the customer can complete the payment. Use `redirect_url` for redirect-based payment and + * 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback + * URL. Complete the payment through [Hosted + * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the + * [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget). * *

Operation ID: CreateCheckout * @@ -65,12 +68,15 @@ public com.sumup.sdk.models.Checkout create(com.sumup.sdk.models.CheckoutCreateR /** * Create a checkout * - *

Creates a new payment checkout resource. The unique `checkout_reference` created by this - * request, is used for further manipulation of the checkout. For 3DS checkouts, add the - * `redirect_url` parameter to your request body schema. To use the [Hosted - * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the - * `hosted_checkout.enabled` to `true`. Follow by processing a checkout to charge the provided - * payment instrument. + *

Creates a payment checkout for the specified merchant, amount, and currency. Supply a + * `checkout_reference` to identify the payment attempt in your own systems. Creating a checkout + * does not charge a payment instrument. Set `hosted_checkout.enabled` to `true` to receive a + * [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) URL + * where the customer can complete the payment. Use `redirect_url` for redirect-based payment and + * 3DS flows. If `return_url` is provided, SumUp sends processing updates to that backend callback + * URL. Complete the payment through [Hosted + * Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) or the + * [Payment Widget](https://developer.sumup.com/online-payments/checkouts/card-widget). * *

Operation ID: CreateCheckout * @@ -107,8 +113,9 @@ public com.sumup.sdk.models.Checkout create( * *

Operation ID: CreateApplePaySession * - * @param checkoutId Unique identifier of the checkout resource. - * @param request The data needed to create an apple pay session for a checkout. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. + * @param request Merchant validation details from the Apple Pay session in the payer's browser. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return {@code java.util.Map} parsed response. @@ -131,8 +138,9 @@ public java.util.Map createApplePaySession( * *

Operation ID: CreateApplePaySession * - * @param checkoutId Unique identifier of the checkout resource. - * @param request The data needed to create an apple pay session for a checkout. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. + * @param request Merchant validation details from the Apple Pay session in the payer's browser. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return {@code java.util.Map} parsed response. @@ -165,7 +173,8 @@ public java.util.Map createApplePaySession( * *

Operation ID: DeactivateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return com.sumup.sdk.models.Checkout parsed response. @@ -183,7 +192,8 @@ public com.sumup.sdk.models.Checkout deactivate(String checkoutId) throws ApiExc * *

Operation ID: DeactivateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return com.sumup.sdk.models.Checkout parsed response. @@ -208,12 +218,14 @@ public com.sumup.sdk.models.Checkout deactivate(String checkoutId, RequestOption /** * Retrieve a checkout * - *

Retrieves an identified checkout resource. Use this request after processing a checkout to - * confirm its status and inform the end user respectively. + *

Retrieves a checkout by its SumUp `checkout_id`. After processing a payment, returning from + * a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current + * `status` before updating your order or displaying the payment outcome to the payer. * *

Operation ID: GetCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return com.sumup.sdk.models.CheckoutSuccess parsed response. @@ -226,12 +238,14 @@ public com.sumup.sdk.models.CheckoutSuccess get(String checkoutId) throws ApiExc /** * Retrieve a checkout * - *

Retrieves an identified checkout resource. Use this request after processing a checkout to - * confirm its status and inform the end user respectively. + *

Retrieves a checkout by its SumUp `checkout_id`. After processing a payment, returning from + * a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current + * `status` before updating your order or displaying the payment outcome to the payer. * *

Operation ID: GetCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return com.sumup.sdk.models.CheckoutSuccess parsed response. @@ -322,7 +336,9 @@ public java.util.List list( /** * Get available payment methods * - *

Get payment methods available for the given merchant to use with a checkout. + *

Lists the payment methods available to the merchant for checkout payments. Use the optional + * amount and currency filters to check eligibility for a particular payment before presenting + * payment options to the payer. * *

Operation ID: GetPaymentMethods * @@ -340,7 +356,9 @@ public com.sumup.sdk.models.GetPaymentMethodsResponse listAvailablePaymentMethod /** * Get available payment methods * - *

Get payment methods available for the given merchant to use with a checkout. + *

Lists the payment methods available to the merchant for checkout payments. Use the optional + * amount and currency filters to check eligibility for a particular payment before presenting + * payment options to the payer. * *

Operation ID: GetPaymentMethods * @@ -359,7 +377,9 @@ public com.sumup.sdk.models.GetPaymentMethodsResponse listAvailablePaymentMethod /** * Get available payment methods * - *

Get payment methods available for the given merchant to use with a checkout. + *

Lists the payment methods available to the merchant for checkout payments. Use the optional + * amount and currency filters to check eligibility for a particular payment before presenting + * payment options to the payer. * *

Operation ID: GetPaymentMethods * @@ -404,12 +424,16 @@ public com.sumup.sdk.models.GetPaymentMethodsResponse listAvailablePaymentMethod * requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this * integration if your environment is appropriately PCI DSS compliant. ::: 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. + * resource initiated in the `Create a checkout` endpoint. A processing response can require an + * additional payer action, such as a 3DS challenge or a payment-provider redirect. If `next_step` + * is returned, follow its instructions to continue the payment flow. Retrieve the checkout + * afterwards to confirm its payment status. Acceptance of the processing request does not by + * itself mean the checkout is paid. * *

Operation ID: ProcessCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details of the payment instrument for processing the checkout. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -430,12 +454,16 @@ public com.sumup.sdk.models.CheckoutSuccess2 process( * requirements](https://www.pcisecuritystandards.org/document_library/). You should only use this * integration if your environment is appropriately PCI DSS compliant. ::: 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. + * resource initiated in the `Create a checkout` endpoint. A processing response can require an + * additional payer action, such as a 3DS challenge or a payment-provider redirect. If `next_step` + * is returned, follow its instructions to continue the payment flow. Retrieve the checkout + * afterwards to confirm its payment status. Acceptance of the processing request does not by + * itself mean the checkout is paid. * *

Operation ID: ProcessCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details of the payment instrument for processing the checkout. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. @@ -465,11 +493,15 @@ public com.sumup.sdk.models.CheckoutSuccess2 process( /** * Update a checkout * - *

Updates an identified checkout resource. + *

Updates the amount, currency, description, reference, expiration, or customer associated + * with an existing checkout. Only the supplied fields are updated. This request changes the + * checkout details; it does not charge a payment instrument. Process the checkout separately to + * attempt a payment. * *

Operation ID: UpdateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details for updating a checkout resource. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -484,11 +516,15 @@ public com.sumup.sdk.models.Checkout update( /** * Update a checkout * - *

Updates an identified checkout resource. + *

Updates the amount, currency, description, reference, expiration, or customer associated + * with an existing checkout. Only the supplied fields are updated. This request changes the + * checkout details; it does not charge a payment instrument. Process the checkout separately to + * attempt a payment. * *

Operation ID: UpdateCheckout * - * @param checkoutId Unique identifier of the checkout resource. + * @param checkoutId SumUp-generated `id` returned when creating a checkout. Use this value to + * retrieve, update, process, or deactivate the checkout. * @param request Details for updating a checkout resource. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. @@ -522,7 +558,8 @@ public static final class ListCheckoutsQueryParams { /** * Sets the checkout_reference query parameter. * - * @param value Filters the list of checkout resources by the unique reference of the checkout. + * @param value Filters checkouts by the merchant-defined `checkout_reference` supplied when + * creating the checkout. This is separate from the SumUp-generated checkout `id`. * @return This ListCheckoutsQueryParams instance. */ public ListCheckoutsQueryParams checkoutReference(String value) { @@ -547,7 +584,8 @@ public static final class GetPaymentMethodsQueryParams { /** * Sets the amount query parameter. * - * @param value The amount for which the payment methods should be eligible, in major units. + * @param value Payment amount in major units, for example `9.99` for EUR 9.99. When filtering + * by `amount`, also provide `currency`. * @return This GetPaymentMethodsQueryParams instance. */ public GetPaymentMethodsQueryParams amount(Double value) { @@ -558,7 +596,8 @@ public GetPaymentMethodsQueryParams amount(Double value) { /** * Sets the currency query parameter. * - * @param value The currency for which the payment methods should be eligible. + * @param value Three-letter ISO 4217 currency code for which the payment methods should be + * eligible, for example `EUR`. * @return This GetPaymentMethodsQueryParams instance. */ public GetPaymentMethodsQueryParams currency(String value) { diff --git a/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java index 667da57..3287559 100644 --- a/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java @@ -12,10 +12,14 @@ /** * Client for the "Customers" API group. * - *

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. + *

Customers represent payers in your integration. Create a customer with your own `customer_id` + * to associate their personal details and saved payment instruments with your business records. To + * save a card, create a checkout for that customer with `purpose = SETUP_RECURRING_PAYMENT`, then + * process it with the payer's consent and mandate details. See the [tokenization + * guide](https://developer.sumup.com/online-payments/guides/tokenization-with-payment-sdk/). Use + * the Customers endpoints to create, retrieve, or update customer details and to list or deactivate + * saved payment instruments. For subsequent payments, process a new checkout with the saved + * instrument's `token` and its associated `customer_id`. */ public final class CustomersAsyncClient { private final ApiClient apiClient; @@ -32,8 +36,9 @@ public CustomersAsyncClient(ApiClient apiClient) { /** * Create a customer * - *

Creates a new saved customer resource which you can later manipulate and save payment - * instruments to. + *

Creates a customer using the `customer_id` you supply. Choose an identifier that maps to the + * payer in your own system and reuse it when retrieving the customer or associating checkouts and + * saved payment instruments with them. * *

Operation ID: CreateCustomer * @@ -51,8 +56,9 @@ public CompletableFuture create( /** * Create a customer * - *

Creates a new saved customer resource which you can later manipulate and save payment - * instruments to. + *

Creates a customer using the `customer_id` you supply. Choose an identifier that maps to the + * payer in your own system and reuse it when retrieving the customer or associating checkouts and + * saved payment instruments with them. * *

Operation ID: CreateCustomer * @@ -84,7 +90,7 @@ public CompletableFuture create( * *

Operation ID: DeactivatePaymentInstrument * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param token Unique token identifying the card saved as a payment instrument resource. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -103,7 +109,7 @@ public CompletableFuture deactivatePaymentInstrument(String customerId, St * *

Operation ID: DeactivatePaymentInstrument * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param token Unique token identifying the card saved as a payment instrument resource. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. @@ -125,12 +131,11 @@ public CompletableFuture deactivatePaymentInstrument( /** * Retrieve a customer * - *

Retrieves an identified saved customer resource through the unique `customer_id` parameter, - * generated upon customer creation. + *

Retrieves a saved customer using the `customer_id` you supplied when creating the customer. * *

Operation ID: GetCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return CompletableFuture resolved with com.sumup.sdk.models.Customer parsed response. @@ -144,12 +149,11 @@ public CompletableFuture get(String customerId) /** * Retrieve a customer * - *

Retrieves an identified saved customer resource through the unique `customer_id` parameter, - * generated upon customer creation. + *

Retrieves a saved customer using the `customer_id` you supplied when creating the customer. * *

Operation ID: GetCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return CompletableFuture resolved with com.sumup.sdk.models.Customer parsed response. @@ -178,7 +182,7 @@ public CompletableFuture get( * *

Operation ID: ListPaymentInstruments * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return CompletableFuture resolved with {@code @@ -197,7 +201,7 @@ public CompletableFuture get( * *

Operation ID: ListPaymentInstruments * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return CompletableFuture resolved with {@code @@ -229,7 +233,7 @@ public CompletableFuture get( * *

Operation ID: UpdateCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param request Customer fields to update. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -250,7 +254,7 @@ public CompletableFuture update( * *

Operation ID: UpdateCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param request Customer fields to update. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. diff --git a/src/main/java/com/sumup/sdk/clients/CustomersClient.java b/src/main/java/com/sumup/sdk/clients/CustomersClient.java index 9702654..003b675 100644 --- a/src/main/java/com/sumup/sdk/clients/CustomersClient.java +++ b/src/main/java/com/sumup/sdk/clients/CustomersClient.java @@ -11,10 +11,14 @@ /** * Client for the "Customers" API group. * - *

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. + *

Customers represent payers in your integration. Create a customer with your own `customer_id` + * to associate their personal details and saved payment instruments with your business records. To + * save a card, create a checkout for that customer with `purpose = SETUP_RECURRING_PAYMENT`, then + * process it with the payer's consent and mandate details. See the [tokenization + * guide](https://developer.sumup.com/online-payments/guides/tokenization-with-payment-sdk/). Use + * the Customers endpoints to create, retrieve, or update customer details and to list or deactivate + * saved payment instruments. For subsequent payments, process a new checkout with the saved + * instrument's `token` and its associated `customer_id`. */ public final class CustomersClient { private final ApiClient apiClient; @@ -31,8 +35,9 @@ public CustomersClient(ApiClient apiClient) { /** * Create a customer * - *

Creates a new saved customer resource which you can later manipulate and save payment - * instruments to. + *

Creates a customer using the `customer_id` you supply. Choose an identifier that maps to the + * payer in your own system and reuse it when retrieving the customer or associating checkouts and + * saved payment instruments with them. * *

Operation ID: CreateCustomer * @@ -50,8 +55,9 @@ public com.sumup.sdk.models.Customer create(com.sumup.sdk.models.Customer reques /** * Create a customer * - *

Creates a new saved customer resource which you can later manipulate and save payment - * instruments to. + *

Creates a customer using the `customer_id` you supply. Choose an identifier that maps to the + * payer in your own system and reuse it when retrieving the customer or associating checkouts and + * saved payment instruments with them. * *

Operation ID: CreateCustomer * @@ -83,7 +89,7 @@ public com.sumup.sdk.models.Customer create( * *

Operation ID: DeactivatePaymentInstrument * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param token Unique token identifying the card saved as a payment instrument resource. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -100,7 +106,7 @@ public void deactivatePaymentInstrument(String customerId, String token) throws * *

Operation ID: DeactivatePaymentInstrument * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param token Unique token identifying the card saved as a payment instrument resource. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. @@ -120,12 +126,11 @@ public void deactivatePaymentInstrument( /** * Retrieve a customer * - *

Retrieves an identified saved customer resource through the unique `customer_id` parameter, - * generated upon customer creation. + *

Retrieves a saved customer using the `customer_id` you supplied when creating the customer. * *

Operation ID: GetCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return com.sumup.sdk.models.Customer parsed response. @@ -138,12 +143,11 @@ public com.sumup.sdk.models.Customer get(String customerId) throws ApiException /** * Retrieve a customer * - *

Retrieves an identified saved customer resource through the unique `customer_id` parameter, - * generated upon customer creation. + *

Retrieves a saved customer using the `customer_id` you supplied when creating the customer. * *

Operation ID: GetCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return com.sumup.sdk.models.Customer parsed response. @@ -172,7 +176,7 @@ public com.sumup.sdk.models.Customer get(String customerId, RequestOptions reque * *

Operation ID: ListPaymentInstruments * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. * @return {@code java.util.List} parsed response. @@ -190,7 +194,7 @@ public java.util.List listPaymen * *

Operation ID: ListPaymentInstruments * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. * @return {@code java.util.List} parsed response. @@ -221,7 +225,7 @@ public java.util.List listPaymen * *

Operation ID: UpdateCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param request Customer fields to update. *

Call the overload that accepts RequestOptions to customize headers, authorization, or * request timeout. @@ -242,7 +246,7 @@ public com.sumup.sdk.models.Customer update( * *

Operation ID: UpdateCustomer * - * @param customerId Unique identifier of the saved customer resource. + * @param customerId The `customer_id` you supplied when creating the customer. * @param request Customer fields to update. * @param requestOptions Request-specific overrides (headers, authorization, or timeout). Pass * {@code null} to use client defaults. diff --git a/src/main/java/com/sumup/sdk/clients/MembersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/MembersAsyncClient.java index 710ef1b..2dfa09e 100644 --- a/src/main/java/com/sumup/sdk/clients/MembersAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/MembersAsyncClient.java @@ -32,7 +32,10 @@ public MembersAsyncClient(ApiClient apiClient) { /** * Create a member * - *

Create a merchant member. + *

Adds a member to the merchant account with the specified roles. By default, sends an + * invitation email to the provided address. The recipient must accept the invitation to join the + * account. When `is_managed_user` is `true`, creates a managed user with the provided password + * and optional nickname and assigns the roles directly, without sending an invitation. * *

Operation ID: CreateMerchantMember * @@ -52,7 +55,10 @@ public CompletableFuture create( /** * Create a member * - *

Create a merchant member. + *

Adds a member to the merchant account with the specified roles. By default, sends an + * invitation email to the provided address. The recipient must accept the invitation to join the + * account. When `is_managed_user` is `true`, creates a managed user with the provided password + * and optional nickname and assigns the roles directly, without sending an invitation. * *

Operation ID: CreateMerchantMember * @@ -266,7 +272,11 @@ public CompletableFuture list( /** * Update a member * - *

Update the merchant member. + *

Updates a merchant member and returns the updated member. Providing `roles` replaces the + * member's assigned roles and can grant or revoke access. Providing `metadata` replaces the + * entire metadata object. For managed users, `user.nickname` changes the display name and + * `user.password` replaces the password. Updating the password also enables the managed user + * account. * *

Operation ID: UpdateMerchantMember * @@ -289,7 +299,11 @@ public CompletableFuture update( /** * Update a member * - *

Update the merchant member. + *

Updates a merchant member and returns the updated member. Providing `roles` replaces the + * member's assigned roles and can grant or revoke access. Providing `metadata` replaces the + * entire metadata object. For managed users, `user.nickname` changes the display name and + * `user.password` replaces the password. Updating the password also enables the managed user + * account. * *

Operation ID: UpdateMerchantMember * @@ -407,19 +421,6 @@ public ListMerchantMembersQueryParams userId(java.util.UUID value) { return this; } - /** - * Sets the user.type query parameter. - * - * @param value Filter the returned members by user type. Repeat this parameter to include - * multiple user types. - * @return This ListMerchantMembersQueryParams instance. - */ - public ListMerchantMembersQueryParams userType( - java.util.List value) { - this.values.put("user.type", Objects.requireNonNull(value, "userType")); - return this; - } - /** * Converts query parameters to a map understood by ApiClient. * diff --git a/src/main/java/com/sumup/sdk/clients/MembersClient.java b/src/main/java/com/sumup/sdk/clients/MembersClient.java index 45b871c..372495f 100644 --- a/src/main/java/com/sumup/sdk/clients/MembersClient.java +++ b/src/main/java/com/sumup/sdk/clients/MembersClient.java @@ -31,7 +31,10 @@ public MembersClient(ApiClient apiClient) { /** * Create a member * - *

Create a merchant member. + *

Adds a member to the merchant account with the specified roles. By default, sends an + * invitation email to the provided address. The recipient must accept the invitation to join the + * account. When `is_managed_user` is `true`, creates a managed user with the provided password + * and optional nickname and assigns the roles directly, without sending an invitation. * *

Operation ID: CreateMerchantMember * @@ -51,7 +54,10 @@ public com.sumup.sdk.models.Member create( /** * Create a member * - *

Create a merchant member. + *

Adds a member to the merchant account with the specified roles. By default, sends an + * invitation email to the provided address. The recipient must accept the invitation to join the + * account. When `is_managed_user` is `true`, creates a managed user with the provided password + * and optional nickname and assigns the roles directly, without sending an invitation. * *

Operation ID: CreateMerchantMember * @@ -258,7 +264,11 @@ public com.sumup.sdk.models.ListMerchantMembersResponse list( /** * Update a member * - *

Update the merchant member. + *

Updates a merchant member and returns the updated member. Providing `roles` replaces the + * member's assigned roles and can grant or revoke access. Providing `metadata` replaces the + * entire metadata object. For managed users, `user.nickname` changes the display name and + * `user.password` replaces the password. Updating the password also enables the managed user + * account. * *

Operation ID: UpdateMerchantMember * @@ -281,7 +291,11 @@ public com.sumup.sdk.models.Member update( /** * Update a member * - *

Update the merchant member. + *

Updates a merchant member and returns the updated member. Providing `roles` replaces the + * member's assigned roles and can grant or revoke access. Providing `metadata` replaces the + * entire metadata object. For managed users, `user.nickname` changes the display name and + * `user.password` replaces the password. Updating the password also enables the managed user + * account. * *

Operation ID: UpdateMerchantMember * @@ -399,19 +413,6 @@ public ListMerchantMembersQueryParams userId(java.util.UUID value) { return this; } - /** - * Sets the user.type query parameter. - * - * @param value Filter the returned members by user type. Repeat this parameter to include - * multiple user types. - * @return This ListMerchantMembersQueryParams instance. - */ - public ListMerchantMembersQueryParams userType( - java.util.List value) { - this.values.put("user.type", Objects.requireNonNull(value, "userType")); - return this; - } - /** * Converts query parameters to a map understood by ApiClient. * diff --git a/src/main/java/com/sumup/sdk/clients/MembershipsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/MembershipsAsyncClient.java index 3fbf31d..759c07c 100644 --- a/src/main/java/com/sumup/sdk/clients/MembershipsAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/MembershipsAsyncClient.java @@ -150,6 +150,17 @@ public ListMembershipsQueryParams resourceAttributesSandbox(Boolean value) { return this; } + /** + * Sets the resource.id query parameter. + * + * @param value Filter memberships by the ID of the resource the membership is in. + * @return This ListMembershipsQueryParams instance. + */ + public ListMembershipsQueryParams resourceId(String value) { + this.values.put("resource.id", Objects.requireNonNull(value, "resourceId")); + return this; + } + /** * Sets the resource.name query parameter. * @@ -164,9 +175,10 @@ public ListMembershipsQueryParams resourceName(String value) { /** * Sets the resource.parent.id query parameter. * - * @param value 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. + * @param value Filter memberships by the parent of the resource the membership is in. Omit both + * `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering + * by parent, both parameters must be present. To select resources without a parent, set + * each parameter to an empty value. Otherwise, both parameters must identify a parent. * @return This ListMembershipsQueryParams instance. */ public ListMembershipsQueryParams resourceParentId(String value) { @@ -177,12 +189,13 @@ public ListMembershipsQueryParams resourceParentId(String value) { /** * Sets the resource.parent.type query parameter. * - * @param value 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. + * @param value Filter memberships by the parent of the resource the membership is in. Omit both + * `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering + * by parent, both parameters must be present. To select resources without a parent, set + * each parameter to an empty value. Otherwise, both parameters must identify a parent. * @return This ListMembershipsQueryParams instance. */ - public ListMembershipsQueryParams resourceParentType(java.util.Map value) { + public ListMembershipsQueryParams resourceParentType(String value) { this.values.put("resource.parent.type", Objects.requireNonNull(value, "resourceParentType")); return this; } diff --git a/src/main/java/com/sumup/sdk/clients/MembershipsClient.java b/src/main/java/com/sumup/sdk/clients/MembershipsClient.java index 813b2a3..d7775fb 100644 --- a/src/main/java/com/sumup/sdk/clients/MembershipsClient.java +++ b/src/main/java/com/sumup/sdk/clients/MembershipsClient.java @@ -145,6 +145,17 @@ public ListMembershipsQueryParams resourceAttributesSandbox(Boolean value) { return this; } + /** + * Sets the resource.id query parameter. + * + * @param value Filter memberships by the ID of the resource the membership is in. + * @return This ListMembershipsQueryParams instance. + */ + public ListMembershipsQueryParams resourceId(String value) { + this.values.put("resource.id", Objects.requireNonNull(value, "resourceId")); + return this; + } + /** * Sets the resource.name query parameter. * @@ -159,9 +170,10 @@ public ListMembershipsQueryParams resourceName(String value) { /** * Sets the resource.parent.id query parameter. * - * @param value 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. + * @param value Filter memberships by the parent of the resource the membership is in. Omit both + * `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering + * by parent, both parameters must be present. To select resources without a parent, set + * each parameter to an empty value. Otherwise, both parameters must identify a parent. * @return This ListMembershipsQueryParams instance. */ public ListMembershipsQueryParams resourceParentId(String value) { @@ -172,12 +184,13 @@ public ListMembershipsQueryParams resourceParentId(String value) { /** * Sets the resource.parent.type query parameter. * - * @param value 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. + * @param value Filter memberships by the parent of the resource the membership is in. Omit both + * `resource.parent.id` and `resource.parent.type` to skip parent filtering. When filtering + * by parent, both parameters must be present. To select resources without a parent, set + * each parameter to an empty value. Otherwise, both parameters must identify a parent. * @return This ListMembershipsQueryParams instance. */ - public ListMembershipsQueryParams resourceParentType(java.util.Map value) { + public ListMembershipsQueryParams resourceParentType(String value) { this.values.put("resource.parent.type", Objects.requireNonNull(value, "resourceParentType")); return this; } diff --git a/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java index 7073934..bdd1764 100644 --- a/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/ReadersAsyncClient.java @@ -605,7 +605,9 @@ public CompletableFuture terminateCheckout( /** * Update a Reader * - *

Update a Reader. + *

Updates a reader's name or metadata and returns the updated reader. Providing `metadata` + * replaces the entire metadata object; include all entries that should be retained. Omitted + * fields remain unchanged. * *

Operation ID: UpdateReader * @@ -626,7 +628,9 @@ public CompletableFuture update( /** * Update a Reader * - *

Update a Reader. + *

Updates a reader's name or metadata and returns the updated reader. Providing `metadata` + * replaces the entire metadata object; include all entries that should be retained. Omitted + * fields remain unchanged. * *

Operation ID: UpdateReader * diff --git a/src/main/java/com/sumup/sdk/clients/ReadersClient.java b/src/main/java/com/sumup/sdk/clients/ReadersClient.java index d3af542..983f09b 100644 --- a/src/main/java/com/sumup/sdk/clients/ReadersClient.java +++ b/src/main/java/com/sumup/sdk/clients/ReadersClient.java @@ -588,7 +588,9 @@ public void terminateCheckout( /** * Update a Reader * - *

Update a Reader. + *

Updates a reader's name or metadata and returns the updated reader. Providing `metadata` + * replaces the entire metadata object; include all entries that should be retained. Omitted + * fields remain unchanged. * *

Operation ID: UpdateReader * @@ -609,7 +611,9 @@ public com.sumup.sdk.models.Reader update( /** * Update a Reader * - *

Update a Reader. + *

Updates a reader's name or metadata and returns the updated reader. Providing `metadata` + * replaces the entire metadata object; include all entries that should be retained. Omitted + * fields remain unchanged. * *

Operation ID: UpdateReader * diff --git a/src/main/java/com/sumup/sdk/clients/ReceiptsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/ReceiptsAsyncClient.java index 79bab29..0453071 100644 --- a/src/main/java/com/sumup/sdk/clients/ReceiptsAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/ReceiptsAsyncClient.java @@ -14,7 +14,9 @@ /** * Client for the "Receipts" API group. * - *

The Receipts model obtains receipt-like details for specific transactions. + *

Retrieve structured receipt data for a transaction, including payment, merchant, and acquirer + * details. Use this data to display a receipt in your application. The response is JSON, rather + * than a rendered receipt document. */ public final class ReceiptsAsyncClient { private final ApiClient apiClient; @@ -31,7 +33,9 @@ public ReceiptsAsyncClient(ApiClient apiClient) { /** * Retrieve receipt details * - *

Retrieves receipt specific data for a transaction. + *

Retrieves structured receipt data for a transaction belonging to the merchant specified by + * `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide + * `tx_event_id` to include a specific transaction event, such as a refund, on the receipt. * *

Operation ID: GetReceipt * @@ -50,7 +54,9 @@ public CompletableFuture get(String transactionId, /** * Retrieve receipt details * - *

Retrieves receipt specific data for a transaction. + *

Retrieves structured receipt data for a transaction belonging to the merchant specified by + * `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide + * `tx_event_id` to include a specific transaction event, such as a refund, on the receipt. * *

Operation ID: GetReceipt * @@ -70,7 +76,9 @@ public CompletableFuture get( /** * Retrieve receipt details * - *

Retrieves receipt specific data for a transaction. + *

Retrieves structured receipt data for a transaction belonging to the merchant specified by + * `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide + * `tx_event_id` to include a specific transaction event, such as a refund, on the receipt. * *

Operation ID: GetReceipt * diff --git a/src/main/java/com/sumup/sdk/clients/ReceiptsClient.java b/src/main/java/com/sumup/sdk/clients/ReceiptsClient.java index da15c69..32a3fbd 100644 --- a/src/main/java/com/sumup/sdk/clients/ReceiptsClient.java +++ b/src/main/java/com/sumup/sdk/clients/ReceiptsClient.java @@ -13,7 +13,9 @@ /** * Client for the "Receipts" API group. * - *

The Receipts model obtains receipt-like details for specific transactions. + *

Retrieve structured receipt data for a transaction, including payment, merchant, and acquirer + * details. Use this data to display a receipt in your application. The response is JSON, rather + * than a rendered receipt document. */ public final class ReceiptsClient { private final ApiClient apiClient; @@ -30,7 +32,9 @@ public ReceiptsClient(ApiClient apiClient) { /** * Retrieve receipt details * - *

Retrieves receipt specific data for a transaction. + *

Retrieves structured receipt data for a transaction belonging to the merchant specified by + * `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide + * `tx_event_id` to include a specific transaction event, such as a refund, on the receipt. * *

Operation ID: GetReceipt * @@ -48,7 +52,9 @@ public com.sumup.sdk.models.Receipt get(String transactionId, String mid) throws /** * Retrieve receipt details * - *

Retrieves receipt specific data for a transaction. + *

Retrieves structured receipt data for a transaction belonging to the merchant specified by + * `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide + * `tx_event_id` to include a specific transaction event, such as a refund, on the receipt. * *

Operation ID: GetReceipt * @@ -68,7 +74,9 @@ public com.sumup.sdk.models.Receipt get( /** * Retrieve receipt details * - *

Retrieves receipt specific data for a transaction. + *

Retrieves structured receipt data for a transaction belonging to the merchant specified by + * `mid`. The path accepts either the SumUp transaction ID or transaction code. Provide + * `tx_event_id` to include a specific transaction event, such as a refund, on the receipt. * *

Operation ID: GetReceipt * diff --git a/src/main/java/com/sumup/sdk/clients/RolesAsyncClient.java b/src/main/java/com/sumup/sdk/clients/RolesAsyncClient.java index 151408c..dee9c44 100644 --- a/src/main/java/com/sumup/sdk/clients/RolesAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/RolesAsyncClient.java @@ -239,7 +239,9 @@ public CompletableFuture list( /** * Update a role * - *

Update a custom role. + *

Updates a custom role's name, description, or permissions and returns the updated role. + * Providing `permissions` replaces the role's permission list and changes the access granted to + * members assigned to that role. Omitted fields remain unchanged. * *

Operation ID: UpdateMerchantRole * @@ -260,7 +262,9 @@ public CompletableFuture update( /** * Update a role * - *

Update a custom role. + *

Updates a custom role's name, description, or permissions and returns the updated role. + * Providing `permissions` replaces the role's permission list and changes the access granted to + * members assigned to that role. Omitted fields remain unchanged. * *

Operation ID: UpdateMerchantRole * diff --git a/src/main/java/com/sumup/sdk/clients/RolesClient.java b/src/main/java/com/sumup/sdk/clients/RolesClient.java index a3fb557..4da6f66 100644 --- a/src/main/java/com/sumup/sdk/clients/RolesClient.java +++ b/src/main/java/com/sumup/sdk/clients/RolesClient.java @@ -232,7 +232,9 @@ public com.sumup.sdk.models.ListMerchantRolesResponse list( /** * Update a role * - *

Update a custom role. + *

Updates a custom role's name, description, or permissions and returns the updated role. + * Providing `permissions` replaces the role's permission list and changes the access granted to + * members assigned to that role. Omitted fields remain unchanged. * *

Operation ID: UpdateMerchantRole * @@ -253,7 +255,9 @@ public com.sumup.sdk.models.Role update( /** * Update a role * - *

Update a custom role. + *

Updates a custom role's name, description, or permissions and returns the updated role. + * Providing `permissions` replaces the role's permission list and changes the access granted to + * members assigned to that role. Omitted fields remain unchanged. * *

Operation ID: UpdateMerchantRole * diff --git a/src/main/java/com/sumup/sdk/clients/TransactionsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/TransactionsAsyncClient.java index d1949e2..8c2a16c 100644 --- a/src/main/java/com/sumup/sdk/clients/TransactionsAsyncClient.java +++ b/src/main/java/com/sumup/sdk/clients/TransactionsAsyncClient.java @@ -128,7 +128,11 @@ public CompletableFuture get( /** * List transactions * - *

Lists detailed history of all transactions associated with the merchant profile. + *

Lists transaction history for the merchant, with optional filters for payment type, status, + * and date range. The response contains the current page in `items` and pagination query strings + * in `links`. To request another page, use the query string from the relevant link's `href` with + * this history endpoint. Use `changes_since` when retrieving transactions modified since a + * previous synchronization, including transactions created earlier whose status has changed. * *

Operation ID: ListTransactionsV2.1 * @@ -147,7 +151,11 @@ public CompletableFuture list( /** * List transactions * - *

Lists detailed history of all transactions associated with the merchant profile. + *

Lists transaction history for the merchant, with optional filters for payment type, status, + * and date range. The response contains the current page in `items` and pagination query strings + * in `links`. To request another page, use the query string from the relevant link's `href` with + * this history endpoint. Use `changes_since` when retrieving transactions modified since a + * previous synchronization, including transactions created earlier whose status has changed. * *

Operation ID: ListTransactionsV2.1 * @@ -167,7 +175,11 @@ public CompletableFuture list( /** * List transactions * - *

Lists detailed history of all transactions associated with the merchant profile. + *

Lists transaction history for the merchant, with optional filters for payment type, status, + * and date range. The response contains the current page in `items` and pagination query strings + * in `links`. To request another page, use the query string from the relevant link's `href` with + * this history endpoint. Use `changes_since` when retrieving transactions modified since a + * previous synchronization, including transactions created earlier whose status has changed. * *

Operation ID: ListTransactionsV2.1 * @@ -207,7 +219,11 @@ public CompletableFuture list( /** * Refund a transaction * - *

Refunds an identified transaction either in full or partially. + *

Refunds a transaction identified by its SumUp transaction ID. Omit the request body to + * request a full refund, or provide `amount` for a partial refund in the transaction's currency. + * Retrieve the transaction afterwards to inspect its refunded amount and refund events. The + * transaction must be eligible for a refund; see the error responses for invalid amounts, + * permissions, and processing failures. * *

Operation ID: RefundTransaction * @@ -230,7 +246,11 @@ public CompletableFuture> refund( /** * Refund a transaction * - *

Refunds an identified transaction either in full or partially. + *

Refunds a transaction identified by its SumUp transaction ID. Omit the request body to + * request a full refund, or provide `amount` for a partial refund in the transaction's currency. + * Retrieve the transaction afterwards to inspect its refunded amount and refund events. The + * transaction must be eligible for a refund; see the error responses for invalid amounts, + * permissions, and processing failures. * *

Operation ID: RefundTransaction * @@ -361,8 +381,8 @@ public ListTransactionsV21QueryParams entryModes( /** * Sets the limit query parameter. * - * @param value Specifies the maximum number of results per page. Value must be a positive - * integer and if not specified, will return 10 results. + * @param value Maximum number of transactions per page. Must be a positive integer. Defaults to + * `10` when omitted; a page can contain fewer results. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams limit(Long value) { @@ -373,9 +393,9 @@ public ListTransactionsV21QueryParams limit(Long value) { /** * Sets the newest_ref query parameter. * - * @param value 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). + * @param value Pagination reference that returns results before the specified reference. Use + * the value from a returned pagination link rather than constructing it yourself. This + * parameter takes precedence over `newest_time` when both are provided. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams newestRef(String value) { @@ -399,9 +419,9 @@ public ListTransactionsV21QueryParams newestTime(java.time.OffsetDateTime value) /** * Sets the oldest_ref query parameter. * - * @param value 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). + * @param value Pagination reference that returns results after the specified reference. Use the + * value from a returned pagination link rather than constructing it yourself. This + * parameter takes precedence over `oldest_time` when both are provided. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams oldestRef(String value) { @@ -425,7 +445,8 @@ public ListTransactionsV21QueryParams oldestTime(java.time.OffsetDateTime value) /** * Sets the order query parameter. * - * @param value Specifies the order in which the returned results are displayed. + * @param value Sort direction for the transaction history. Use `ascending` or `descending`; the + * default is `ascending`. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams order( @@ -450,8 +471,8 @@ public ListTransactionsV21QueryParams paymentTypes( /** * Sets the statuses[] query parameter. * - * @param value Filters the returned results by the specified list of final statuses of the - * transactions. + * @param value Filters transactions by the listed final statuses. For multiple values, repeat + * the query parameter, for example `statuses[]=SUCCESSFUL&statuses[]=REFUNDED`. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams statuses( @@ -486,7 +507,8 @@ public ListTransactionsV21QueryParams types( /** * Sets the users[] query parameter. * - * @param value Filters the returned results by user email. + * @param value Filters transactions by user email. For multiple values, repeat the query + * parameter, for example `users[]=first@example.com&users[]=second@example.com`. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams users(java.util.List value) { diff --git a/src/main/java/com/sumup/sdk/clients/TransactionsClient.java b/src/main/java/com/sumup/sdk/clients/TransactionsClient.java index 657ac91..51d7589 100644 --- a/src/main/java/com/sumup/sdk/clients/TransactionsClient.java +++ b/src/main/java/com/sumup/sdk/clients/TransactionsClient.java @@ -126,7 +126,11 @@ public com.sumup.sdk.models.TransactionFull get( /** * List transactions * - *

Lists detailed history of all transactions associated with the merchant profile. + *

Lists transaction history for the merchant, with optional filters for payment type, status, + * and date range. The response contains the current page in `items` and pagination query strings + * in `links`. To request another page, use the query string from the relevant link's `href` with + * this history endpoint. Use `changes_since` when retrieving transactions modified since a + * previous synchronization, including transactions created earlier whose status has changed. * *

Operation ID: ListTransactionsV2.1 * @@ -144,7 +148,11 @@ public com.sumup.sdk.models.ListTransactionsV21Response list(String merchantCode /** * List transactions * - *

Lists detailed history of all transactions associated with the merchant profile. + *

Lists transaction history for the merchant, with optional filters for payment type, status, + * and date range. The response contains the current page in `items` and pagination query strings + * in `links`. To request another page, use the query string from the relevant link's `href` with + * this history endpoint. Use `changes_since` when retrieving transactions modified since a + * previous synchronization, including transactions created earlier whose status has changed. * *

Operation ID: ListTransactionsV2.1 * @@ -163,7 +171,11 @@ public com.sumup.sdk.models.ListTransactionsV21Response list( /** * List transactions * - *

Lists detailed history of all transactions associated with the merchant profile. + *

Lists transaction history for the merchant, with optional filters for payment type, status, + * and date range. The response contains the current page in `items` and pagination query strings + * in `links`. To request another page, use the query string from the relevant link's `href` with + * this history endpoint. Use `changes_since` when retrieving transactions modified since a + * previous synchronization, including transactions created earlier whose status has changed. * *

Operation ID: ListTransactionsV2.1 * @@ -202,7 +214,11 @@ public com.sumup.sdk.models.ListTransactionsV21Response list( /** * Refund a transaction * - *

Refunds an identified transaction either in full or partially. + *

Refunds a transaction identified by its SumUp transaction ID. Omit the request body to + * request a full refund, or provide `amount` for a partial refund in the transaction's currency. + * Retrieve the transaction afterwards to inspect its refunded amount and refund events. The + * transaction must be eligible for a refund; see the error responses for invalid amounts, + * permissions, and processing failures. * *

Operation ID: RefundTransaction * @@ -225,7 +241,11 @@ public java.util.Map refund( /** * Refund a transaction * - *

Refunds an identified transaction either in full or partially. + *

Refunds a transaction identified by its SumUp transaction ID. Omit the request body to + * request a full refund, or provide `amount` for a partial refund in the transaction's currency. + * Retrieve the transaction afterwards to inspect its refunded amount and refund events. The + * transaction must be eligible for a refund; see the error responses for invalid amounts, + * permissions, and processing failures. * *

Operation ID: RefundTransaction * @@ -356,8 +376,8 @@ public ListTransactionsV21QueryParams entryModes( /** * Sets the limit query parameter. * - * @param value Specifies the maximum number of results per page. Value must be a positive - * integer and if not specified, will return 10 results. + * @param value Maximum number of transactions per page. Must be a positive integer. Defaults to + * `10` when omitted; a page can contain fewer results. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams limit(Long value) { @@ -368,9 +388,9 @@ public ListTransactionsV21QueryParams limit(Long value) { /** * Sets the newest_ref query parameter. * - * @param value 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). + * @param value Pagination reference that returns results before the specified reference. Use + * the value from a returned pagination link rather than constructing it yourself. This + * parameter takes precedence over `newest_time` when both are provided. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams newestRef(String value) { @@ -394,9 +414,9 @@ public ListTransactionsV21QueryParams newestTime(java.time.OffsetDateTime value) /** * Sets the oldest_ref query parameter. * - * @param value 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). + * @param value Pagination reference that returns results after the specified reference. Use the + * value from a returned pagination link rather than constructing it yourself. This + * parameter takes precedence over `oldest_time` when both are provided. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams oldestRef(String value) { @@ -420,7 +440,8 @@ public ListTransactionsV21QueryParams oldestTime(java.time.OffsetDateTime value) /** * Sets the order query parameter. * - * @param value Specifies the order in which the returned results are displayed. + * @param value Sort direction for the transaction history. Use `ascending` or `descending`; the + * default is `ascending`. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams order( @@ -445,8 +466,8 @@ public ListTransactionsV21QueryParams paymentTypes( /** * Sets the statuses[] query parameter. * - * @param value Filters the returned results by the specified list of final statuses of the - * transactions. + * @param value Filters transactions by the listed final statuses. For multiple values, repeat + * the query parameter, for example `statuses[]=SUCCESSFUL&statuses[]=REFUNDED`. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams statuses( @@ -481,7 +502,8 @@ public ListTransactionsV21QueryParams types( /** * Sets the users[] query parameter. * - * @param value Filters the returned results by user email. + * @param value Filters transactions by user email. For multiple values, repeat the query + * parameter, for example `users[]=first@example.com&users[]=second@example.com`. * @return This ListTransactionsV21QueryParams instance. */ public ListTransactionsV21QueryParams users(java.util.List value) { diff --git a/src/main/java/com/sumup/sdk/events/AsyncEventsHandler.java b/src/main/java/com/sumup/sdk/events/AsyncEventsHandler.java index 700c658..d2d7fad 100644 --- a/src/main/java/com/sumup/sdk/events/AsyncEventsHandler.java +++ b/src/main/java/com/sumup/sdk/events/AsyncEventsHandler.java @@ -108,6 +108,42 @@ public AsyncEventsHandler onReaderDeleted(AsyncEventCallback return this; } + /** + * Registers the callback for {@code "roles.created"}, replacing any previous registration. + * + * @param callback callback to complete before acknowledging delivery + * @return this handler for chaining + */ + public AsyncEventsHandler onRoleCreated(AsyncEventCallback callback) { + Objects.requireNonNull(callback); + callbacks.put("roles.created", event -> callback.handle((RoleCreatedEvent) event)); + return this; + } + + /** + * Registers the callback for {@code "roles.deleted"}, replacing any previous registration. + * + * @param callback callback to complete before acknowledging delivery + * @return this handler for chaining + */ + public AsyncEventsHandler onRoleDeleted(AsyncEventCallback callback) { + Objects.requireNonNull(callback); + callbacks.put("roles.deleted", event -> callback.handle((RoleDeletedEvent) event)); + return this; + } + + /** + * Registers the callback for {@code "roles.updated"}, replacing any previous registration. + * + * @param callback callback to complete before acknowledging delivery + * @return this handler for chaining + */ + public AsyncEventsHandler onRoleUpdated(AsyncEventCallback callback) { + Objects.requireNonNull(callback); + callbacks.put("roles.updated", event -> callback.handle((RoleUpdatedEvent) event)); + return this; + } + /** * Verifies, parses, and completes when the selected callback finishes. * diff --git a/src/main/java/com/sumup/sdk/events/EventNotification.java b/src/main/java/com/sumup/sdk/events/EventNotification.java index 5e4b010..fbed34f 100644 --- a/src/main/java/com/sumup/sdk/events/EventNotification.java +++ b/src/main/java/com/sumup/sdk/events/EventNotification.java @@ -103,6 +103,9 @@ private static EventNotification parseBody(ApiClient client, byte[] body) { case "members.updated" -> MemberUpdatedEvent.class; case "readers.created" -> ReaderCreatedEvent.class; case "readers.deleted" -> ReaderDeletedEvent.class; + case "roles.created" -> RoleCreatedEvent.class; + case "roles.deleted" -> RoleDeletedEvent.class; + case "roles.updated" -> RoleUpdatedEvent.class; default -> EventNotification.class; }; EventNotification event = MAPPER.treeToValue(root, type); diff --git a/src/main/java/com/sumup/sdk/events/EventsHandler.java b/src/main/java/com/sumup/sdk/events/EventsHandler.java index 203b800..89016cf 100644 --- a/src/main/java/com/sumup/sdk/events/EventsHandler.java +++ b/src/main/java/com/sumup/sdk/events/EventsHandler.java @@ -125,6 +125,54 @@ public EventsHandler onReaderDeleted(EventCallback callback) return this; } + /** + * Registers the callback for {@code "roles.created"}, replacing any previous registration. + * + * @param callback callback to complete before acknowledging delivery + * @return this handler for chaining + */ + public EventsHandler onRoleCreated(EventCallback callback) { + Objects.requireNonNull(callback); + callbacks.put( + "roles.created", + event -> { + callback.handle((RoleCreatedEvent) event); + }); + return this; + } + + /** + * Registers the callback for {@code "roles.deleted"}, replacing any previous registration. + * + * @param callback callback to complete before acknowledging delivery + * @return this handler for chaining + */ + public EventsHandler onRoleDeleted(EventCallback callback) { + Objects.requireNonNull(callback); + callbacks.put( + "roles.deleted", + event -> { + callback.handle((RoleDeletedEvent) event); + }); + return this; + } + + /** + * Registers the callback for {@code "roles.updated"}, replacing any previous registration. + * + * @param callback callback to complete before acknowledging delivery + * @return this handler for chaining + */ + public EventsHandler onRoleUpdated(EventCallback callback) { + Objects.requireNonNull(callback); + callbacks.put( + "roles.updated", + event -> { + callback.handle((RoleUpdatedEvent) event); + }); + return this; + } + /** * Verifies, parses, and invokes the selected callback. * diff --git a/src/main/java/com/sumup/sdk/events/RoleCreatedEvent.java b/src/main/java/com/sumup/sdk/events/RoleCreatedEvent.java new file mode 100644 index 0000000..440c053 --- /dev/null +++ b/src/main/java/com/sumup/sdk/events/RoleCreatedEvent.java @@ -0,0 +1,13 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.events; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.sumup.sdk.models.Role; + +/** Sent when a role is created for a merchant account. */ +public final class RoleCreatedEvent extends FetchableEvent { + @Override + TypeReference resourceType() { + return new TypeReference<>() {}; + } +} diff --git a/src/main/java/com/sumup/sdk/events/RoleDeletedEvent.java b/src/main/java/com/sumup/sdk/events/RoleDeletedEvent.java new file mode 100644 index 0000000..dda14b8 --- /dev/null +++ b/src/main/java/com/sumup/sdk/events/RoleDeletedEvent.java @@ -0,0 +1,13 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.events; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.sumup.sdk.models.Role; + +/** Sent when a role is deleted for a merchant account. */ +public final class RoleDeletedEvent extends FetchableEvent { + @Override + TypeReference resourceType() { + return new TypeReference<>() {}; + } +} diff --git a/src/main/java/com/sumup/sdk/events/RoleUpdatedEvent.java b/src/main/java/com/sumup/sdk/events/RoleUpdatedEvent.java new file mode 100644 index 0000000..821c958 --- /dev/null +++ b/src/main/java/com/sumup/sdk/events/RoleUpdatedEvent.java @@ -0,0 +1,13 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.events; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.sumup.sdk.models.Role; + +/** Sent when a role is updated for a merchant account. */ +public final class RoleUpdatedEvent extends FetchableEvent { + @Override + TypeReference resourceType() { + return new TypeReference<>() {}; + } +} diff --git a/src/main/java/com/sumup/sdk/models/Address.java b/src/main/java/com/sumup/sdk/models/Address.java index c054f4c..26f6151 100644 --- a/src/main/java/com/sumup/sdk/models/Address.java +++ b/src/main/java/com/sumup/sdk/models/Address.java @@ -26,11 +26,7 @@ public record Address( */ String commune, - /** - * 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. - */ + /** The ISO3166-1 Alpha-2 code of the address country. */ String country, /** @@ -158,9 +154,7 @@ public Builder commune(String commune) { /** * Sets the value for {@code country}. * - * @param country 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. + * @param country The ISO3166-1 Alpha-2 code of the address country. * @return This builder instance. */ public Builder country(String country) { diff --git a/src/main/java/com/sumup/sdk/models/BasePerson.java b/src/main/java/com/sumup/sdk/models/BasePerson.java index 9f5c317..2e7eb02 100644 --- a/src/main/java/com/sumup/sdk/models/BasePerson.java +++ b/src/main/java/com/sumup/sdk/models/BasePerson.java @@ -7,13 +7,7 @@ * registered the Merchant with SumUp. They should always have a `user_id`. */ public record BasePerson( - /** - * 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. - */ + /** The address of the individual. */ com.sumup.sdk.models.Address address, /** @@ -30,11 +24,7 @@ public record BasePerson( */ String changeStatus, - /** - * 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. - */ + /** The Alpha-2 ISO code of the country where the Person is a citizen. */ String citizenship, /** @@ -70,9 +60,17 @@ public record BasePerson( * not conform to this standard. */ String nationality, + + /** + * Details about the ownership relationship between the Person and the Merchant. This is only + * set if the Person has a relationship of type `owner`. + */ com.sumup.sdk.models.Ownership ownership, - /** A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. */ + /** + * The (mobile) phone number of the individual (used for verification) in + * [E.164](https://en.wikipedia.org/wiki/E.164) format. + */ String phoneNumber, /** @@ -120,11 +118,7 @@ private Builder() {} /** * Sets the value for {@code address}. * - * @param address 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. + * @param address The address of the individual. * @return This builder instance. */ public Builder address(com.sumup.sdk.models.Address address) { @@ -147,9 +141,7 @@ public Builder birthdate(java.time.LocalDate birthdate) { /** * Sets the value for {@code citizenship}. * - * @param citizenship 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. + * @param citizenship The Alpha-2 ISO code of the country where the Person is a citizen. * @return This builder instance. */ public Builder citizenship(String citizenship) { @@ -232,7 +224,8 @@ public Builder nationality(String nationality) { /** * Sets the value for {@code ownership}. * - * @param ownership Value for the ownership field. + * @param ownership Details about the ownership relationship between the Person and the + * Merchant. This is only set if the Person has a relationship of type `owner`. * @return This builder instance. */ public Builder ownership(com.sumup.sdk.models.Ownership ownership) { @@ -243,7 +236,7 @@ public Builder ownership(com.sumup.sdk.models.Ownership ownership) { /** * Sets the value for {@code phoneNumber}. * - * @param phoneNumber A publicly available phone number in + * @param phoneNumber The (mobile) phone number of the individual (used for verification) in * [E.164](https://en.wikipedia.org/wiki/E.164) format. * @return This builder instance. */ diff --git a/src/main/java/com/sumup/sdk/models/CardResponse.java b/src/main/java/com/sumup/sdk/models/CardResponse.java index 47ee1ac..a05540f 100644 --- a/src/main/java/com/sumup/sdk/models/CardResponse.java +++ b/src/main/java/com/sumup/sdk/models/CardResponse.java @@ -6,6 +6,17 @@ public record CardResponse( /** Last 4 digits of the payment card number. */ String last4Digits, + /** + * Payment Account Reference (PAR) defined by + * [EMVCo](https://www.emvco.com/emv-technologies/payment-tokenisation/). It links a card's + * primary account number (PAN) with its affiliated payment tokens, allowing transactions made + * with the physical card and tokenized versions of that card, such as digital wallets, to be + * correlated when PAR is available. This reference cannot be used to initiate a payment and is + * separate from the saved payment instrument `token` used to process checkouts. Returned only + * when available for the card; integrations must handle its absence. + */ + String paymentAccountReference, + /** Issuing card network of the payment card used for the transaction. */ com.sumup.sdk.models.CardType type) { /** @@ -19,10 +30,29 @@ public static Builder builder() { /** Builder for CardResponse instances. */ public static final class Builder { + private String paymentAccountReference; private com.sumup.sdk.models.CardType type; private Builder() {} + /** + * Sets the value for {@code paymentAccountReference}. + * + * @param paymentAccountReference Payment Account Reference (PAR) defined by + * [EMVCo](https://www.emvco.com/emv-technologies/payment-tokenisation/). It links a card's + * primary account number (PAN) with its affiliated payment tokens, allowing transactions + * made with the physical card and tokenized versions of that card, such as digital wallets, + * to be correlated when PAR is available. This reference cannot be used to initiate a + * payment and is separate from the saved payment instrument `token` used to process + * checkouts. Returned only when available for the card; integrations must handle its + * absence. + * @return This builder instance. + */ + public Builder paymentAccountReference(String paymentAccountReference) { + this.paymentAccountReference = paymentAccountReference; + return this; + } + /** * Sets the value for {@code type}. * @@ -40,7 +70,7 @@ public Builder type(com.sumup.sdk.models.CardType type) { * @return Immutable CardResponse. */ public CardResponse build() { - return new CardResponse(null, type); + return new CardResponse(null, paymentAccountReference, type); } } } diff --git a/src/main/java/com/sumup/sdk/models/CardType.java b/src/main/java/com/sumup/sdk/models/CardType.java index 8776125..b0bfecf 100644 --- a/src/main/java/com/sumup/sdk/models/CardType.java +++ b/src/main/java/com/sumup/sdk/models/CardType.java @@ -9,6 +9,7 @@ public final class CardType { public static final CardType ALELO = new CardType("ALELO"); public static final CardType AMEX = new CardType("AMEX"); + public static final CardType BANCOMAT = new CardType("BANCOMAT"); public static final CardType CONECS = new CardType("CONECS"); public static final CardType CUP = new CardType("CUP"); public static final CardType DINERS = new CardType("DINERS"); diff --git a/src/main/java/com/sumup/sdk/models/Checkout.java b/src/main/java/com/sumup/sdk/models/Checkout.java index 0585653..a7ae934 100644 --- a/src/main/java/com/sumup/sdk/models/Checkout.java +++ b/src/main/java/com/sumup/sdk/models/Checkout.java @@ -53,8 +53,11 @@ public record Checkout( String merchantCode, /** - * Optional backend callback URL used by SumUp to notify your platform about processing updates - * for the checkout. + * Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST + * with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status + * before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response + * requirements. */ String returnUrl, @@ -200,8 +203,11 @@ public Builder merchantCode(String merchantCode) { /** * Sets the value for {@code returnUrl}. * - * @param returnUrl Optional backend callback URL used by SumUp to notify your platform about - * processing updates for the checkout. + * @param returnUrl Optional backend callback URL for checkout status notifications. SumUp sends + * an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its + * current status before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and + * response requirements. * @return This builder instance. */ public Builder returnUrl(String returnUrl) { diff --git a/src/main/java/com/sumup/sdk/models/CheckoutCreateRequest.java b/src/main/java/com/sumup/sdk/models/CheckoutCreateRequest.java index da1c507..20f5d77 100644 --- a/src/main/java/com/sumup/sdk/models/CheckoutCreateRequest.java +++ b/src/main/java/com/sumup/sdk/models/CheckoutCreateRequest.java @@ -12,8 +12,10 @@ public record CheckoutCreateRequest( Float amount, /** - * Merchant-defined reference for the new checkout. It should be unique enough for you to - * identify the payment attempt in your own systems. + * Merchant-defined reference for the new checkout, up to 64 characters. Use it to correlate the + * checkout with an order or payment attempt in your own system. If a checkout already exists + * for the supplied unique parameters, creation returns `409` with `DUPLICATED_CHECKOUT`; see + * the conflict response. */ String checkoutReference, @@ -61,8 +63,11 @@ public record CheckoutCreateRequest( String redirectUrl, /** - * Optional backend callback URL used by SumUp to notify your platform about processing updates - * for the checkout. + * Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST + * with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status + * before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response + * requirements. */ String returnUrl, @@ -110,8 +115,10 @@ public Builder amount(Float amount) { /** * Sets the value for {@code checkoutReference}. * - * @param checkoutReference Merchant-defined reference for the new checkout. It should be unique - * enough for you to identify the payment attempt in your own systems. + * @param checkoutReference Merchant-defined reference for the new checkout, up to 64 + * characters. Use it to correlate the checkout with an order or payment attempt in your own + * system. If a checkout already exists for the supplied unique parameters, creation returns + * `409` with `DUPLICATED_CHECKOUT`; see the conflict response. * @return This builder instance. */ public Builder checkoutReference(String checkoutReference) { @@ -211,8 +218,11 @@ public Builder redirectUrl(String redirectUrl) { /** * Sets the value for {@code returnUrl}. * - * @param returnUrl Optional backend callback URL used by SumUp to notify your platform about - * processing updates for the checkout. + * @param returnUrl Optional backend callback URL for checkout status notifications. SumUp sends + * an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its + * current status before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and + * response requirements. * @return This builder instance. */ public Builder returnUrl(String returnUrl) { diff --git a/src/main/java/com/sumup/sdk/models/CheckoutSuccess.java b/src/main/java/com/sumup/sdk/models/CheckoutSuccess.java index ade1473..ab01f88 100644 --- a/src/main/java/com/sumup/sdk/models/CheckoutSuccess.java +++ b/src/main/java/com/sumup/sdk/models/CheckoutSuccess.java @@ -62,8 +62,11 @@ public record CheckoutSuccess( String redirectUrl, /** - * Optional backend callback URL used by SumUp to notify your platform about processing updates - * for the checkout. + * Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST + * with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status + * before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response + * requirements. */ String returnUrl, @@ -257,8 +260,11 @@ public Builder redirectUrl(String redirectUrl) { /** * Sets the value for {@code returnUrl}. * - * @param returnUrl Optional backend callback URL used by SumUp to notify your platform about - * processing updates for the checkout. + * @param returnUrl Optional backend callback URL for checkout status notifications. SumUp sends + * an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its + * current status before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and + * response requirements. * @return This builder instance. */ public Builder returnUrl(String returnUrl) { diff --git a/src/main/java/com/sumup/sdk/models/CheckoutSuccess2.java b/src/main/java/com/sumup/sdk/models/CheckoutSuccess2.java index 939c2d2..cbe4371 100644 --- a/src/main/java/com/sumup/sdk/models/CheckoutSuccess2.java +++ b/src/main/java/com/sumup/sdk/models/CheckoutSuccess2.java @@ -62,8 +62,11 @@ public record CheckoutSuccess2( String redirectUrl, /** - * Optional backend callback URL used by SumUp to notify your platform about processing updates - * for the checkout. + * Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST + * with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status + * before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response + * requirements. */ String returnUrl, @@ -257,8 +260,11 @@ public Builder redirectUrl(String redirectUrl) { /** * Sets the value for {@code returnUrl}. * - * @param returnUrl Optional backend callback URL used by SumUp to notify your platform about - * processing updates for the checkout. + * @param returnUrl Optional backend callback URL for checkout status notifications. SumUp sends + * an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its + * current status before updating your order. See the [webhook + * guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and + * response requirements. * @return This builder instance. */ public Builder returnUrl(String returnUrl) { diff --git a/src/main/java/com/sumup/sdk/models/CheckoutSuccessTransactionsItem.java b/src/main/java/com/sumup/sdk/models/CheckoutSuccessTransactionsItem.java index 48024f5..040c5b4 100644 --- a/src/main/java/com/sumup/sdk/models/CheckoutSuccessTransactionsItem.java +++ b/src/main/java/com/sumup/sdk/models/CheckoutSuccessTransactionsItem.java @@ -2,7 +2,10 @@ package com.sumup.sdk.models; public record CheckoutSuccessTransactionsItem( - /** Total amount of the transaction. */ + /** + * Total amount of the transaction in major units of `currency`, for example `10.1` for EUR + * 10.10. + */ Float amount, /** @@ -16,7 +19,11 @@ public record CheckoutSuccessTransactionsItem( */ com.sumup.sdk.models.Currency currency, - /** Entry mode of the payment details. */ + /** + * How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present + * payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and + * alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`. + */ com.sumup.sdk.models.EntryMode entryMode, /** Unique identifier of the transaction. */ @@ -28,7 +35,12 @@ public record CheckoutSuccessTransactionsItem( /** Unique code of the registered merchant to whom the payment is made. */ String merchantCode, - /** Payment type used for the transaction. */ + /** + * Payment category recorded on a transaction, for example `POS` for a point-of-sale card + * payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. + * These reporting values are separate from the lowercase `payment_type` values used to process + * checkouts. + */ com.sumup.sdk.models.PaymentType paymentType, /** @@ -43,15 +55,21 @@ public record CheckoutSuccessTransactionsItem( /** The timestamp of when the transaction was created. */ java.time.OffsetDateTime timestamp, - /** Amount of the tip (out of the total transaction amount). */ + /** + * Tip included in the total transaction amount, in major units of the transaction's currency. + */ Float tipAmount, /** - * Transaction code returned by the acquirer/processing entity after processing the transaction. + * SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the + * `transaction_code` query parameter. This is separate from the transaction's `id` and the card + * issuer's `auth_code`. */ String transactionCode, - /** Amount of the applicable VAT (out of the total transaction amount). */ + /** + * VAT included in the total transaction amount, in major units of the transaction's currency. + */ Float vatAmount) { /** * Creates a builder for CheckoutSuccessTransactionsItem. @@ -83,7 +101,8 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount Total amount of the transaction. + * @param amount Total amount of the transaction in major units of `currency`, for example + * `10.1` for EUR 10.10. * @return This builder instance. */ public Builder amount(Float amount) { @@ -118,7 +137,10 @@ public Builder currency(com.sumup.sdk.models.Currency currency) { /** * Sets the value for {@code entryMode}. * - * @param entryMode Entry mode of the payment details. + * @param entryMode How the payment details were captured, for example `CHIP` or `CONTACTLESS` + * for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For + * wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` + * or `BLIK`. * @return This builder instance. */ public Builder entryMode(com.sumup.sdk.models.EntryMode entryMode) { @@ -162,7 +184,10 @@ public Builder merchantCode(String merchantCode) { /** * Sets the value for {@code paymentType}. * - * @param paymentType Payment type used for the transaction. + * @param paymentType Payment category recorded on a transaction, for example `POS` for a + * point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a + * recurring card payment. These reporting values are separate from the lowercase + * `payment_type` values used to process checkouts. * @return This builder instance. */ public Builder paymentType(com.sumup.sdk.models.PaymentType paymentType) { @@ -199,7 +224,8 @@ public Builder timestamp(java.time.OffsetDateTime timestamp) { /** * Sets the value for {@code tipAmount}. * - * @param tipAmount Amount of the tip (out of the total transaction amount). + * @param tipAmount Tip included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder tipAmount(Float tipAmount) { @@ -210,8 +236,9 @@ public Builder tipAmount(Float tipAmount) { /** * Sets the value for {@code transactionCode}. * - * @param transactionCode Transaction code returned by the acquirer/processing entity after - * processing the transaction. + * @param transactionCode SumUp transaction code, for example `TEENSK4W2K`. Use it to look up + * the transaction with the `transaction_code` query parameter. This is separate from the + * transaction's `id` and the card issuer's `auth_code`. * @return This builder instance. */ public Builder transactionCode(String transactionCode) { @@ -222,7 +249,8 @@ public Builder transactionCode(String transactionCode) { /** * Sets the value for {@code vatAmount}. * - * @param vatAmount Amount of the applicable VAT (out of the total transaction amount). + * @param vatAmount VAT included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder vatAmount(Float vatAmount) { diff --git a/src/main/java/com/sumup/sdk/models/CheckoutTransactionsItem.java b/src/main/java/com/sumup/sdk/models/CheckoutTransactionsItem.java index 70f15ea..a8a83c0 100644 --- a/src/main/java/com/sumup/sdk/models/CheckoutTransactionsItem.java +++ b/src/main/java/com/sumup/sdk/models/CheckoutTransactionsItem.java @@ -2,7 +2,10 @@ package com.sumup.sdk.models; public record CheckoutTransactionsItem( - /** Total amount of the transaction. */ + /** + * Total amount of the transaction in major units of `currency`, for example `10.1` for EUR + * 10.10. + */ Float amount, /** @@ -16,7 +19,11 @@ public record CheckoutTransactionsItem( */ com.sumup.sdk.models.Currency currency, - /** Entry mode of the payment details. */ + /** + * How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present + * payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and + * alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`. + */ com.sumup.sdk.models.EntryMode entryMode, /** Unique identifier of the transaction. */ @@ -28,7 +35,12 @@ public record CheckoutTransactionsItem( /** Unique code of the registered merchant to whom the payment is made. */ String merchantCode, - /** Payment type used for the transaction. */ + /** + * Payment category recorded on a transaction, for example `POS` for a point-of-sale card + * payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. + * These reporting values are separate from the lowercase `payment_type` values used to process + * checkouts. + */ com.sumup.sdk.models.PaymentType paymentType, /** @@ -43,15 +55,21 @@ public record CheckoutTransactionsItem( /** The timestamp of when the transaction was created. */ java.time.OffsetDateTime timestamp, - /** Amount of the tip (out of the total transaction amount). */ + /** + * Tip included in the total transaction amount, in major units of the transaction's currency. + */ Float tipAmount, /** - * Transaction code returned by the acquirer/processing entity after processing the transaction. + * SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the + * `transaction_code` query parameter. This is separate from the transaction's `id` and the card + * issuer's `auth_code`. */ String transactionCode, - /** Amount of the applicable VAT (out of the total transaction amount). */ + /** + * VAT included in the total transaction amount, in major units of the transaction's currency. + */ Float vatAmount) { /** * Creates a builder for CheckoutTransactionsItem. @@ -83,7 +101,8 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount Total amount of the transaction. + * @param amount Total amount of the transaction in major units of `currency`, for example + * `10.1` for EUR 10.10. * @return This builder instance. */ public Builder amount(Float amount) { @@ -118,7 +137,10 @@ public Builder currency(com.sumup.sdk.models.Currency currency) { /** * Sets the value for {@code entryMode}. * - * @param entryMode Entry mode of the payment details. + * @param entryMode How the payment details were captured, for example `CHIP` or `CONTACTLESS` + * for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For + * wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` + * or `BLIK`. * @return This builder instance. */ public Builder entryMode(com.sumup.sdk.models.EntryMode entryMode) { @@ -162,7 +184,10 @@ public Builder merchantCode(String merchantCode) { /** * Sets the value for {@code paymentType}. * - * @param paymentType Payment type used for the transaction. + * @param paymentType Payment category recorded on a transaction, for example `POS` for a + * point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a + * recurring card payment. These reporting values are separate from the lowercase + * `payment_type` values used to process checkouts. * @return This builder instance. */ public Builder paymentType(com.sumup.sdk.models.PaymentType paymentType) { @@ -199,7 +224,8 @@ public Builder timestamp(java.time.OffsetDateTime timestamp) { /** * Sets the value for {@code tipAmount}. * - * @param tipAmount Amount of the tip (out of the total transaction amount). + * @param tipAmount Tip included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder tipAmount(Float tipAmount) { @@ -210,8 +236,9 @@ public Builder tipAmount(Float tipAmount) { /** * Sets the value for {@code transactionCode}. * - * @param transactionCode Transaction code returned by the acquirer/processing entity after - * processing the transaction. + * @param transactionCode SumUp transaction code, for example `TEENSK4W2K`. Use it to look up + * the transaction with the `transaction_code` query parameter. This is separate from the + * transaction's `id` and the card issuer's `auth_code`. * @return This builder instance. */ public Builder transactionCode(String transactionCode) { @@ -222,7 +249,8 @@ public Builder transactionCode(String transactionCode) { /** * Sets the value for {@code vatAmount}. * - * @param vatAmount Amount of the applicable VAT (out of the total transaction amount). + * @param vatAmount VAT included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder vatAmount(Float vatAmount) { diff --git a/src/main/java/com/sumup/sdk/models/Company.java b/src/main/java/com/sumup/sdk/models/Company.java index 4e1443b..a43be3f 100644 --- a/src/main/java/com/sumup/sdk/models/Company.java +++ b/src/main/java/com/sumup/sdk/models/Company.java @@ -6,13 +6,7 @@ * verification. */ public record Company( - /** - * 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. - */ + /** The company's primary address. */ com.sumup.sdk.models.Address address, /** Object attributes that are modifiable only by SumUp applications. */ @@ -21,11 +15,7 @@ public record Company( /** A list of country-specific company identifiers. */ com.sumup.sdk.models.CompanyIdentifiers identifiers, - /** - * 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. - */ + /** The category identifying the legal structure of the company or legal entity. */ String legalType, /** @@ -38,15 +28,15 @@ public record Company( /** The company's legal name. */ String name, - /** A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. */ + /** + * The company's phone number (used for verification) in + * [E.164](https://en.wikipedia.org/wiki/E.164) format. + */ String phoneNumber, /** - * 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. + * A trading address is where your suppliers, banks or customers send you correspondence to. + * Trading address can be different to the company's registered address (`address`). */ com.sumup.sdk.models.Address tradingAddress, @@ -78,11 +68,7 @@ private Builder() {} /** * Sets the value for {@code address}. * - * @param address 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. + * @param address The company's primary address. * @return This builder instance. */ public Builder address(com.sumup.sdk.models.Address address) { @@ -115,9 +101,7 @@ public Builder identifiers(com.sumup.sdk.models.CompanyIdentifiers identifiers) /** * Sets the value for {@code legalType}. * - * @param legalType 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. + * @param legalType The category identifying the legal structure of the company or legal entity. * @return This builder instance. */ public Builder legalType(String legalType) { @@ -152,7 +136,7 @@ public Builder name(String name) { /** * Sets the value for {@code phoneNumber}. * - * @param phoneNumber A publicly available phone number in + * @param phoneNumber The company's phone number (used for verification) in * [E.164](https://en.wikipedia.org/wiki/E.164) format. * @return This builder instance. */ @@ -164,11 +148,9 @@ public Builder phoneNumber(String phoneNumber) { /** * Sets the value for {@code tradingAddress}. * - * @param tradingAddress 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. + * @param tradingAddress A trading address is where your suppliers, banks or customers send you + * correspondence to. Trading address can be different to the company's registered address + * (`address`). * @return This builder instance. */ public Builder tradingAddress(com.sumup.sdk.models.Address tradingAddress) { diff --git a/src/main/java/com/sumup/sdk/models/CreateApplePaySessionRequest.java b/src/main/java/com/sumup/sdk/models/CreateApplePaySessionRequest.java index 1814a39..6a1f106 100644 --- a/src/main/java/com/sumup/sdk/models/CreateApplePaySessionRequest.java +++ b/src/main/java/com/sumup/sdk/models/CreateApplePaySessionRequest.java @@ -4,10 +4,16 @@ import java.util.Objects; public record CreateApplePaySessionRequest( - /** the context to create this apple pay session. */ + /** + * Hostname of the website displaying the Apple Pay payment sheet, without a URL scheme or path. + * Use the domain registered for Apple Pay. + */ String context, - /** The target url to create this apple pay session. */ + /** + * Apple Pay validation URL received as `validationURL` in the browser's `onvalidatemerchant` + * event. + */ String target) { /** * Creates a builder for CreateApplePaySessionRequest. @@ -28,7 +34,8 @@ private Builder() {} /** * Sets the value for {@code context}. * - * @param context the context to create this apple pay session. + * @param context Hostname of the website displaying the Apple Pay payment sheet, without a URL + * scheme or path. Use the domain registered for Apple Pay. * @return This builder instance. */ public Builder context(String context) { @@ -39,7 +46,8 @@ public Builder context(String context) { /** * Sets the value for {@code target}. * - * @param target The target url to create this apple pay session. + * @param target Apple Pay validation URL received as `validationURL` in the browser's + * `onvalidatemerchant` event. * @return This builder instance. */ public Builder target(String target) { diff --git a/src/main/java/com/sumup/sdk/models/Currency.java b/src/main/java/com/sumup/sdk/models/Currency.java index 54902a3..f8f99fd 100644 --- a/src/main/java/com/sumup/sdk/models/Currency.java +++ b/src/main/java/com/sumup/sdk/models/Currency.java @@ -7,7 +7,6 @@ /** Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount. */ public final class Currency { - public static final Currency BGN = new Currency("BGN"); public static final Currency BRL = new Currency("BRL"); public static final Currency CHF = new Currency("CHF"); public static final Currency CLP = new Currency("CLP"); diff --git a/src/main/java/com/sumup/sdk/models/Customer.java b/src/main/java/com/sumup/sdk/models/Customer.java index d90a2bc..351d2d9 100644 --- a/src/main/java/com/sumup/sdk/models/Customer.java +++ b/src/main/java/com/sumup/sdk/models/Customer.java @@ -3,9 +3,15 @@ import java.util.Objects; -/** Saved customer details. */ +/** + * Saved payer details identified by the `customer_id` supplied by your integration. A customer can + * have saved payment instruments for subsequent payments. + */ public record Customer( - /** Unique identifier of the customer. */ + /** + * Identifier you supply when creating the customer. Use an ID from your own system and retain + * it for subsequent customer, checkout, and saved-payment-instrument requests. + */ String customerId, /** Personal details for the customer. */ @@ -29,7 +35,9 @@ private Builder() {} /** * Sets the value for {@code customerId}. * - * @param customerId Unique identifier of the customer. + * @param customerId Identifier you supply when creating the customer. Use an ID from your own + * system and retain it for subsequent customer, checkout, and saved-payment-instrument + * requests. * @return This builder instance. */ public Builder customerId(String customerId) { diff --git a/src/main/java/com/sumup/sdk/models/EntryMode.java b/src/main/java/com/sumup/sdk/models/EntryMode.java index 9d57595..00f6a24 100644 --- a/src/main/java/com/sumup/sdk/models/EntryMode.java +++ b/src/main/java/com/sumup/sdk/models/EntryMode.java @@ -5,7 +5,11 @@ import com.fasterxml.jackson.annotation.JsonValue; import java.util.Objects; -/** Entry mode of the payment details. */ +/** + * How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present + * payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and alternative + * payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`. + */ public final class EntryMode { public static final EntryMode BOLETO = new EntryMode("BOLETO"); public static final EntryMode SOFORT = new EntryMode("SOFORT"); diff --git a/src/main/java/com/sumup/sdk/models/Event.java b/src/main/java/com/sumup/sdk/models/Event.java index 7cc6794..6ed3ebc 100644 --- a/src/main/java/com/sumup/sdk/models/Event.java +++ b/src/main/java/com/sumup/sdk/models/Event.java @@ -15,7 +15,11 @@ public record Event( /** Fee associated with the transaction event, in major units. */ Float feeAmount, - /** Unique identifier of the transaction event. */ + /** + * Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting receipt + * details for a specific event. This is separate from the transaction ID and the transaction + * history pagination references. + */ Long id, /** Consecutive number of the installment associated with the event. */ @@ -45,7 +49,13 @@ public record Event( /** Unique identifier of the transaction. */ String transactionId, - /** Type of the transaction event. */ + /** + * Financial event associated with a transaction. - `PAYOUT`: Funds from the transaction being + * prepared for or included in a merchant payout. Check the event status to determine whether + * they have been paid out. - `REFUND`: Money returned to the payer. - `CHARGE_BACK`: A reversal + * of the payment following a chargeback. - `PAYOUT_DEDUCTION`: An amount deducted from a + * merchant payout, for example to cover a refund or chargeback. + */ com.sumup.sdk.models.TransactionEventType type) { /** * Creates a builder for Event. @@ -118,7 +128,9 @@ public Builder feeAmount(Float feeAmount) { /** * Sets the value for {@code id}. * - * @param id Unique identifier of the transaction event. + * @param id Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting + * receipt details for a specific event. This is separate from the transaction ID and the + * transaction history pagination references. * @return This builder instance. */ public Builder id(Long id) { @@ -187,7 +199,11 @@ public Builder transactionId(String transactionId) { /** * Sets the value for {@code type}. * - * @param type Type of the transaction event. + * @param type Financial event associated with a transaction. - `PAYOUT`: Funds from the + * transaction being prepared for or included in a merchant payout. Check the event status + * to determine whether they have been paid out. - `REFUND`: Money returned to the payer. - + * `CHARGE_BACK`: A reversal of the payment following a chargeback. - `PAYOUT_DEDUCTION`: An + * amount deducted from a merchant payout, for example to cover a refund or chargeback. * @return This builder instance. */ public Builder type(com.sumup.sdk.models.TransactionEventType type) { diff --git a/src/main/java/com/sumup/sdk/models/PaymentInstrumentResponse.java b/src/main/java/com/sumup/sdk/models/PaymentInstrumentResponse.java index 5927a4e..a2397dd 100644 --- a/src/main/java/com/sumup/sdk/models/PaymentInstrumentResponse.java +++ b/src/main/java/com/sumup/sdk/models/PaymentInstrumentResponse.java @@ -18,7 +18,11 @@ public record PaymentInstrumentResponse( /** Details of the mandate linked to the saved payment instrument. */ com.sumup.sdk.models.MandateResponse mandate, - /** Unique token identifying the saved payment card for a customer. */ + /** + * Token identifying the customer's saved payment card. Pass it as `token`, together with the + * associated `customer_id` and `payment_type = card`, when processing a checkout with this + * instrument. + */ String token, /** Type of the payment instrument. */ diff --git a/src/main/java/com/sumup/sdk/models/PaymentType.java b/src/main/java/com/sumup/sdk/models/PaymentType.java index accb48a..a1890b5 100644 --- a/src/main/java/com/sumup/sdk/models/PaymentType.java +++ b/src/main/java/com/sumup/sdk/models/PaymentType.java @@ -5,7 +5,11 @@ import com.fasterxml.jackson.annotation.JsonValue; import java.util.Objects; -/** Payment type used for the transaction. */ +/** + * Payment category recorded on a transaction, for example `POS` for a point-of-sale card payment, + * `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. These reporting + * values are separate from the lowercase `payment_type` values used to process checkouts. + */ public final class PaymentType { public static final PaymentType CASH = new PaymentType("CASH"); public static final PaymentType POS = new PaymentType("POS"); diff --git a/src/main/java/com/sumup/sdk/models/Person.java b/src/main/java/com/sumup/sdk/models/Person.java index dee505a..7e3c404 100644 --- a/src/main/java/com/sumup/sdk/models/Person.java +++ b/src/main/java/com/sumup/sdk/models/Person.java @@ -2,13 +2,7 @@ package com.sumup.sdk.models; public record Person( - /** - * 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. - */ + /** The address of the individual. */ com.sumup.sdk.models.Address address, /** @@ -25,11 +19,7 @@ public record Person( */ String changeStatus, - /** - * 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. - */ + /** The Alpha-2 ISO code of the country where the Person is a citizen. */ String citizenship, /** @@ -65,9 +55,17 @@ public record Person( * not conform to this standard. */ String nationality, + + /** + * Details about the ownership relationship between the Person and the Merchant. This is only + * set if the Person has a relationship of type `owner`. + */ com.sumup.sdk.models.Ownership ownership, - /** A publicly available phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. */ + /** + * The (mobile) phone number of the individual (used for verification) in + * [E.164](https://en.wikipedia.org/wiki/E.164) format. + */ String phoneNumber, /** @@ -115,11 +113,7 @@ private Builder() {} /** * Sets the value for {@code address}. * - * @param address 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. + * @param address The address of the individual. * @return This builder instance. */ public Builder address(com.sumup.sdk.models.Address address) { @@ -142,9 +136,7 @@ public Builder birthdate(java.time.LocalDate birthdate) { /** * Sets the value for {@code citizenship}. * - * @param citizenship 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. + * @param citizenship The Alpha-2 ISO code of the country where the Person is a citizen. * @return This builder instance. */ public Builder citizenship(String citizenship) { @@ -227,7 +219,8 @@ public Builder nationality(String nationality) { /** * Sets the value for {@code ownership}. * - * @param ownership Value for the ownership field. + * @param ownership Details about the ownership relationship between the Person and the + * Merchant. This is only set if the Person has a relationship of type `owner`. * @return This builder instance. */ public Builder ownership(com.sumup.sdk.models.Ownership ownership) { @@ -238,7 +231,7 @@ public Builder ownership(com.sumup.sdk.models.Ownership ownership) { /** * Sets the value for {@code phoneNumber}. * - * @param phoneNumber A publicly available phone number in + * @param phoneNumber The (mobile) phone number of the individual (used for verification) in * [E.164](https://en.wikipedia.org/wiki/E.164) format. * @return This builder instance. */ diff --git a/src/main/java/com/sumup/sdk/models/PersonalDetails.java b/src/main/java/com/sumup/sdk/models/PersonalDetails.java index 209c84b..530a4d7 100644 --- a/src/main/java/com/sumup/sdk/models/PersonalDetails.java +++ b/src/main/java/com/sumup/sdk/models/PersonalDetails.java @@ -6,7 +6,7 @@ public record PersonalDetails( /** Profile's personal address information. */ com.sumup.sdk.models.AddressLegacy address, - /** Date of birth of the customer. */ + /** Date of birth of the customer in `YYYY-MM-DD` format, without a time or timezone. */ java.time.LocalDate birthDate, /** Email address of the customer. */ @@ -58,7 +58,8 @@ public Builder address(com.sumup.sdk.models.AddressLegacy address) { /** * Sets the value for {@code birthDate}. * - * @param birthDate Date of birth of the customer. + * @param birthDate Date of birth of the customer in `YYYY-MM-DD` format, without a time or + * timezone. * @return This builder instance. */ public Builder birthDate(java.time.LocalDate birthDate) { diff --git a/src/main/java/com/sumup/sdk/models/ProcessCheckout.java b/src/main/java/com/sumup/sdk/models/ProcessCheckout.java index 93a78f5..992aee8 100644 --- a/src/main/java/com/sumup/sdk/models/ProcessCheckout.java +++ b/src/main/java/com/sumup/sdk/models/ProcessCheckout.java @@ -48,8 +48,9 @@ public record ProcessCheckout( com.sumup.sdk.models.PersonalDetails personalDetails, /** - * Saved-card token to use instead of raw card details when processing with a previously stored - * payment instrument. + * Token of a saved payment instrument returned by checkout processing or the customer's + * payment-instruments endpoint. To charge a saved card, set `payment_type` to `card` and + * provide both this `token` and the associated `customer_id` instead of raw card details. */ String token) { /** @@ -172,8 +173,10 @@ public Builder personalDetails(com.sumup.sdk.models.PersonalDetails personalDeta /** * Sets the value for {@code token}. * - * @param token Saved-card token to use instead of raw card details when processing with a - * previously stored payment instrument. + * @param token Token of a saved payment instrument returned by checkout processing or the + * customer's payment-instruments endpoint. To charge a saved card, set `payment_type` to + * `card` and provide both this `token` and the associated `customer_id` instead of raw card + * details. * @return This builder instance. */ public Builder token(String token) { diff --git a/src/main/java/com/sumup/sdk/models/Product.java b/src/main/java/com/sumup/sdk/models/Product.java index bd58c07..b78db14 100644 --- a/src/main/java/com/sumup/sdk/models/Product.java +++ b/src/main/java/com/sumup/sdk/models/Product.java @@ -30,7 +30,7 @@ public record Product( /** Total VAT amount for the product quantity. */ Double vatAmount, - /** VAT rate applied to the product price. */ + /** VAT rate as a decimal fraction, for example `0.19` for 19%. */ Double vatRate) { /** * Creates a builder for Product. @@ -158,7 +158,7 @@ public Builder vatAmount(Double vatAmount) { /** * Sets the value for {@code vatRate}. * - * @param vatRate VAT rate applied to the product price. + * @param vatRate VAT rate as a decimal fraction, for example `0.19` for 19%. * @return This builder instance. */ public Builder vatRate(Double vatRate) { diff --git a/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParams.java b/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParams.java index ebdd030..4657760 100644 --- a/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParams.java +++ b/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParams.java @@ -4,14 +4,14 @@ import java.util.Objects; public record ReaderPaymentRequestParams( - com.sumup.sdk.models.Affiliate affiliate, + com.sumup.sdk.models.ReaderPaymentRequestParamsAffiliate affiliate, /** Caller-supplied correlation identifier, used as the idempotency key. */ String clientTransactionId, - /** Optional tip amount in minor units, added on top of total_amount. */ + /** Portion of total_amount that is a tip, in minor units. */ Long tipAmount, - com.sumup.sdk.models.Amount totalAmount) { + com.sumup.sdk.models.ReaderPaymentRequestParamsTotalAmount totalAmount) { /** * Creates a builder for ReaderPaymentRequestParams. * @@ -23,10 +23,10 @@ public static Builder builder() { /** Builder for ReaderPaymentRequestParams instances. */ public static final class Builder { - private com.sumup.sdk.models.Affiliate affiliate; + private com.sumup.sdk.models.ReaderPaymentRequestParamsAffiliate affiliate; private String clientTransactionId; private Long tipAmount; - private com.sumup.sdk.models.Amount totalAmount; + private com.sumup.sdk.models.ReaderPaymentRequestParamsTotalAmount totalAmount; private Builder() {} @@ -36,7 +36,7 @@ private Builder() {} * @param affiliate Value for the affiliate field. * @return This builder instance. */ - public Builder affiliate(com.sumup.sdk.models.Affiliate affiliate) { + public Builder affiliate(com.sumup.sdk.models.ReaderPaymentRequestParamsAffiliate affiliate) { this.affiliate = affiliate; return this; } @@ -56,7 +56,7 @@ public Builder clientTransactionId(String clientTransactionId) { /** * Sets the value for {@code tipAmount}. * - * @param tipAmount Optional tip amount in minor units, added on top of total_amount. + * @param tipAmount Portion of total_amount that is a tip, in minor units. * @return This builder instance. */ public Builder tipAmount(Long tipAmount) { @@ -70,7 +70,8 @@ public Builder tipAmount(Long tipAmount) { * @param totalAmount Value for the totalAmount field. * @return This builder instance. */ - public Builder totalAmount(com.sumup.sdk.models.Amount totalAmount) { + public Builder totalAmount( + com.sumup.sdk.models.ReaderPaymentRequestParamsTotalAmount totalAmount) { this.totalAmount = totalAmount; return this; } diff --git a/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsAffiliate.java b/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsAffiliate.java new file mode 100644 index 0000000..65bee15 --- /dev/null +++ b/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsAffiliate.java @@ -0,0 +1,56 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.models; + +import java.util.Objects; + +public record ReaderPaymentRequestParamsAffiliate(String appId, String key) { + + /** + * Creates a builder for ReaderPaymentRequestParamsAffiliate. + * + * @return Builder that constructs immutable ReaderPaymentRequestParamsAffiliate instances. + */ + public static Builder builder() { + return new Builder(); + } + + /** Builder for ReaderPaymentRequestParamsAffiliate instances. */ + public static final class Builder { + private String appId; + private String key; + + private Builder() {} + + /** + * Sets the value for {@code appId}. + * + * @param appId Value for the appId field. + * @return This builder instance. + */ + public Builder appId(String appId) { + this.appId = appId; + return this; + } + + /** + * Sets the value for {@code key}. + * + * @param key Value for the key field. + * @return This builder instance. + */ + public Builder key(String key) { + this.key = key; + return this; + } + + /** + * Builds an immutable ReaderPaymentRequestParamsAffiliate instance. + * + * @return Immutable ReaderPaymentRequestParamsAffiliate. + */ + public ReaderPaymentRequestParamsAffiliate build() { + return new ReaderPaymentRequestParamsAffiliate( + Objects.requireNonNull(appId, "appId"), Objects.requireNonNull(key, "key")); + } + } +} diff --git a/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsTotalAmount.java b/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsTotalAmount.java new file mode 100644 index 0000000..a12406a --- /dev/null +++ b/src/main/java/com/sumup/sdk/models/ReaderPaymentRequestParamsTotalAmount.java @@ -0,0 +1,60 @@ +// Code generated by sumup-java/codegen. DO NOT EDIT. +package com.sumup.sdk.models; + +import java.util.Objects; + +public record ReaderPaymentRequestParamsTotalAmount( + /** Currency ISO 4217 code */ + String currency, + + /** Amount in minor units (e.g. cents). */ + Long value) { + /** + * Creates a builder for ReaderPaymentRequestParamsTotalAmount. + * + * @return Builder that constructs immutable ReaderPaymentRequestParamsTotalAmount instances. + */ + public static Builder builder() { + return new Builder(); + } + + /** Builder for ReaderPaymentRequestParamsTotalAmount instances. */ + public static final class Builder { + private String currency; + private Long value; + + private Builder() {} + + /** + * Sets the value for {@code currency}. + * + * @param currency Currency ISO 4217 code + * @return This builder instance. + */ + public Builder currency(String currency) { + this.currency = currency; + return this; + } + + /** + * Sets the value for {@code value}. + * + * @param value Amount in minor units (e.g. cents). + * @return This builder instance. + */ + public Builder value(Long value) { + this.value = value; + return this; + } + + /** + * Builds an immutable ReaderPaymentRequestParamsTotalAmount instance. + * + * @return Immutable ReaderPaymentRequestParamsTotalAmount. + */ + public ReaderPaymentRequestParamsTotalAmount build() { + return new ReaderPaymentRequestParamsTotalAmount( + Objects.requireNonNull(currency, "currency"), Objects.requireNonNull(value, "value")); + } + } +} diff --git a/src/main/java/com/sumup/sdk/models/Receipt.java b/src/main/java/com/sumup/sdk/models/Receipt.java index 24102ba..1961fd1 100644 --- a/src/main/java/com/sumup/sdk/models/Receipt.java +++ b/src/main/java/com/sumup/sdk/models/Receipt.java @@ -1,7 +1,11 @@ // Code generated by sumup-java/codegen. DO NOT EDIT. package com.sumup.sdk.models; -/** Receipt details for a transaction. */ +/** + * Structured receipt details for a transaction. The transaction's `amount`, `vat_amount`, and + * `tip_amount`, as well as event amounts, are returned as decimal strings in major currency units, + * for example `"10.10"` for EUR 10.10. + */ public record Receipt( /** Acquirer-specific metadata related to the card authorization. */ com.sumup.sdk.models.ReceiptAcquirerData acquirerData, diff --git a/src/main/java/com/sumup/sdk/models/ReceiptEvent.java b/src/main/java/com/sumup/sdk/models/ReceiptEvent.java index ac69c42..5a77a66 100644 --- a/src/main/java/com/sumup/sdk/models/ReceiptEvent.java +++ b/src/main/java/com/sumup/sdk/models/ReceiptEvent.java @@ -6,7 +6,11 @@ public record ReceiptEvent( /** Amount associated with the transaction event, in major units. */ String amount, - /** Unique identifier of the transaction event. */ + /** + * Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting receipt + * details for a specific event. This is separate from the transaction ID and the transaction + * history pagination references. + */ Long id, /** Receipt number associated with the event. */ @@ -36,7 +40,13 @@ public record ReceiptEvent( /** Unique identifier of the transaction. */ String transactionId, - /** Type of the transaction event. */ + /** + * Financial event associated with a transaction. - `PAYOUT`: Funds from the transaction being + * prepared for or included in a merchant payout. Check the event status to determine whether + * they have been paid out. - `REFUND`: Money returned to the payer. - `CHARGE_BACK`: A reversal + * of the payment following a chargeback. - `PAYOUT_DEDUCTION`: An amount deducted from a + * merchant payout, for example to cover a refund or chargeback. + */ com.sumup.sdk.models.TransactionEventType type) { /** * Creates a builder for ReceiptEvent. @@ -73,7 +83,9 @@ public Builder amount(String amount) { /** * Sets the value for {@code id}. * - * @param id Unique identifier of the transaction event. + * @param id Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting + * receipt details for a specific event. This is separate from the transaction ID and the + * transaction history pagination references. * @return This builder instance. */ public Builder id(Long id) { @@ -142,7 +154,11 @@ public Builder transactionId(String transactionId) { /** * Sets the value for {@code type}. * - * @param type Type of the transaction event. + * @param type Financial event associated with a transaction. - `PAYOUT`: Funds from the + * transaction being prepared for or included in a merchant payout. Check the event status + * to determine whether they have been paid out. - `REFUND`: Money returned to the payer. - + * `CHARGE_BACK`: A reversal of the payment following a chargeback. - `PAYOUT_DEDUCTION`: An + * amount deducted from a merchant payout, for example to cover a refund or chargeback. * @return This builder instance. */ public Builder type(com.sumup.sdk.models.TransactionEventType type) { diff --git a/src/main/java/com/sumup/sdk/models/RefundTransactionRequest.java b/src/main/java/com/sumup/sdk/models/RefundTransactionRequest.java index 4b29681..6723625 100644 --- a/src/main/java/com/sumup/sdk/models/RefundTransactionRequest.java +++ b/src/main/java/com/sumup/sdk/models/RefundTransactionRequest.java @@ -4,9 +4,10 @@ /** Optional amount for partial refunds of transactions. */ public record RefundTransactionRequest( /** - * 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. + * Amount to refund in major units of the transaction's currency, for example `5` for EUR 5.00. + * It must be greater than zero and cannot exceed the amount eligible for a refund. Eligibility + * depends on the transaction and country/currency rules. If omitted, the system requests a full + * refund. */ Float amount) { /** @@ -27,9 +28,10 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount 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. + * @param amount Amount to refund in major units of the transaction's currency, for example `5` + * for EUR 5.00. It must be greater than zero and cannot exceed the amount eligible for a + * refund. Eligibility depends on the transaction and country/currency rules. If omitted, + * the system requests a full refund. * @return This builder instance. */ public Builder amount(Float amount) { diff --git a/src/main/java/com/sumup/sdk/models/TransactionBase.java b/src/main/java/com/sumup/sdk/models/TransactionBase.java index 351810d..f05e7e0 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionBase.java +++ b/src/main/java/com/sumup/sdk/models/TransactionBase.java @@ -3,7 +3,10 @@ /** Core details shared by transaction resources. */ public record TransactionBase( - /** Total amount of the transaction. */ + /** + * Total amount of the transaction in major units of `currency`, for example `10.1` for EUR + * 10.10. + */ Float amount, /** @@ -17,7 +20,12 @@ public record TransactionBase( /** Number of installments for a deferred payment. */ Long installmentsCount, - /** Payment type used for the transaction. */ + /** + * Payment category recorded on a transaction, for example `POS` for a point-of-sale card + * payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. + * These reporting values are separate from the lowercase `payment_type` values used to process + * checkouts. + */ com.sumup.sdk.models.PaymentType paymentType, /** @@ -33,7 +41,9 @@ public record TransactionBase( java.time.OffsetDateTime timestamp, /** - * Transaction code returned by the acquirer/processing entity after processing the transaction. + * SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the + * `transaction_code` query parameter. This is separate from the transaction's `id` and the card + * issuer's `auth_code`. */ String transactionCode) { /** @@ -61,7 +71,8 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount Total amount of the transaction. + * @param amount Total amount of the transaction in major units of `currency`, for example + * `10.1` for EUR 10.10. * @return This builder instance. */ public Builder amount(Float amount) { @@ -106,7 +117,10 @@ public Builder installmentsCount(Long installmentsCount) { /** * Sets the value for {@code paymentType}. * - * @param paymentType Payment type used for the transaction. + * @param paymentType Payment category recorded on a transaction, for example `POS` for a + * point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a + * recurring card payment. These reporting values are separate from the lowercase + * `payment_type` values used to process checkouts. * @return This builder instance. */ public Builder paymentType(com.sumup.sdk.models.PaymentType paymentType) { @@ -143,8 +157,9 @@ public Builder timestamp(java.time.OffsetDateTime timestamp) { /** * Sets the value for {@code transactionCode}. * - * @param transactionCode Transaction code returned by the acquirer/processing entity after - * processing the transaction. + * @param transactionCode SumUp transaction code, for example `TEENSK4W2K`. Use it to look up + * the transaction with the `transaction_code` query parameter. This is separate from the + * transaction's `id` and the card issuer's `auth_code`. * @return This builder instance. */ public Builder transactionCode(String transactionCode) { diff --git a/src/main/java/com/sumup/sdk/models/TransactionCheckoutInfo.java b/src/main/java/com/sumup/sdk/models/TransactionCheckoutInfo.java index 05720f9..46d5dd6 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionCheckoutInfo.java +++ b/src/main/java/com/sumup/sdk/models/TransactionCheckoutInfo.java @@ -9,16 +9,24 @@ public record TransactionCheckoutInfo( */ String authCode, - /** Entry mode of the payment details. */ + /** + * How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present + * payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and + * alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`. + */ com.sumup.sdk.models.EntryMode entryMode, /** Unique code of the registered merchant to whom the payment is made. */ String merchantCode, - /** Amount of the tip (out of the total transaction amount). */ + /** + * Tip included in the total transaction amount, in major units of the transaction's currency. + */ Float tipAmount, - /** Amount of the applicable VAT (out of the total transaction amount). */ + /** + * VAT included in the total transaction amount, in major units of the transaction's currency. + */ Float vatAmount) { /** * Creates a builder for TransactionCheckoutInfo. @@ -54,7 +62,10 @@ public Builder authCode(String authCode) { /** * Sets the value for {@code entryMode}. * - * @param entryMode Entry mode of the payment details. + * @param entryMode How the payment details were captured, for example `CHIP` or `CONTACTLESS` + * for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For + * wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` + * or `BLIK`. * @return This builder instance. */ public Builder entryMode(com.sumup.sdk.models.EntryMode entryMode) { @@ -76,7 +87,8 @@ public Builder merchantCode(String merchantCode) { /** * Sets the value for {@code tipAmount}. * - * @param tipAmount Amount of the tip (out of the total transaction amount). + * @param tipAmount Tip included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder tipAmount(Float tipAmount) { @@ -87,7 +99,8 @@ public Builder tipAmount(Float tipAmount) { /** * Sets the value for {@code vatAmount}. * - * @param vatAmount Amount of the applicable VAT (out of the total transaction amount). + * @param vatAmount VAT included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder vatAmount(Float vatAmount) { diff --git a/src/main/java/com/sumup/sdk/models/TransactionEvent.java b/src/main/java/com/sumup/sdk/models/TransactionEvent.java index 52a0283..d84f7b6 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionEvent.java +++ b/src/main/java/com/sumup/sdk/models/TransactionEvent.java @@ -3,7 +3,7 @@ /** Detailed information about a transaction event. */ public record TransactionEvent( - /** Amount of the event. */ + /** Amount of the event in major units of the associated transaction's currency. */ Double amount, /** Date when the transaction event occurred. */ @@ -12,14 +12,24 @@ public record TransactionEvent( /** Date when the transaction event is due to occur. */ java.time.LocalDate dueDate, - /** Type of the transaction event. */ + /** + * Financial event associated with a transaction. - `PAYOUT`: Funds from the transaction being + * prepared for or included in a merchant payout. Check the event status to determine whether + * they have been paid out. - `REFUND`: Money returned to the payer. - `CHARGE_BACK`: A reversal + * of the payment following a chargeback. - `PAYOUT_DEDUCTION`: An amount deducted from a + * merchant payout, for example to cover a refund or chargeback. + */ com.sumup.sdk.models.TransactionEventType eventType, - /** Unique identifier of the transaction event. */ + /** + * Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting receipt + * details for a specific event. This is separate from the transaction ID and the transaction + * history pagination references. + */ Long id, /** - * Consecutive number of the installment that is paid. Applicable only payout events, i.e. + * Consecutive number of the installment that is paid. Applicable only to payout events, i.e. * `event_type = PAYOUT`. */ Long installmentNumber, @@ -69,7 +79,7 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount Amount of the event. + * @param amount Amount of the event in major units of the associated transaction's currency. * @return This builder instance. */ public Builder amount(Double amount) { @@ -102,7 +112,11 @@ public Builder dueDate(java.time.LocalDate dueDate) { /** * Sets the value for {@code eventType}. * - * @param eventType Type of the transaction event. + * @param eventType Financial event associated with a transaction. - `PAYOUT`: Funds from the + * transaction being prepared for or included in a merchant payout. Check the event status + * to determine whether they have been paid out. - `REFUND`: Money returned to the payer. - + * `CHARGE_BACK`: A reversal of the payment following a chargeback. - `PAYOUT_DEDUCTION`: An + * amount deducted from a merchant payout, for example to cover a refund or chargeback. * @return This builder instance. */ public Builder eventType(com.sumup.sdk.models.TransactionEventType eventType) { @@ -113,7 +127,9 @@ public Builder eventType(com.sumup.sdk.models.TransactionEventType eventType) { /** * Sets the value for {@code id}. * - * @param id Unique identifier of the transaction event. + * @param id Numeric identifier of a transaction event. Use it as `tx_event_id` when requesting + * receipt details for a specific event. This is separate from the transaction ID and the + * transaction history pagination references. * @return This builder instance. */ public Builder id(Long id) { @@ -125,7 +141,7 @@ public Builder id(Long id) { * Sets the value for {@code installmentNumber}. * * @param installmentNumber Consecutive number of the installment that is paid. Applicable only - * payout events, i.e. `event_type = PAYOUT`. + * to payout events, i.e. `event_type = PAYOUT`. * @return This builder instance. */ public Builder installmentNumber(Long installmentNumber) { diff --git a/src/main/java/com/sumup/sdk/models/TransactionEventType.java b/src/main/java/com/sumup/sdk/models/TransactionEventType.java index f2b68d6..eac2a75 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionEventType.java +++ b/src/main/java/com/sumup/sdk/models/TransactionEventType.java @@ -5,7 +5,13 @@ import com.fasterxml.jackson.annotation.JsonValue; import java.util.Objects; -/** Type of the transaction event. */ +/** + * Financial event associated with a transaction. - `PAYOUT`: Funds from the transaction being + * prepared for or included in a merchant payout. Check the event status to determine whether they + * have been paid out. - `REFUND`: Money returned to the payer. - `CHARGE_BACK`: A reversal of the + * payment following a chargeback. - `PAYOUT_DEDUCTION`: An amount deducted from a merchant payout, + * for example to cover a refund or chargeback. + */ public final class TransactionEventType { public static final TransactionEventType PAYOUT = new TransactionEventType("PAYOUT"); public static final TransactionEventType CHARGE_BACK = new TransactionEventType("CHARGE_BACK"); diff --git a/src/main/java/com/sumup/sdk/models/TransactionFull.java b/src/main/java/com/sumup/sdk/models/TransactionFull.java index 61b5294..4e0b1f0 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionFull.java +++ b/src/main/java/com/sumup/sdk/models/TransactionFull.java @@ -3,7 +3,10 @@ /** Full transaction resource with checkout, payout, and event details. */ public record TransactionFull( - /** Total amount of the transaction. */ + /** + * Total amount of the transaction in major units of `currency`, for example `10.1` for EUR + * 10.10. + */ Float amount, /** @@ -29,13 +32,17 @@ public record TransactionFull( /** Details of the ELV card account associated with the transaction. */ com.sumup.sdk.models.ElvCardAccount elvAccount, - /** Entry mode of the payment details. */ + /** + * How the payment details were captured, for example `CHIP` or `CONTACTLESS` for card-present + * payments and `CUSTOMER_ENTRY` for card details entered by the payer. For wallet and + * alternative payment methods, this can identify the method, such as `APPLE_PAY` or `BLIK`. + */ com.sumup.sdk.models.EntryMode entryMode, /** Compact list of events related to the transaction. */ java.util.List events, - /** Transaction SumUp total fee amount. */ + /** Total SumUp transaction fee in major units of the transaction's currency. */ Double feeAmount, /** External transaction identifier supplied by the client. */ @@ -79,7 +86,12 @@ public record TransactionFull( /** Internal SumUp identifier of the merchant. */ Long merchantId, - /** Payment type used for the transaction. */ + /** + * Payment category recorded on a transaction, for example `POS` for a point-of-sale card + * payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. + * These reporting values are separate from the lowercase `payment_type` values used to process + * checkouts. + */ com.sumup.sdk.models.PaymentType paymentType, /** The date of the payout. */ @@ -144,11 +156,15 @@ public record TransactionFull( /** The timestamp of when the transaction was created. */ java.time.OffsetDateTime timestamp, - /** Amount of the tip (out of the total transaction amount). */ + /** + * Tip included in the total transaction amount, in major units of the transaction's currency. + */ Float tipAmount, /** - * Transaction code returned by the acquirer/processing entity after processing the transaction. + * SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the + * `transaction_code` query parameter. This is separate from the transaction's `id` and the card + * issuer's `auth_code`. */ String transactionCode, @@ -158,7 +174,9 @@ public record TransactionFull( /** Email address of the registered user (merchant) to whom the payment is made. */ String username, - /** Amount of the applicable VAT (out of the total transaction amount). */ + /** + * VAT included in the total transaction amount, in major units of the transaction's currency. + */ Float vatAmount, /** List of VAT rates applicable to the transaction. */ @@ -225,7 +243,8 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount Total amount of the transaction. + * @param amount Total amount of the transaction in major units of `currency`, for example + * `10.1` for EUR 10.10. * @return This builder instance. */ public Builder amount(Float amount) { @@ -304,7 +323,10 @@ public Builder elvAccount(com.sumup.sdk.models.ElvCardAccount elvAccount) { /** * Sets the value for {@code entryMode}. * - * @param entryMode Entry mode of the payment details. + * @param entryMode How the payment details were captured, for example `CHIP` or `CONTACTLESS` + * for card-present payments and `CUSTOMER_ENTRY` for card details entered by the payer. For + * wallet and alternative payment methods, this can identify the method, such as `APPLE_PAY` + * or `BLIK`. * @return This builder instance. */ public Builder entryMode(com.sumup.sdk.models.EntryMode entryMode) { @@ -326,7 +348,7 @@ public Builder events(java.util.List events) { /** * Sets the value for {@code feeAmount}. * - * @param feeAmount Transaction SumUp total fee amount. + * @param feeAmount Total SumUp transaction fee in major units of the transaction's currency. * @return This builder instance. */ public Builder feeAmount(Double feeAmount) { @@ -461,7 +483,10 @@ public Builder merchantId(Long merchantId) { /** * Sets the value for {@code paymentType}. * - * @param paymentType Payment type used for the transaction. + * @param paymentType Payment category recorded on a transaction, for example `POS` for a + * point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a + * recurring card payment. These reporting values are separate from the lowercase + * `payment_type` values used to process checkouts. * @return This builder instance. */ public Builder paymentType(com.sumup.sdk.models.PaymentType paymentType) { @@ -636,7 +661,8 @@ public Builder timestamp(java.time.OffsetDateTime timestamp) { /** * Sets the value for {@code tipAmount}. * - * @param tipAmount Amount of the tip (out of the total transaction amount). + * @param tipAmount Tip included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder tipAmount(Float tipAmount) { @@ -647,8 +673,9 @@ public Builder tipAmount(Float tipAmount) { /** * Sets the value for {@code transactionCode}. * - * @param transactionCode Transaction code returned by the acquirer/processing entity after - * processing the transaction. + * @param transactionCode SumUp transaction code, for example `TEENSK4W2K`. Use it to look up + * the transaction with the `transaction_code` query parameter. This is separate from the + * transaction's `id` and the card issuer's `auth_code`. * @return This builder instance. */ public Builder transactionCode(String transactionCode) { @@ -682,7 +709,8 @@ public Builder username(String username) { /** * Sets the value for {@code vatAmount}. * - * @param vatAmount Amount of the applicable VAT (out of the total transaction amount). + * @param vatAmount VAT included in the total transaction amount, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder vatAmount(Float vatAmount) { diff --git a/src/main/java/com/sumup/sdk/models/TransactionHistory.java b/src/main/java/com/sumup/sdk/models/TransactionHistory.java index bea9280..458a86d 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionHistory.java +++ b/src/main/java/com/sumup/sdk/models/TransactionHistory.java @@ -3,7 +3,10 @@ /** Transaction entry returned in history listing responses. */ public record TransactionHistory( - /** Total amount of the transaction. */ + /** + * Total amount of the transaction in major units of `currency`, for example `10.1` for EUR + * 10.10. + */ Float amount, /** Issuing card network of the payment card used for the transaction. */ @@ -23,7 +26,12 @@ public record TransactionHistory( /** Number of installments for a deferred payment. */ Long installmentsCount, - /** Payment type used for the transaction. */ + /** + * Payment category recorded on a transaction, for example `POS` for a point-of-sale card + * payment, `ECOM` for an online card payment, or `RECURRING` for a recurring card payment. + * These reporting values are separate from the lowercase `payment_type` values used to process + * checkouts. + */ com.sumup.sdk.models.PaymentType paymentType, /** Payout date (if paid out at once). */ @@ -47,7 +55,7 @@ public record TransactionHistory( */ String productSummary, - /** Total refunded amount. */ + /** Total amount refunded for this transaction, in major units of the transaction's currency. */ Double refundedAmount, /** @@ -63,7 +71,9 @@ public record TransactionHistory( java.time.OffsetDateTime timestamp, /** - * Transaction code returned by the acquirer/processing entity after processing the transaction. + * SumUp transaction code, for example `TEENSK4W2K`. Use it to look up the transaction with the + * `transaction_code` query parameter. This is separate from the transaction's `id` and the card + * issuer's `auth_code`. */ String transactionCode, @@ -112,7 +122,8 @@ private Builder() {} /** * Sets the value for {@code amount}. * - * @param amount Total amount of the transaction. + * @param amount Total amount of the transaction in major units of `currency`, for example + * `10.1` for EUR 10.10. * @return This builder instance. */ public Builder amount(Float amount) { @@ -179,7 +190,10 @@ public Builder installmentsCount(Long installmentsCount) { /** * Sets the value for {@code paymentType}. * - * @param paymentType Payment type used for the transaction. + * @param paymentType Payment category recorded on a transaction, for example `POS` for a + * point-of-sale card payment, `ECOM` for an online card payment, or `RECURRING` for a + * recurring card payment. These reporting values are separate from the lowercase + * `payment_type` values used to process checkouts. * @return This builder instance. */ public Builder paymentType(com.sumup.sdk.models.PaymentType paymentType) { @@ -260,7 +274,8 @@ public Builder productSummary(String productSummary) { /** * Sets the value for {@code refundedAmount}. * - * @param refundedAmount Total refunded amount. + * @param refundedAmount Total amount refunded for this transaction, in major units of the + * transaction's currency. * @return This builder instance. */ public Builder refundedAmount(Double refundedAmount) { @@ -297,8 +312,9 @@ public Builder timestamp(java.time.OffsetDateTime timestamp) { /** * Sets the value for {@code transactionCode}. * - * @param transactionCode Transaction code returned by the acquirer/processing entity after - * processing the transaction. + * @param transactionCode SumUp transaction code, for example `TEENSK4W2K`. Use it to look up + * the transaction with the `transaction_code` query parameter. This is separate from the + * transaction's `id` and the card issuer's `auth_code`. * @return This builder instance. */ public Builder transactionCode(String transactionCode) { diff --git a/src/main/java/com/sumup/sdk/models/TransactionsHistoryLink.java b/src/main/java/com/sumup/sdk/models/TransactionsHistoryLink.java index 85530ef..3f47306 100644 --- a/src/main/java/com/sumup/sdk/models/TransactionsHistoryLink.java +++ b/src/main/java/com/sumup/sdk/models/TransactionsHistoryLink.java @@ -5,10 +5,13 @@ /** Hypermedia link used for transaction history pagination. */ public record TransactionsHistoryLink( - /** Location. */ + /** + * Query string to use with the transaction history endpoint when requesting the linked page. + * Preserve the returned pagination references and query parameters. + */ String href, - /** Relation. */ + /** Pagination relation indicating which page the link retrieves, for example `next`. */ String rel) { /** * Creates a builder for TransactionsHistoryLink. @@ -29,7 +32,8 @@ private Builder() {} /** * Sets the value for {@code href}. * - * @param href Location. + * @param href Query string to use with the transaction history endpoint when requesting the + * linked page. Preserve the returned pagination references and query parameters. * @return This builder instance. */ public Builder href(String href) { @@ -40,7 +44,7 @@ public Builder href(String href) { /** * Sets the value for {@code rel}. * - * @param rel Relation. + * @param rel Pagination relation indicating which page the link retrieves, for example `next`. * @return This builder instance. */ public Builder rel(String rel) {