diff --git a/openapi.json b/openapi.json index cb75d06..cc14b16 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" @@ -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" ], @@ -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" ], @@ -6242,7 +6243,7 @@ }, "payment_account_reference": { "type": "string", - "description": "PAR (Payment account reference) if available for the card.", + "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" } } @@ -6328,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" }, @@ -6354,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": { @@ -6385,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." }, @@ -6446,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": { @@ -6471,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": { @@ -6493,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." }, @@ -6534,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" }, @@ -6543,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." }, @@ -6632,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": { @@ -6752,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": { @@ -7092,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" } }, @@ -7178,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" }, @@ -7266,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" }, @@ -7305,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": { @@ -7348,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" @@ -7797,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": { @@ -7814,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": { @@ -7837,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": { @@ -7882,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": { @@ -7991,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 } } @@ -8001,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", @@ -8020,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", @@ -8119,7 +8120,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": { @@ -8351,7 +8352,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", @@ -8379,7 +8380,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": { @@ -8394,7 +8395,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 }, @@ -8403,7 +8404,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 }, @@ -8459,7 +8460,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.", @@ -8472,7 +8481,18 @@ "type": "integer" }, "total_amount": { - "$ref": "#/components/schemas/Amount" + "allOf": [ + { + "description": "Amount structure. 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": [ @@ -8975,7 +8995,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", @@ -9504,7 +9532,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", @@ -9522,16 +9551,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": [ @@ -9579,19 +9611,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", @@ -10548,7 +10584,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" } }, @@ -10606,7 +10642,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" } } @@ -10653,7 +10689,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 } } @@ -10684,7 +10720,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", @@ -10721,7 +10757,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": [ @@ -10820,7 +10856,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": [] } @@ -11140,7 +11176,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", @@ -11151,7 +11187,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" @@ -11161,7 +11197,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" @@ -11190,7 +11226,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": [ @@ -11203,7 +11239,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 @@ -11212,7 +11248,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" @@ -11231,7 +11267,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", @@ -11329,7 +11365,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", @@ -11349,13 +11385,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", @@ -11379,27 +11415,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." - } } } } @@ -11657,6 +11672,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 diff --git a/src/SumUp/CheckoutsClient.g.cs b/src/SumUp/CheckoutsClient.g.cs index 4e7a211..85bece7 100644 --- a/src/SumUp/CheckoutsClient.g.cs +++ b/src/SumUp/CheckoutsClient.g.cs @@ -158,8 +158,8 @@ public async Task> CreateAsync(CheckoutCreateRequest body, /// Create an Apple Pay session /// /// Creates an Apple Pay merchant session for the specified checkout. Use this endpoint after the customer selects Apple Pay and before calling ApplePaySession.completeMerchantValidation(...) in the browser. SumUp validates the merchant session request and returns the Apple Pay session object that your frontend should pass to Apple's JavaScript API. - /// Unique identifier of the checkout resource. - /// The data needed to create an apple pay session for a checkout. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. + /// Merchant validation details from the Apple Pay session in the payer's browser. /// Optional per-request overrides. /// Token used to cancel the request. public ApiResponse CreateApplePaySession(string checkoutId, CheckoutsCreateApplePaySessionRequest? body = null, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -217,8 +217,8 @@ public ApiResponse CreateApplePaySession(string checkoutId, Checko /// Create an Apple Pay session /// /// Creates an Apple Pay merchant session for the specified checkout. Use this endpoint after the customer selects Apple Pay and before calling ApplePaySession.completeMerchantValidation(...) in the browser. SumUp validates the merchant session request and returns the Apple Pay session object that your frontend should pass to Apple's JavaScript API. - /// Unique identifier of the checkout resource. - /// The data needed to create an apple pay session for a checkout. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. + /// Merchant validation details from the Apple Pay session in the payer's browser. /// Optional per-request overrides. /// Token used to cancel the request. public async Task> CreateApplePaySessionAsync(string checkoutId, CheckoutsCreateApplePaySessionRequest? body = null, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -276,7 +276,7 @@ public async Task> CreateApplePaySessionAsync(string c /// Deactivate a checkout /// /// Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated. - /// Unique identifier of the checkout resource. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Optional per-request overrides. /// Token used to cancel the request. public ApiResponse Deactivate(string checkoutId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -335,7 +335,7 @@ public ApiResponse Deactivate(string checkoutId, RequestOptions? reque /// Deactivate a checkout /// /// Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated. - /// Unique identifier of the checkout resource. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Optional per-request overrides. /// Token used to cancel the request. public async Task> DeactivateAsync(string checkoutId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -393,8 +393,8 @@ public async Task> DeactivateAsync(string checkoutId, Requ /// /// 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. - /// Unique identifier of the checkout resource. + /// 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. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Optional per-request overrides. /// Token used to cancel the request. public ApiResponse Get(string checkoutId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -447,8 +447,8 @@ public ApiResponse Get(string checkoutId, RequestOptions? reque /// /// 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. - /// Unique identifier of the checkout resource. + /// 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. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Optional per-request overrides. /// Token used to cancel the request. public async Task> GetAsync(string checkoutId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -601,7 +601,7 @@ public async Task>> ListAsync(Checkouts /// /// 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. /// Short unique identifier for the merchant. /// Query and header parameters for the request. /// Optional per-request overrides. @@ -654,7 +654,7 @@ public ApiResponse ListAvailablePa /// /// 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. /// Short unique identifier for the merchant. /// Query and header parameters for the request. /// Optional per-request overrides. @@ -707,8 +707,8 @@ public async Task> Lis /// /// Process a checkout /// - /// :::caution[PCI DSS compliance required] When 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. 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. - /// Unique identifier of the checkout resource. + /// :::caution[PCI DSS compliance required] When 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. 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. 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. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Details of the payment instrument for processing the checkout. /// Optional per-request overrides. /// Token used to cancel the request. @@ -776,8 +776,8 @@ public ApiResponse Process(string checkoutId, ProcessC /// /// Process a checkout /// - /// :::caution[PCI DSS compliance required] When 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. 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. - /// Unique identifier of the checkout resource. + /// :::caution[PCI DSS compliance required] When 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. 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. 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. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Details of the payment instrument for processing the checkout. /// Optional per-request overrides. /// Token used to cancel the request. @@ -846,7 +846,7 @@ public async Task> ProcessAsync(string che /// Update a checkout /// /// 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. - /// Unique identifier of the checkout resource. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Details for updating a checkout resource. /// Optional per-request overrides. /// Token used to cancel the request. @@ -905,7 +905,7 @@ public ApiResponse Update(string checkoutId, CheckoutUpdateRequest bod /// Update a checkout /// /// 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. - /// Unique identifier of the checkout resource. + /// SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout. /// Details for updating a checkout resource. /// Optional per-request overrides. /// Token used to cancel the request. diff --git a/src/SumUp/CustomersClient.g.cs b/src/SumUp/CustomersClient.g.cs index fab380e..36d861e 100644 --- a/src/SumUp/CustomersClient.g.cs +++ b/src/SumUp/CustomersClient.g.cs @@ -18,7 +18,7 @@ public sealed partial class CustomersClient /// /// Client for the Customers API endpoints. /// - /// 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. 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. internal CustomersClient(ApiClient client) { _client = client; @@ -27,7 +27,7 @@ internal CustomersClient(ApiClient client) /// /// 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. /// Details of the customer. /// Optional per-request overrides. /// Token used to cancel the request. @@ -92,7 +92,7 @@ public ApiResponse Create(Customer body, RequestOptions? requestOption /// /// 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. /// Details of the customer. /// Optional per-request overrides. /// Token used to cancel the request. @@ -158,7 +158,7 @@ public async Task> CreateAsync(Customer body, RequestOptio /// Deactivate a payment instrument /// /// Deactivates an identified card payment instrument resource for a customer. - /// Unique identifier of the saved customer resource. + /// The customer_id you supplied when creating the customer. /// Unique token identifying the card saved as a payment instrument resource. /// Optional per-request overrides. /// Token used to cancel the request. @@ -222,7 +222,7 @@ public ApiResponse DeactivatePaymentInstrument(string customerId, /// Deactivate a payment instrument /// /// Deactivates an identified card payment instrument resource for a customer. - /// Unique identifier of the saved customer resource. + /// The customer_id you supplied when creating the customer. /// Unique token identifying the card saved as a payment instrument resource. /// Optional per-request overrides. /// Token used to cancel the request. @@ -285,8 +285,8 @@ public async Task> DeactivatePaymentInstrumentAsync(st /// /// Retrieve a customer /// - /// Retrieves an identified saved customer resource through the unique customer_id parameter, generated upon customer creation. - /// Unique identifier of the saved customer resource. + /// Retrieves a saved customer using the customer_id you supplied when creating the customer. + /// The customer_id you supplied when creating the customer. /// Optional per-request overrides. /// Token used to cancel the request. public ApiResponse Get(string customerId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -344,8 +344,8 @@ public ApiResponse Get(string customerId, RequestOptions? requestOptio /// /// Retrieve a customer /// - /// Retrieves an identified saved customer resource through the unique customer_id parameter, generated upon customer creation. - /// Unique identifier of the saved customer resource. + /// Retrieves a saved customer using the customer_id you supplied when creating the customer. + /// The customer_id you supplied when creating the customer. /// Optional per-request overrides. /// Token used to cancel the request. public async Task> GetAsync(string customerId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -404,7 +404,7 @@ public async Task> GetAsync(string customerId, RequestOpti /// List payment instruments /// /// Lists all payment instrument resources that are saved for an identified customer. - /// Unique identifier of the saved customer resource. + /// The customer_id you supplied when creating the customer. /// Optional per-request overrides. /// Token used to cancel the request. public ApiResponse> ListPaymentInstruments(string customerId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -463,7 +463,7 @@ public ApiResponse> ListPaymentInstrument /// List payment instruments /// /// Lists all payment instrument resources that are saved for an identified customer. - /// Unique identifier of the saved customer resource. + /// The customer_id you supplied when creating the customer. /// Optional per-request overrides. /// Token used to cancel the request. public async Task>> ListPaymentInstrumentsAsync(string customerId, RequestOptions? requestOptions = null, CancellationToken cancellationToken = default) @@ -522,7 +522,7 @@ public async Task>> ListPayme /// Update a customer /// /// Updates an identified saved customer resource's personal details. The request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values. - /// Unique identifier of the saved customer resource. + /// The customer_id you supplied when creating the customer. /// Customer fields to update. /// Optional per-request overrides. /// Token used to cancel the request. @@ -586,7 +586,7 @@ public ApiResponse Update(string customerId, CustomersUpdateRequest bo /// Update a customer /// /// Updates an identified saved customer resource's personal details. The request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values. - /// Unique identifier of the saved customer resource. + /// The customer_id you supplied when creating the customer. /// Customer fields to update. /// Optional per-request overrides. /// Token used to cancel the request. diff --git a/src/SumUp/Events.g.cs b/src/SumUp/Events.g.cs index 35dbebb..7ebc0b0 100644 --- a/src/SumUp/Events.g.cs +++ b/src/SumUp/Events.g.cs @@ -19,6 +19,15 @@ public sealed class ReaderCreatedEvent : EventNotification; /// Sent when a reader is unpaired from a merchant account and is no longer available through the Readers API. public sealed class ReaderDeletedEvent : EventNotification; +/// Sent when a role is created for a merchant account. +public sealed class RoleCreatedEvent : EventNotification; + +/// Sent when a role is deleted for a merchant account. +public sealed class RoleDeletedEvent : EventNotification; + +/// Sent when a role is updated for a merchant account. +public sealed class RoleUpdatedEvent : EventNotification; + public sealed partial class EventsHandler { /// Registers a callback for "members.created", replacing any previous callback for this type. @@ -51,6 +60,24 @@ public EventsHandler OnReaderCreated(Func callback) => Register("readers.deleted", callback); + /// Registers a callback for "roles.created", replacing any previous callback for this type. + /// The callback to await, with the request cancellation token. + /// This handler, for chaining registrations. + public EventsHandler OnRoleCreated(Func callback) => + Register("roles.created", callback); + + /// Registers a callback for "roles.deleted", replacing any previous callback for this type. + /// The callback to await, with the request cancellation token. + /// This handler, for chaining registrations. + public EventsHandler OnRoleDeleted(Func callback) => + Register("roles.deleted", callback); + + /// Registers a callback for "roles.updated", replacing any previous callback for this type. + /// The callback to await, with the request cancellation token. + /// This handler, for chaining registrations. + public EventsHandler OnRoleUpdated(Func callback) => + Register("roles.updated", callback); + } public partial class SumUpClient @@ -62,6 +89,9 @@ public partial class SumUpClient "members.updated" => root.Deserialize()!, "readers.created" => root.Deserialize()!, "readers.deleted" => root.Deserialize()!, + "roles.created" => root.Deserialize()!, + "roles.deleted" => root.Deserialize()!, + "roles.updated" => root.Deserialize()!, _ => root.Deserialize()!, }; } diff --git a/src/SumUp/Models/Address.g.cs b/src/SumUp/Models/Address.g.cs index 3f5922c..4815cb4 100644 --- a/src/SumUp/Models/Address.g.cs +++ b/src/SumUp/Models/Address.g.cs @@ -17,9 +17,8 @@ public sealed partial class Address /// In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile. [JsonPropertyName("commune")] public string? Commune { get; set; } - /// An ISO3166-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. [JsonPropertyName("country")] - public string Country { get; set; } = default!; + public AddressCountry Country { get; set; } = default!; /// A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc. [JsonPropertyName("county")] public string? County { get; set; } diff --git a/src/SumUp/Models/AddressCountry.g.cs b/src/SumUp/Models/AddressCountry.g.cs new file mode 100644 index 0000000..b1a4355 --- /dev/null +++ b/src/SumUp/Models/AddressCountry.g.cs @@ -0,0 +1,9 @@ +// +#nullable enable + +namespace SumUp; + +using System.Text.Json.Serialization; +public sealed partial class AddressCountry +{ +} \ No newline at end of file diff --git a/src/SumUp/Models/BasePerson.g.cs b/src/SumUp/Models/BasePerson.g.cs index 0410fa5..779081d 100644 --- a/src/SumUp/Models/BasePerson.g.cs +++ b/src/SumUp/Models/BasePerson.g.cs @@ -8,7 +8,7 @@ namespace SumUp; /// Base schema for a Person associated with a Merchant. This can be a legal representative, business owner (ultimate beneficial owner), or an officer. A legal representative is the Person who registered the Merchant with SumUp. They should always have a user_id. public sealed partial class 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. [JsonPropertyName("address")] public Address? Address { get; set; } /// The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. @@ -18,7 +18,7 @@ public sealed partial class BasePerson [JsonPropertyName("change_status")] [JsonInclude] public string? ChangeStatus { get; private set; } - /// An ISO3166-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. [JsonPropertyName("citizenship")] public string? Citizenship { get; set; } /// An ISO3166-1 alpha-2 country code representing the country where the Person resides. @@ -43,9 +43,10 @@ public sealed partial class BasePerson /// The Person's nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard. [JsonPropertyName("nationality")] public string? Nationality { get; set; } + /// Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type owner. [JsonPropertyName("ownership")] public Ownership? Ownership { get; set; } - /// A publicly available phone number in E.164 format. + /// The (mobile) phone number of the individual (used for verification) in E.164 format. [JsonPropertyName("phone_number")] public string? PhoneNumber { get; set; } /// A list of roles the Person has in the Merchant or towards SumUp. A Merchant must have at least one Person with the relationship representative. diff --git a/src/SumUp/Models/CardResponse.g.cs b/src/SumUp/Models/CardResponse.g.cs index 4a87324..0233c98 100644 --- a/src/SumUp/Models/CardResponse.g.cs +++ b/src/SumUp/Models/CardResponse.g.cs @@ -11,7 +11,7 @@ public sealed partial class CardResponse [JsonPropertyName("last_4_digits")] [JsonInclude] public string? Last4Digits { get; private set; } - /// PAR (Payment account reference) if available for the card. + /// Payment Account Reference (PAR) defined by EMVCo. 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. [JsonPropertyName("payment_account_reference")] public string? PaymentAccountReference { get; set; } /// Issuing card network of the payment card used for the transaction. diff --git a/src/SumUp/Models/Checkout.g.cs b/src/SumUp/Models/Checkout.g.cs index 8a4c9eb..fa54ccf 100644 --- a/src/SumUp/Models/Checkout.g.cs +++ b/src/SumUp/Models/Checkout.g.cs @@ -40,7 +40,7 @@ public sealed partial class Checkout /// Short unique identifier for the merchant that receives the payment. [JsonPropertyName("merchant_code")] public string? MerchantCode { get; set; } - /// 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 for the payload and response requirements. [JsonPropertyName("return_url")] public string? ReturnUrl { get; set; } /// Current high-level state of the checkout. PENDING means the checkout exists but is not yet completed, PAID means a payment succeeded, FAILED means the latest processing attempt failed, and EXPIRED means the checkout can no longer be processed. diff --git a/src/SumUp/Models/CheckoutCreateRequest.g.cs b/src/SumUp/Models/CheckoutCreateRequest.g.cs index 0aea442..432fd27 100644 --- a/src/SumUp/Models/CheckoutCreateRequest.g.cs +++ b/src/SumUp/Models/CheckoutCreateRequest.g.cs @@ -10,7 +10,7 @@ public sealed partial class CheckoutCreateRequest /// Amount to be charged to the payer, expressed in major units. [JsonPropertyName("amount")] public float Amount { get; set; } - /// 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. [JsonPropertyName("checkout_reference")] public string CheckoutReference { get; set; } = default!; /// Three-letter ISO 4217 currency code of the amount. @@ -34,7 +34,7 @@ public sealed partial class CheckoutCreateRequest /// URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for APMs and recommended for card checkouts that may require 3DS. If it is omitted, the Payment Widget can render the challenge in an iframe instead of using a full-page redirect. [JsonPropertyName("redirect_url")] public string? RedirectUrl { get; set; } - /// 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 for the payload and response requirements. [JsonPropertyName("return_url")] public string? ReturnUrl { get; set; } /// 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. diff --git a/src/SumUp/Models/CheckoutSuccess.g.cs b/src/SumUp/Models/CheckoutSuccess.g.cs index b395b12..598d842 100644 --- a/src/SumUp/Models/CheckoutSuccess.g.cs +++ b/src/SumUp/Models/CheckoutSuccess.g.cs @@ -49,7 +49,7 @@ public sealed partial class CheckoutSuccess /// URL where the payer is redirected after a redirect-based payment or SCA flow completes. [JsonPropertyName("redirect_url")] public string? RedirectUrl { get; set; } - /// 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 for the payload and response requirements. [JsonPropertyName("return_url")] public string? ReturnUrl { get; set; } /// Current high-level state of the checkout. PENDING means the checkout exists but is not yet completed, PAID means a payment succeeded, FAILED means the latest processing attempt failed, and EXPIRED means the checkout can no longer be processed. diff --git a/src/SumUp/Models/CheckoutSuccessTransactionsItem.g.cs b/src/SumUp/Models/CheckoutSuccessTransactionsItem.g.cs index fffc7c1..95f0e5d 100644 --- a/src/SumUp/Models/CheckoutSuccessTransactionsItem.g.cs +++ b/src/SumUp/Models/CheckoutSuccessTransactionsItem.g.cs @@ -6,7 +6,7 @@ namespace SumUp; using System.Text.Json.Serialization; public sealed partial class CheckoutSuccessTransactionsItem { - /// Total amount of the transaction. + /// Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10. [JsonPropertyName("amount")] public float? Amount { get; set; } /// Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. @@ -15,7 +15,7 @@ public sealed partial class CheckoutSuccessTransactionsItem /// Three-letter ISO 4217 currency code of the amount. [JsonPropertyName("currency")] public Currency? Currency { get; set; } - /// 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. [JsonPropertyName("entry_mode")] public EntryMode? EntryMode { get; set; } /// Unique identifier of the transaction. @@ -27,7 +27,7 @@ public sealed partial class CheckoutSuccessTransactionsItem /// Unique code of the registered merchant to whom the payment is made. [JsonPropertyName("merchant_code")] public string? MerchantCode { get; set; } - /// 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. [JsonPropertyName("payment_type")] public PaymentType? PaymentType { get; set; } /// Current status of the transaction. - PENDING: The transaction has been created but its final outcome is not known yet. - SUCCESSFUL: The transaction completed successfully. - CANCELLED: The transaction was cancelled or otherwise reversed before completion. - FAILED: The transaction attempt did not complete successfully. - REFUNDED: The transaction was refunded in full or in part. @@ -36,13 +36,13 @@ public sealed partial class CheckoutSuccessTransactionsItem /// The timestamp of when the transaction was created. [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// 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. [JsonPropertyName("tip_amount")] public float? TipAmount { get; set; } - /// 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. [JsonPropertyName("transaction_code")] public string? TransactionCode { get; set; } - /// 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. [JsonPropertyName("vat_amount")] public float? VatAmount { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/CheckoutTransactionsItem.g.cs b/src/SumUp/Models/CheckoutTransactionsItem.g.cs index 127847f..5e65b3b 100644 --- a/src/SumUp/Models/CheckoutTransactionsItem.g.cs +++ b/src/SumUp/Models/CheckoutTransactionsItem.g.cs @@ -6,7 +6,7 @@ namespace SumUp; using System.Text.Json.Serialization; public sealed partial class CheckoutTransactionsItem { - /// Total amount of the transaction. + /// Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10. [JsonPropertyName("amount")] public float? Amount { get; set; } /// Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. @@ -15,7 +15,7 @@ public sealed partial class CheckoutTransactionsItem /// Three-letter ISO 4217 currency code of the amount. [JsonPropertyName("currency")] public Currency? Currency { get; set; } - /// 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. [JsonPropertyName("entry_mode")] public EntryMode? EntryMode { get; set; } /// Unique identifier of the transaction. @@ -27,7 +27,7 @@ public sealed partial class CheckoutTransactionsItem /// Unique code of the registered merchant to whom the payment is made. [JsonPropertyName("merchant_code")] public string? MerchantCode { get; set; } - /// 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. [JsonPropertyName("payment_type")] public PaymentType? PaymentType { get; set; } /// Current status of the transaction. - PENDING: The transaction has been created but its final outcome is not known yet. - SUCCESSFUL: The transaction completed successfully. - CANCELLED: The transaction was cancelled or otherwise reversed before completion. - FAILED: The transaction attempt did not complete successfully. - REFUNDED: The transaction was refunded in full or in part. @@ -36,13 +36,13 @@ public sealed partial class CheckoutTransactionsItem /// The timestamp of when the transaction was created. [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// 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. [JsonPropertyName("tip_amount")] public float? TipAmount { get; set; } - /// 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. [JsonPropertyName("transaction_code")] public string? TransactionCode { get; set; } - /// 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. [JsonPropertyName("vat_amount")] public float? VatAmount { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/CheckoutsCreateApplePaySessionRequest.g.cs b/src/SumUp/Models/CheckoutsCreateApplePaySessionRequest.g.cs index b7c0981..b3ac889 100644 --- a/src/SumUp/Models/CheckoutsCreateApplePaySessionRequest.g.cs +++ b/src/SumUp/Models/CheckoutsCreateApplePaySessionRequest.g.cs @@ -6,10 +6,10 @@ namespace SumUp; using System.Text.Json.Serialization; public sealed partial class CheckoutsCreateApplePaySessionRequest { - /// 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. [JsonPropertyName("context")] public string Context { get; set; } = default!; - /// The target url to create this apple pay session. + /// Apple Pay validation URL received as validationURL in the browser's onvalidatemerchant event. [JsonPropertyName("target")] public string Target { get; set; } = default!; } \ No newline at end of file diff --git a/src/SumUp/Models/CheckoutsProcessResponse.g.cs b/src/SumUp/Models/CheckoutsProcessResponse.g.cs index c8acecd..9a3eda2 100644 --- a/src/SumUp/Models/CheckoutsProcessResponse.g.cs +++ b/src/SumUp/Models/CheckoutsProcessResponse.g.cs @@ -49,7 +49,7 @@ public sealed partial class CheckoutsProcessResponse /// URL where the payer is redirected after a redirect-based payment or SCA flow completes. [JsonPropertyName("redirect_url")] public string? RedirectUrl { get; set; } - /// 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 for the payload and response requirements. [JsonPropertyName("return_url")] public string? ReturnUrl { get; set; } /// Current high-level state of the checkout. PENDING means the checkout exists but is not yet completed, PAID means a payment succeeded, FAILED means the latest processing attempt failed, and EXPIRED means the checkout can no longer be processed. diff --git a/src/SumUp/Models/CheckoutsProcessResponseTransactionsItem.g.cs b/src/SumUp/Models/CheckoutsProcessResponseTransactionsItem.g.cs index 9181201..af46572 100644 --- a/src/SumUp/Models/CheckoutsProcessResponseTransactionsItem.g.cs +++ b/src/SumUp/Models/CheckoutsProcessResponseTransactionsItem.g.cs @@ -6,7 +6,7 @@ namespace SumUp; using System.Text.Json.Serialization; public sealed partial class CheckoutsProcessResponseTransactionsItem { - /// Total amount of the transaction. + /// Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10. [JsonPropertyName("amount")] public float? Amount { get; set; } /// Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. @@ -15,7 +15,7 @@ public sealed partial class CheckoutsProcessResponseTransactionsItem /// Three-letter ISO 4217 currency code of the amount. [JsonPropertyName("currency")] public Currency? Currency { get; set; } - /// 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. [JsonPropertyName("entry_mode")] public EntryMode? EntryMode { get; set; } /// Unique identifier of the transaction. @@ -27,7 +27,7 @@ public sealed partial class CheckoutsProcessResponseTransactionsItem /// Unique code of the registered merchant to whom the payment is made. [JsonPropertyName("merchant_code")] public string? MerchantCode { get; set; } - /// 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. [JsonPropertyName("payment_type")] public PaymentType? PaymentType { get; set; } /// Current status of the transaction. - PENDING: The transaction has been created but its final outcome is not known yet. - SUCCESSFUL: The transaction completed successfully. - CANCELLED: The transaction was cancelled or otherwise reversed before completion. - FAILED: The transaction attempt did not complete successfully. - REFUNDED: The transaction was refunded in full or in part. @@ -36,13 +36,13 @@ public sealed partial class CheckoutsProcessResponseTransactionsItem /// The timestamp of when the transaction was created. [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// 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. [JsonPropertyName("tip_amount")] public float? TipAmount { get; set; } - /// 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. [JsonPropertyName("transaction_code")] public string? TransactionCode { get; set; } - /// 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. [JsonPropertyName("vat_amount")] public float? VatAmount { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/Company.g.cs b/src/SumUp/Models/Company.g.cs index 434093d..6304140 100644 --- a/src/SumUp/Models/Company.g.cs +++ b/src/SumUp/Models/Company.g.cs @@ -8,7 +8,7 @@ namespace SumUp; /// Information about the company or business. This is legal information that is used for verification. public sealed partial class 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. [JsonPropertyName("address")] public Address? Address { get; set; } /// Object attributes that are modifiable only by SumUp applications. @@ -17,7 +17,7 @@ public sealed partial class Company /// A list of country-specific company identifiers. [JsonPropertyName("identifiers")] public IEnumerable? Identifiers { get; set; } - /// 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. [JsonPropertyName("legal_type")] public string? LegalType { get; set; } /// The merchant category code for the account as specified by ISO18245. MCCs are used to classify businesses based on the goods or services they provide. @@ -26,10 +26,10 @@ public sealed partial class Company /// The company's legal name. [JsonPropertyName("name")] public string? Name { get; set; } - /// A publicly available phone number in E.164 format. + /// The company's phone number (used for verification) in E.164 format. [JsonPropertyName("phone_number")] public string? PhoneNumber { get; set; } - /// 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). [JsonPropertyName("trading_address")] public Address? TradingAddress { get; set; } /// HTTP(S) URL of the company's website. diff --git a/src/SumUp/Models/Customer.g.cs b/src/SumUp/Models/Customer.g.cs index a972925..87cda1c 100644 --- a/src/SumUp/Models/Customer.g.cs +++ b/src/SumUp/Models/Customer.g.cs @@ -4,10 +4,10 @@ namespace SumUp; using System.Text.Json.Serialization; -/// 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 sealed partial class 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. [JsonPropertyName("customer_id")] public string CustomerId { get; set; } = default!; /// Personal details for the customer. diff --git a/src/SumUp/Models/EventValue.g.cs b/src/SumUp/Models/EventValue.g.cs index 7fed7df..964be41 100644 --- a/src/SumUp/Models/EventValue.g.cs +++ b/src/SumUp/Models/EventValue.g.cs @@ -19,7 +19,7 @@ public sealed partial class EventValue /// Fee associated with the transaction event, in major units. [JsonPropertyName("fee_amount")] public float? FeeAmount { get; set; } - /// 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. [JsonPropertyName("id")] public long? Id { get; set; } /// Consecutive number of the installment associated with the event. @@ -34,7 +34,7 @@ public sealed partial class EventValue /// Unique identifier of the transaction. [JsonPropertyName("transaction_id")] public string? TransactionId { get; set; } - /// 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. [JsonPropertyName("type")] public TransactionEventType? Type { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/PaymentInstrumentResponse.g.cs b/src/SumUp/Models/PaymentInstrumentResponse.g.cs index fd26b48..c0fdeca 100644 --- a/src/SumUp/Models/PaymentInstrumentResponse.g.cs +++ b/src/SumUp/Models/PaymentInstrumentResponse.g.cs @@ -20,7 +20,7 @@ public sealed partial class PaymentInstrumentResponse /// Details of the mandate linked to the saved payment instrument. [JsonPropertyName("mandate")] public MandateResponse? Mandate { get; set; } - /// 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. [JsonPropertyName("token")] [JsonInclude] public string? Token { get; private set; } diff --git a/src/SumUp/Models/Person.g.cs b/src/SumUp/Models/Person.g.cs index 7c444a2..44106b7 100644 --- a/src/SumUp/Models/Person.g.cs +++ b/src/SumUp/Models/Person.g.cs @@ -7,7 +7,7 @@ namespace SumUp; using System.Collections.Generic; public sealed partial class 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. [JsonPropertyName("address")] public Address? Address { get; set; } /// The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. @@ -17,7 +17,7 @@ public sealed partial class Person [JsonPropertyName("change_status")] [JsonInclude] public string? ChangeStatus { get; private set; } - /// An ISO3166-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. [JsonPropertyName("citizenship")] public string? Citizenship { get; set; } /// An ISO3166-1 alpha-2 country code representing the country where the Person resides. @@ -42,9 +42,10 @@ public sealed partial class Person /// The Person's nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard. [JsonPropertyName("nationality")] public string? Nationality { get; set; } + /// Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type owner. [JsonPropertyName("ownership")] public Ownership? Ownership { get; set; } - /// A publicly available phone number in E.164 format. + /// The (mobile) phone number of the individual (used for verification) in E.164 format. [JsonPropertyName("phone_number")] public string? PhoneNumber { get; set; } /// A list of roles the Person has in the Merchant or towards SumUp. A Merchant must have at least one Person with the relationship representative. diff --git a/src/SumUp/Models/PersonalDetails.g.cs b/src/SumUp/Models/PersonalDetails.g.cs index 396a6e6..45026f0 100644 --- a/src/SumUp/Models/PersonalDetails.g.cs +++ b/src/SumUp/Models/PersonalDetails.g.cs @@ -10,7 +10,7 @@ public sealed partial class PersonalDetails /// Profile's personal address information. [JsonPropertyName("address")] public AddressLegacy? Address { get; set; } - /// Date of birth of the customer. + /// Date of birth of the customer in YYYY-MM-DD format, without a time or timezone. [JsonPropertyName("birth_date")] public DateOnly? BirthDate { get; set; } /// Email address of the customer. diff --git a/src/SumUp/Models/ProcessCheckout.g.cs b/src/SumUp/Models/ProcessCheckout.g.cs index 038d25d..f1f873e 100644 --- a/src/SumUp/Models/ProcessCheckout.g.cs +++ b/src/SumUp/Models/ProcessCheckout.g.cs @@ -31,7 +31,7 @@ public sealed partial class ProcessCheckout /// Personal details for the customer. [JsonPropertyName("personal_details")] public PersonalDetails? PersonalDetails { get; set; } - /// 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. [JsonPropertyName("token")] public string? Token { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/Product.g.cs b/src/SumUp/Models/Product.g.cs index e525547..df98524 100644 --- a/src/SumUp/Models/Product.g.cs +++ b/src/SumUp/Models/Product.g.cs @@ -34,7 +34,7 @@ public sealed partial class Product /// Total VAT amount for the product quantity. [JsonPropertyName("vat_amount")] public decimal? VatAmount { get; set; } - /// VAT rate applied to the product price. + /// VAT rate as a decimal fraction, for example 0.19 for 19%. [JsonPropertyName("vat_rate")] public decimal? VatRate { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/ReaderPaymentRequestParams.g.cs b/src/SumUp/Models/ReaderPaymentRequestParams.g.cs index ba2d04c..0f3a95d 100644 --- a/src/SumUp/Models/ReaderPaymentRequestParams.g.cs +++ b/src/SumUp/Models/ReaderPaymentRequestParams.g.cs @@ -7,7 +7,7 @@ namespace SumUp; public sealed partial class ReaderPaymentRequestParams { [JsonPropertyName("affiliate")] - public Affiliate? Affiliate { get; set; } + public ReaderPaymentRequestParamsAffiliate? Affiliate { get; set; } /// Caller-supplied correlation identifier, used as the idempotency key. [JsonPropertyName("client_transaction_id")] public string ClientTransactionId { get; set; } = default!; @@ -15,5 +15,5 @@ public sealed partial class ReaderPaymentRequestParams [JsonPropertyName("tip_amount")] public int? TipAmount { get; set; } [JsonPropertyName("total_amount")] - public Amount TotalAmount { get; set; } = default!; + public ReaderPaymentRequestParamsTotalAmount TotalAmount { get; set; } = default!; } \ No newline at end of file diff --git a/src/SumUp/Models/ReaderPaymentRequestParamsAffiliate.g.cs b/src/SumUp/Models/ReaderPaymentRequestParamsAffiliate.g.cs new file mode 100644 index 0000000..8694fb2 --- /dev/null +++ b/src/SumUp/Models/ReaderPaymentRequestParamsAffiliate.g.cs @@ -0,0 +1,13 @@ +// +#nullable enable + +namespace SumUp; + +using System.Text.Json.Serialization; +public sealed partial class ReaderPaymentRequestParamsAffiliate +{ + [JsonPropertyName("app_id")] + public string AppId { get; set; } = default!; + [JsonPropertyName("key")] + public string Key { get; set; } = default!; +} \ No newline at end of file diff --git a/src/SumUp/Models/ReaderPaymentRequestParamsTotalAmount.g.cs b/src/SumUp/Models/ReaderPaymentRequestParamsTotalAmount.g.cs new file mode 100644 index 0000000..df2e929 --- /dev/null +++ b/src/SumUp/Models/ReaderPaymentRequestParamsTotalAmount.g.cs @@ -0,0 +1,15 @@ +// +#nullable enable + +namespace SumUp; + +using System.Text.Json.Serialization; +public sealed partial class ReaderPaymentRequestParamsTotalAmount +{ + /// Currency ISO 4217 code + [JsonPropertyName("currency")] + public string Currency { get; set; } = default!; + /// Amount in minor units (e.g. cents). + [JsonPropertyName("value")] + public int Value { get; set; } +} \ No newline at end of file diff --git a/src/SumUp/Models/Receipt.g.cs b/src/SumUp/Models/Receipt.g.cs index 6ed796b..c24624c 100644 --- a/src/SumUp/Models/Receipt.g.cs +++ b/src/SumUp/Models/Receipt.g.cs @@ -4,7 +4,7 @@ namespace SumUp; using System.Text.Json.Serialization; -/// 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 sealed partial class Receipt { /// Acquirer-specific metadata related to the card authorization. diff --git a/src/SumUp/Models/ReceiptEvent.g.cs b/src/SumUp/Models/ReceiptEvent.g.cs index c8b12cd..a017978 100644 --- a/src/SumUp/Models/ReceiptEvent.g.cs +++ b/src/SumUp/Models/ReceiptEvent.g.cs @@ -10,7 +10,7 @@ public sealed partial class ReceiptEvent /// Amount associated with the transaction event, in major units. [JsonPropertyName("amount")] public string? Amount { get; set; } - /// 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. [JsonPropertyName("id")] public long? Id { get; set; } /// Receipt number associated with the event. @@ -25,7 +25,7 @@ public sealed partial class ReceiptEvent /// Unique identifier of the transaction. [JsonPropertyName("transaction_id")] public string? TransactionId { get; set; } - /// 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. [JsonPropertyName("type")] public TransactionEventType? Type { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/TransactionBase.g.cs b/src/SumUp/Models/TransactionBase.g.cs index fafac3a..b45efe7 100644 --- a/src/SumUp/Models/TransactionBase.g.cs +++ b/src/SumUp/Models/TransactionBase.g.cs @@ -7,7 +7,7 @@ namespace SumUp; /// Core details shared by transaction resources. public sealed partial class TransactionBase { - /// Total amount of the transaction. + /// Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10. [JsonPropertyName("amount")] public float? Amount { get; set; } /// Three-letter ISO 4217 currency code of the amount. @@ -19,7 +19,7 @@ public sealed partial class TransactionBase /// Number of installments for a deferred payment. [JsonPropertyName("installments_count")] public int? InstallmentsCount { get; set; } - /// 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. [JsonPropertyName("payment_type")] public PaymentType? PaymentType { get; set; } /// Current status of the transaction. - PENDING: The transaction has been created but its final outcome is not known yet. - SUCCESSFUL: The transaction completed successfully. - CANCELLED: The transaction was cancelled or otherwise reversed before completion. - FAILED: The transaction attempt did not complete successfully. - REFUNDED: The transaction was refunded in full or in part. @@ -28,7 +28,7 @@ public sealed partial class TransactionBase /// The timestamp of when the transaction was created. [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// 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. [JsonPropertyName("transaction_code")] public string? TransactionCode { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/TransactionCheckoutInfo.g.cs b/src/SumUp/Models/TransactionCheckoutInfo.g.cs index e869f22..3e40520 100644 --- a/src/SumUp/Models/TransactionCheckoutInfo.g.cs +++ b/src/SumUp/Models/TransactionCheckoutInfo.g.cs @@ -10,16 +10,16 @@ public sealed partial class TransactionCheckoutInfo /// Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. [JsonPropertyName("auth_code")] public string? AuthCode { get; set; } - /// 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. [JsonPropertyName("entry_mode")] public EntryMode? EntryMode { get; set; } /// Unique code of the registered merchant to whom the payment is made. [JsonPropertyName("merchant_code")] public string? MerchantCode { get; set; } - /// 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. [JsonPropertyName("tip_amount")] public float? TipAmount { get; set; } - /// 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. [JsonPropertyName("vat_amount")] public float? VatAmount { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Models/TransactionEvent.g.cs b/src/SumUp/Models/TransactionEvent.g.cs index 25dd6da..c56629a 100644 --- a/src/SumUp/Models/TransactionEvent.g.cs +++ b/src/SumUp/Models/TransactionEvent.g.cs @@ -7,7 +7,7 @@ namespace SumUp; /// Detailed information about a transaction event. public sealed partial class TransactionEvent { - /// Amount of the event. + /// Amount of the event in major units of the associated transaction's currency. [JsonPropertyName("amount")] public decimal? Amount { get; set; } /// Date when the transaction event occurred. @@ -16,13 +16,13 @@ public sealed partial class TransactionEvent /// Date when the transaction event is due to occur. [JsonPropertyName("due_date")] public DateOnly? DueDate { get; set; } - /// 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. [JsonPropertyName("event_type")] public TransactionEventType? EventType { get; set; } - /// 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. [JsonPropertyName("id")] public long? Id { get; set; } - /// Consecutive number of the installment that is paid. Applicable only payout events, i.e. event_type = PAYOUT. + /// Consecutive number of the installment that is paid. Applicable only to payout events, i.e. event_type = PAYOUT. [JsonPropertyName("installment_number")] public int? InstallmentNumber { get; set; } /// Status of the transaction event. Not every value is used for every event type. - PENDING: The event has been created but is not final yet. Used for events that are still being processed and whose final outcome is not known yet. - SCHEDULED: The event is planned for a future payout cycle but has not been executed yet. This applies to payout events before money is actually sent out. - RECONCILED: The underlying payment has been matched with settlement data and is ready to continue through payout processing, but the funds have not been paid out yet. This applies to payout events. - PAID_OUT: The payout event has been completed and the funds were included in a merchant payout. - REFUNDED: A refund event has been accepted and recorded in the refund flow. This is the status returned for refund events once the transaction amount is being or has been returned to the payer. - SUCCESSFUL: The event completed successfully. Use this as the generic terminal success status for event types that do not expose a more specific business outcome such as PAID_OUT or REFUNDED. - FAILED: The event could not be completed. Typical examples are a payout that could not be executed or an event that was rejected during processing. diff --git a/src/SumUp/Models/TransactionFull.g.cs b/src/SumUp/Models/TransactionFull.g.cs index 23d0d28..7a891f3 100644 --- a/src/SumUp/Models/TransactionFull.g.cs +++ b/src/SumUp/Models/TransactionFull.g.cs @@ -8,7 +8,7 @@ namespace SumUp; /// Full transaction resource with checkout, payout, and event details. public sealed partial class TransactionFull { - /// Total amount of the transaction. + /// Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10. [JsonPropertyName("amount")] public float? Amount { get; set; } /// Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments. @@ -29,13 +29,13 @@ public sealed partial class TransactionFull /// Details of the ELV card account associated with the transaction. [JsonPropertyName("elv_account")] public ElvCardAccount? ElvAccount { get; set; } - /// 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. [JsonPropertyName("entry_mode")] public EntryMode? EntryMode { get; set; } /// Compact list of events related to the transaction. [JsonPropertyName("events")] public IEnumerable? Events { get; set; } - /// Transaction SumUp total fee amount. + /// Total SumUp transaction fee in major units of the transaction's currency. [JsonPropertyName("fee_amount")] public decimal? FeeAmount { get; set; } /// External transaction identifier supplied by the client. @@ -71,7 +71,7 @@ public sealed partial class TransactionFull /// Internal SumUp identifier of the merchant. [JsonPropertyName("merchant_id")] public long? MerchantId { get; set; } - /// 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. [JsonPropertyName("payment_type")] public PaymentType? PaymentType { get; set; } /// The date of the payout. @@ -113,10 +113,10 @@ public sealed partial class TransactionFull /// The timestamp of when the transaction was created. [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// 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. [JsonPropertyName("tip_amount")] public float? TipAmount { get; set; } - /// 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. [JsonPropertyName("transaction_code")] public string? TransactionCode { get; set; } /// Detailed list of events related to the transaction. @@ -125,7 +125,7 @@ public sealed partial class TransactionFull /// Email address of the registered user (merchant) to whom the payment is made. [JsonPropertyName("username")] public string? Username { get; set; } - /// 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. [JsonPropertyName("vat_amount")] public float? VatAmount { get; set; } /// List of VAT rates applicable to the transaction. diff --git a/src/SumUp/Models/TransactionHistory.g.cs b/src/SumUp/Models/TransactionHistory.g.cs index 6d64172..e15907e 100644 --- a/src/SumUp/Models/TransactionHistory.g.cs +++ b/src/SumUp/Models/TransactionHistory.g.cs @@ -7,7 +7,7 @@ namespace SumUp; /// Transaction entry returned in history listing responses. public sealed partial class TransactionHistory { - /// Total amount of the transaction. + /// Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10. [JsonPropertyName("amount")] public float? Amount { get; set; } /// Issuing card network of the payment card used for the transaction. @@ -25,7 +25,7 @@ public sealed partial class TransactionHistory /// Number of installments for a deferred payment. [JsonPropertyName("installments_count")] public int? InstallmentsCount { get; set; } - /// 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. [JsonPropertyName("payment_type")] public PaymentType? PaymentType { get; set; } /// Payout date (if paid out at once). @@ -46,7 +46,7 @@ public sealed partial class TransactionHistory /// Short description of the payment. The value is taken from the description property of the related checkout resource. [JsonPropertyName("product_summary")] public string? ProductSummary { get; set; } - /// Total refunded amount. + /// Total amount refunded for this transaction, in major units of the transaction's currency. [JsonPropertyName("refunded_amount")] public decimal? RefundedAmount { get; set; } /// Current status of the transaction. - PENDING: The transaction has been created but its final outcome is not known yet. - SUCCESSFUL: The transaction completed successfully. - CANCELLED: The transaction was cancelled or otherwise reversed before completion. - FAILED: The transaction attempt did not complete successfully. - REFUNDED: The transaction was refunded in full or in part. @@ -55,7 +55,7 @@ public sealed partial class TransactionHistory /// The timestamp of when the transaction was created. [JsonPropertyName("timestamp")] public DateTimeOffset? Timestamp { get; set; } - /// 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. [JsonPropertyName("transaction_code")] public string? TransactionCode { get; set; } /// Unique identifier of the transaction. diff --git a/src/SumUp/Models/TransactionsHistoryLink.g.cs b/src/SumUp/Models/TransactionsHistoryLink.g.cs index 85b66e1..4c61f49 100644 --- a/src/SumUp/Models/TransactionsHistoryLink.g.cs +++ b/src/SumUp/Models/TransactionsHistoryLink.g.cs @@ -7,10 +7,10 @@ namespace SumUp; /// Hypermedia link used for transaction history pagination. public sealed partial class TransactionsHistoryLink { - /// Location. + /// Query string to use with the transaction history endpoint when requesting the linked page. Preserve the returned pagination references and query parameters. [JsonPropertyName("href")] public string Href { get; set; } = default!; - /// Relation. + /// Pagination relation indicating which page the link retrieves, for example next. [JsonPropertyName("rel")] public string Rel { get; set; } = default!; } \ No newline at end of file diff --git a/src/SumUp/Models/TransactionsRefundRequest.g.cs b/src/SumUp/Models/TransactionsRefundRequest.g.cs index 7362e0b..d2c8ffb 100644 --- a/src/SumUp/Models/TransactionsRefundRequest.g.cs +++ b/src/SumUp/Models/TransactionsRefundRequest.g.cs @@ -7,7 +7,7 @@ namespace SumUp; /// Optional amount for partial refunds of transactions. public sealed partial class TransactionsRefundRequest { - /// 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. [JsonPropertyName("amount")] public float? Amount { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Options/CheckoutsListAvailablePaymentMethodsOptions.g.cs b/src/SumUp/Options/CheckoutsListAvailablePaymentMethodsOptions.g.cs index c7a3fee..4a1d02f 100644 --- a/src/SumUp/Options/CheckoutsListAvailablePaymentMethodsOptions.g.cs +++ b/src/SumUp/Options/CheckoutsListAvailablePaymentMethodsOptions.g.cs @@ -8,8 +8,8 @@ namespace SumUp; /// public sealed partial class CheckoutsListAvailablePaymentMethodsOptions { - /// The amount for which the payment methods should be eligible, in major units. + /// Payment amount in major units, for example 9.99 for EUR 9.99. When filtering by amount, also provide currency. public decimal? Amount { get; set; } - /// The currency for which the payment methods should be eligible. + /// Three-letter ISO 4217 currency code for which the payment methods should be eligible, for example EUR. public string? Currency { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Options/CheckoutsListOptions.g.cs b/src/SumUp/Options/CheckoutsListOptions.g.cs index f59c1d4..06242bc 100644 --- a/src/SumUp/Options/CheckoutsListOptions.g.cs +++ b/src/SumUp/Options/CheckoutsListOptions.g.cs @@ -8,6 +8,6 @@ namespace SumUp; /// public sealed partial class CheckoutsListOptions { - /// Filters the list of checkout resources by the unique reference of the checkout. + /// Filters checkouts by the merchant-defined checkout_reference supplied when creating the checkout. This is separate from the SumUp-generated checkout id. public string? CheckoutReference { get; set; } } \ No newline at end of file diff --git a/src/SumUp/Options/TransactionsListOptions.g.cs b/src/SumUp/Options/TransactionsListOptions.g.cs index 14abe9a..9f726bb 100644 --- a/src/SumUp/Options/TransactionsListOptions.g.cs +++ b/src/SumUp/Options/TransactionsListOptions.g.cs @@ -11,13 +11,13 @@ public sealed partial class TransactionsListOptions { /// Retrieves the transaction resource with the specified transaction code. public string? TransactionCode { get; set; } - /// Specifies the order in which the returned results are displayed. + /// Sort direction for the transaction history. Use ascending or descending; the default is ascending. public string? Order { get; set; } - /// Specifies the maximum number of results per page. Value must be a positive integer and if not specified, will return 10 results. + /// Maximum number of transactions per page. Must be a positive integer. Defaults to 10 when omitted; a page can contain fewer results. public int? Limit { get; set; } - /// Filters the returned results by user email. + /// Filters transactions by user email. For multiple values, repeat the query parameter, for example users[]=first@example.com&users[]=second@example.com. public IEnumerable? Users { get; set; } - /// Filters the returned results by the specified list of final statuses of the transactions. + /// Filters transactions by the listed final statuses. For multiple values, repeat the query parameter, for example statuses[]=SUCCESSFUL&statuses[]=REFUNDED. public IEnumerable? Statuses { get; set; } /// Filters the returned results by the specified list of payment types used for the transactions. public IEnumerable? PaymentTypes { get; set; } @@ -29,10 +29,10 @@ public sealed partial class TransactionsListOptions public DateTimeOffset? ChangesSince { get; set; } /// Filters the results by the creation time of resources and returns only transactions that are created *before* the specified timestamp (in ISO8601 format). public DateTimeOffset? NewestTime { get; set; } - /// 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). + /// 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. public string? NewestRef { get; set; } /// Filters the results by the creation time of resources and returns only transactions that are created *at or after* the specified timestamp (in ISO8601 format). public DateTimeOffset? OldestTime { get; set; } - /// 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). + /// 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. public string? OldestRef { get; set; } } \ No newline at end of file diff --git a/src/SumUp/ReceiptsClient.g.cs b/src/SumUp/ReceiptsClient.g.cs index b08b142..85603b9 100644 --- a/src/SumUp/ReceiptsClient.g.cs +++ b/src/SumUp/ReceiptsClient.g.cs @@ -17,7 +17,7 @@ public sealed partial class ReceiptsClient /// /// Client for the Receipts API endpoints. /// - /// 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. internal ReceiptsClient(ApiClient client) { _client = client; @@ -26,7 +26,7 @@ internal ReceiptsClient(ApiClient client) /// /// 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. /// SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD. /// Query and header parameters for the request. /// Optional per-request overrides. @@ -89,7 +89,7 @@ public ApiResponse Get(string transactionId, ReceiptsGetOptions options /// /// 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. /// SumUp unique transaction ID or transaction code, e.g. TS7HDYLSKD. /// Query and header parameters for the request. /// Optional per-request overrides. diff --git a/src/SumUp/TransactionsClient.g.cs b/src/SumUp/TransactionsClient.g.cs index 0dc4399..f32a91e 100644 --- a/src/SumUp/TransactionsClient.g.cs +++ b/src/SumUp/TransactionsClient.g.cs @@ -147,7 +147,7 @@ public async Task> GetAsync(string merchantCode, Tr /// /// 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. /// Short unique identifier for the merchant. /// Query and header parameters for the request. /// Optional per-request overrides. @@ -216,7 +216,7 @@ public ApiResponse List(string merchantCode, Transacti /// /// 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. /// Short unique identifier for the merchant. /// Query and header parameters for the request. /// Optional per-request overrides. @@ -285,7 +285,7 @@ public async Task> ListAsync(string mercha /// /// 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. /// Short unique identifier for the merchant. /// Unique identifier of the transaction. /// Optional amount for partial refunds. @@ -361,7 +361,7 @@ public ApiResponse Refund(string merchantCode, string transactionI /// /// 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. /// Short unique identifier for the merchant. /// Unique identifier of the transaction. /// Optional amount for partial refunds.