chore: synced file(s) with sumup/apis

sdk/src/events.ts

@@ -3,6 +3,7 @@ import type { HTTPClient } from "./client";
 import { EventBase, type EventPayload, UnknownEvent } from "./event";
 import type { Member } from "./types/member";
 import type { Reader } from "./types/reader";
+import type { Role } from "./types/role";
 /** A members.created notification. Call fetchObject() to retrieve the latest Member. */
 export class MemberCreatedEvent extends EventBase<Member> {
   declare readonly type: "members.created";
@@ -23,13 +24,28 @@ export class ReaderCreatedEvent extends EventBase<Reader> {
 export class ReaderDeletedEvent extends EventBase<Reader> {
   declare readonly type: "readers.deleted";
 }
+/** A roles.created notification. Call fetchObject() to retrieve the latest Role. */
+export class RoleCreatedEvent extends EventBase<Role> {
+  declare readonly type: "roles.created";
+}
+/** A roles.deleted notification. Call fetchObject() to retrieve the latest Role. */
+export class RoleDeletedEvent extends EventBase<Role> {
+  declare readonly type: "roles.deleted";
+}
+/** A roles.updated notification. Call fetchObject() to retrieve the latest Role. */
+export class RoleUpdatedEvent extends EventBase<Role> {
+  declare readonly type: "roles.updated";
+}
 /** Known wire event names and their notification classes. */
 export interface EventMap {
   "members.created": MemberCreatedEvent;
   "members.deleted": MemberDeletedEvent;
   "members.updated": MemberUpdatedEvent;
   "readers.created": ReaderCreatedEvent;
   "readers.deleted": ReaderDeletedEvent;
+  "roles.created": RoleCreatedEvent;
+  "roles.deleted": RoleDeletedEvent;
+  "roles.updated": RoleUpdatedEvent;
 }
 /** A recognized event notification or {@link UnknownEvent}. Narrow with instanceof to access a specific resource type. */
 export type EventNotification = EventMap[keyof EventMap] | UnknownEvent;
@@ -49,6 +65,12 @@ export function createEvent(
       return new ReaderCreatedEvent(payload, client);
     case "readers.deleted":
       return new ReaderDeletedEvent(payload, client);
+    case "roles.created":
+      return new RoleCreatedEvent(payload, client);
+    case "roles.deleted":
+      return new RoleDeletedEvent(payload, client);
+    case "roles.updated":
+      return new RoleUpdatedEvent(payload, client);
     default:
       return new UnknownEvent(payload, client);
   }

sdk/src/index.ts

@@ -23,6 +23,9 @@ export {
   MemberUpdatedEvent,
   ReaderCreatedEvent,
   ReaderDeletedEvent,
+  RoleCreatedEvent,
+  RoleDeletedEvent,
+  RoleUpdatedEvent,
 } from "./events";
 export type { EventBody, EventCallback } from "./events-handler";
 export {

sdk/src/resources/checkouts/index.ts

@@ -74,11 +74,11 @@ export type ProcessCheckoutError =
 
 export type CreateApplePaySessionParams = {
   /**
-   * 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.
    */
   context: string;
   /**
-   * The target url to create this apple pay session.
+   * Apple Pay validation URL received as `validationURL` in the browser's `onvalidatemerchant` event.
    */
   target: string;
 };
@@ -111,7 +111,7 @@ export type CreateApplePaySessionError =
  */
 export class Checkouts extends APIResource {
   /**
-   * 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.
    */
   listAvailablePaymentMethods(
     merchantCode: string,
@@ -193,7 +193,7 @@ export class Checkouts extends APIResource {
   }
 
   /**
-   * Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.
+   * Retrieves a checkout by its SumUp `checkout_id`. After processing a payment, returning from a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current `status` before updating your order or displaying the payment outcome to the payer.
    */
   get(checkoutId: string, options?: RequestOptions): Promise<CheckoutSuccess> {
     return this._client.get<CheckoutSuccess>({
@@ -219,7 +219,9 @@ export class Checkouts extends APIResource {
    *
    * 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.
+   * 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.
    */
   process(
     checkoutId: string,

sdk/src/resources/customers/index.ts

@@ -35,15 +35,15 @@ export type ListPaymentInstrumentsResponse = PaymentInstrumentResponse[];
 /**
  * API resource for the Customers endpoints.
  *
- * Allow your regular customers to save their information with the Customers model.
+ * 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.
  *
- * This will prevent re-entering payment instrument information for recurring payments on your platform.
+ * To save a card, create a checkout for that customer with `purpose = SETUP_RECURRING_PAYMENT`, then process it with the payer's consent and mandate details. See the [tokenization guide](https://developer.sumup.com/online-payments/guides/tokenization-with-payment-sdk/).
  *
- * Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.
+ * 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`.
  */
 export class Customers extends APIResource {
   /**
-   * 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.
    */
   create(body: Customer, options?: RequestOptions): Promise<Customer> {
     return this._client.post<Customer>({
@@ -65,7 +65,7 @@ export class Customers extends APIResource {
   }
 
   /**
-   * Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation.
+   * Retrieves a saved customer using the `customer_id` you supplied when creating the customer.
    */
   get(customerId: string, options?: RequestOptions): Promise<Customer> {
     return this._client.get<Customer>({

sdk/src/resources/receipts/index.ts

@@ -14,11 +14,11 @@ export type GetReceiptQueryParams = {
 /**
  * API resource for the Receipts 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.
  */
 export class Receipts extends APIResource {
   /**
-   * 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.
    */
   get(
     transactionId: string,

sdk/src/resources/transactions/index.ts

@@ -14,7 +14,7 @@ import type {
 } from "../../types";
 export type RefundTransactionParams = {
   /**
-   * 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.
    */
   amount?: number;
 };
@@ -85,7 +85,9 @@ export type ListTransactionsV2_1Response = {
  */
 export class Transactions extends APIResource {
   /**
-   * 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.
    */
   refund(
     merchantCode: string,
@@ -145,7 +147,9 @@ export class Transactions extends APIResource {
   }
 
   /**
-   * 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.
    */
   list(
     merchantCode: string,

sdk/src/types/address.ts

@@ -15,7 +15,11 @@ export type Address = {
    *
    */
   post_code?: string;
-  country: CountryCode;
+  country: /**
+   * The ISO3166-1 Alpha-2 code of the address country.
+   *
+   */
+  unknown & CountryCode;
   /**
    * The city of the address.
    *

sdk/src/types/base-person.ts

@@ -43,15 +43,30 @@ export type BasePerson = {
    *
    */
   middle_name?: string;
+  /**
+   * The (mobile) phone number of the individual (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.
+   *
+   */
   phone_number?: PhoneNumber;
   /**
    * 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`.
    *
    */
   relationships?: string[];
+  /**
+   * Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type `owner`.
+   *
+   */
   ownership?: Ownership;
+  /**
+   * The address of the individual.
+   */
   address?: Address;
   identifiers?: PersonalIdentifiers;
+  /**
+   * The Alpha-2 ISO code of the country where the Person is a citizen.
+   *
+   */
   citizenship?: CountryCode;
   /**
    * The Person's nationality. May be an [ISO3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, but legacy data may not conform to this standard.

sdk/src/types/card-response.ts

@@ -14,7 +14,9 @@ export type CardResponse = {
   readonly last_4_digits?: string;
   type?: CardType;
   /**
-   * PAR (Payment account reference) if available for the card.
+   * Payment Account Reference (PAR) defined by [EMVCo](https://www.emvco.com/emv-technologies/payment-tokenisation/). It links a card's primary account number (PAN) with its affiliated payment tokens, allowing transactions made with the physical card and tokenized versions of that card, such as digital wallets, to be correlated when PAR is available.
+   *
+   * This reference cannot be used to initiate a payment and is separate from the saved payment instrument `token` used to process checkouts. Returned only when available for the card; integrations must handle its absence.
    */
   payment_account_reference?: string;
 };

sdk/src/types/checkout-create-request.ts

@@ -10,7 +10,7 @@ import type { HostedCheckout } from "./hosted-checkout";
  */
 export type CheckoutCreateRequest = {
   /**
-   * 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.
    */
   checkout_reference: string;
   /**
@@ -27,7 +27,7 @@ export type CheckoutCreateRequest = {
    */
   description?: string;
   /**
-   * Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.
+   * Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.
    */
   return_url?: string;
   /**

sdk/src/types/checkout.ts

@@ -29,7 +29,7 @@ export type Checkout = {
    */
   description?: string;
   /**
-   * Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.
+   * Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with `event_type` and the checkout `id`. Retrieve the checkout to verify its current status before updating your order. See the [webhook guide](https://developer.sumup.com/online-payments/webhooks/) for the payload and response requirements.
    */
   return_url?: string;
   /**

sdk/src/types/company.ts

@@ -22,10 +22,25 @@ export type Company = {
    *
    */
   merchant_category_code?: string;
+  /**
+   * The category identifying the legal structure of the company or legal entity.
+   *
+   */
   legal_type?: LegalType;
+  /**
+   * The company's primary address.
+   */
   address?: Address;
+  /**
+   * 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`).
+   *
+   */
   trading_address?: Address;
   identifiers?: CompanyIdentifiers;
+  /**
+   * The company's phone number (used for verification) in [E.164](https://en.wikipedia.org/wiki/E.164) format.
+   *
+   */
   phone_number?: PhoneNumber;
   /**
    * HTTP(S) URL of the company's website.

sdk/src/types/customer.ts

@@ -5,11 +5,11 @@ import type { PersonalDetails } from "./personal-details";
 /**
  * Customer
  *
- * 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.
  */
 export type 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.
    */
   customer_id: string;
   personal_details?: PersonalDetails;

sdk/src/types/entry-mode.ts

@@ -3,7 +3,7 @@
 /**
  * Entry Mode
  *
- * 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`.
  */
 export type EntryMode =
   | "BOLETO"

sdk/src/types/payment-instrument-response.ts

@@ -10,7 +10,7 @@ import type { MandateResponse } from "./mandate-response";
  */
 export type PaymentInstrumentResponse = {
   /**
-   * 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.
    */
   readonly token?: string;
   /**

sdk/src/types/payment-type.ts

@@ -3,7 +3,7 @@
 /**
  * Payment Type
  *
- * 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.
  */
 export type PaymentType =
   | "CASH"

sdk/src/types/personal-details.ts

@@ -25,7 +25,7 @@ export type PersonalDetails = {
    */
   phone?: string;
   /**
-   * Date of birth of the customer.
+   * Date of birth of the customer in `YYYY-MM-DD` format, without a time or timezone.
    */
   birth_date?: string;
   /**

sdk/src/types/process-checkout.ts

@@ -36,7 +36,7 @@ export type ProcessCheckout = {
    */
   apple_pay?: Record<string, unknown>;
   /**
-   * 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.
    */
   token?: string;
   /**

sdk/src/types/product.ts

@@ -19,7 +19,7 @@ export type Product = {
    */
   price?: number;
   /**
-   * VAT rate applied to the product price.
+   * VAT rate as a decimal fraction, for example `0.19` for 19%.
    */
   vat_rate?: number;
   /**

sdk/src/types/reader-payment-request-params.ts

@@ -4,7 +4,10 @@ import type { Affiliate } from "./affiliate";
 import type { Amount } from "./amount";
 
 export type ReaderPaymentRequestParams = {
-  affiliate?: Affiliate;
+  affiliate?: /**
+   * Optional caller-supplied context about the integration initiating the payment.
+   */
+  Record<string, unknown> & Affiliate;
   /**
    * Caller-supplied correlation identifier, used as the idempotency key.
    */
@@ -13,5 +16,8 @@ export type ReaderPaymentRequestParams = {
    * Optional tip amount in minor units, added on top of total_amount.
    */
   tip_amount?: number;
-  total_amount: Amount;
+  total_amount: /**
+   * 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.
+   */
+  unknown & Amount;
 };

sdk/src/types/receipt.ts

@@ -6,7 +6,7 @@ import type { ReceiptTransaction } from "./receipt-transaction";
 /**
  * Receipt
  *
- * 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.
  */
 export type Receipt = {
   transaction_data?: ReceiptTransaction;

sdk/src/types/transaction-base.ts

@@ -15,11 +15,11 @@ export type TransactionBase = {
    */
   id?: string;
   /**
-   * 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`.
    */
   transaction_code?: string;
   /**
-   * Total amount of the transaction.
+   * Total amount of the transaction in major units of `currency`, for example `10.1` for EUR 10.10.
    */
   amount?: number;
   currency?: Currency;