@wix/auto_sdk_payments_payouts 1.0.0 → 1.0.2

package/build/cjs/index.typings.d.ts

@@ -1,66 +1,82 @@
 import { NonNullablePaths } from '@wix/sdk-types';
 
 /**
- * A payout is one outgoing transfer of funds from a Wix Payments merchant account
- * to the merchant's bank account. The entity carries the amount, lifecycle status,
- * estimated arrival date, and (when applicable) failure information.
+ * A payout is an outgoing transfer of funds from a Wix Payments account to the
+ * merchant's bank account. Each payout has an amount, a lifecycle status, an
+ * estimated arrival date, and (when applicable) a failure reason.
  */
 interface Payout {
     /**
-     * Unique identifier of the payout. Immutable.
+     * Payout ID.
      * @format GUID
      */
     _id?: string;
     /**
-     * ID of the Wix Payments account that owns this payout.
+     * ID of the Wix Payments account that owns the payout. Retrieve account IDs
+     * from the Accounts API.
      * @format GUID
      */
     accountId?: string;
     /**
-     * ID of the Wix Payments account profile this payout belongs to.
-     * A Wix Payments account has one or more profiles; each profile has its own
-     * balance and its own payouts. Most merchants have a single profile.
+     * ID of the Wix Payments account profile that owns the payout.
+     *
+     * A Wix Payments account has 1 or more profiles. Each profile has its own
+     * balance and its own payouts. Most merchants have 1 profile. Retrieve
+     * profile IDs from the Accounts API.
      * @format GUID
      */
     accountProfileId?: string;
     /**
-     * Date the payout was created, in advance of the underlying transfer being
-     * initiated at the bank rail. Once initiated, the funds typically reach the
-     * merchant's bank account within 3-5 business days, depending on the receiving bank.
+     * Date and time the payout was created.
+     *
+     * The payout is created before the underlying transfer is initiated at the
+     * bank. Once initiated, the funds typically reach the merchant's bank account
+     * within 3 to 5 business days, depending on the receiving bank.
      */
     _createdDate?: Date | null;
-    /** Amount of funds transferred to the merchant's bank account. */
+    /** Amount of the transfer to the merchant's bank account. */
     amount?: Money;
     /**
-     * Lifecycle status of the payout. `SENT` means the bank rail accepted the transfer
-     * for delivery; `FAILED` means the receiving bank rejected the transfer. The rail
-     * does not provide a delivery acknowledgement, so `SENT` is not the same as
-     * "delivered to the merchant" — see the per-value documentation on `PayoutStatus`.
+     * Lifecycle status of the payout.
+     *
+     * `SENT` means the bank rail accepted the transfer for delivery. `FAILED` means
+     * the receiving bank rejected the transfer.
+     *
+     * A `SENT` status doesn't guarantee that the funds were delivered to the
+     * merchant. The bank rail doesn't provide a delivery acknowledgement, and a
+     * payout in `SENT` can later transition to `FAILED` if the receiving bank
+     * rejects the transfer. See the per-value documentation on `PayoutStatus` for
+     * details.
      */
     status?: PayoutStatusWithLiterals;
     /**
-     * Estimated date for when the funds should arrive at the merchant's bank, returned
-     * by the underlying bank rail when available. This is a prediction, not a guarantee —
-     * actual arrival depends on the receiving bank's processing and may be later.
+     * Estimated date for when the funds should arrive at the merchant's bank
+     * account, in `YYYY-MM-DD` format.
+     *
+     * The estimated arrival date is a prediction, not a guarantee. Actual arrival
+     * depends on the receiving bank's processing and may be later.
      * @format LOCAL_DATE
      */
     estimatedArrivalDateV2?: string | null;
     /**
-     * Set only when `status` is `FAILED`. Indicates why the bank rail rejected the transfer.
-     * The codes are a Wix Payments unified set; the original provider-specific reason is not exposed.
+     * Reason the bank rail rejected the transfer.
+     *
+     * Returned only when `status` is `FAILED`.
      */
     failureReason?: PayoutFailureReason;
     /**
-     * Reference returned by the bank rail (e.g. ACH trace number, SEPA reference) once
-     * the transfer is initiated. Use it for reconciliation against the merchant's bank
-     * statement. Empty when the rail has not yet returned a reference.
+     * Reference returned by the bank rail once the transfer is initiated. For
+     * example, an ACH trace number or a SEPA reference. Use this value to
+     * reconcile against the merchant's bank statement.
+     *
+     * Empty until the bank rail returns a reference.
      * @maxLength 500
      */
     bankTransferReference?: string | null;
     /**
-     * `true` if the payout's `amount` includes funds that originate from a Wix Capital
-     * advance the merchant has taken out. `false` if the amount is composed only of
-     * regular sales proceeds.
+     * Whether the payout `amount` includes funds from a Wix Capital cash advance
+     * taken out by the merchant. If `false`, the amount comes only from the
+     * merchant's sales proceeds.
      */
     cashAdvanceIncluded?: boolean;
 }
@@ -84,56 +100,56 @@ interface Money {
 }
 /** Lifecycle status of a payout. */
 declare enum PayoutStatus {
-    /** Default value. Not returned by the API. */
+    /** Unknown payout status. Not returned by the API. */
     UNKNOWN = "UNKNOWN",
     /**
-     * The bank rail accepted the transfer. Funds are en route to the merchant's bank,
-     * but acceptance is not the same as delivery — a `SENT` payout can still flip to
-     * `FAILED` if the receiving bank rejects the transfer (the rail's return window
-     * is up to 60 days for ACH and up to 13 months for SEPA).
+     * The bank rail accepted the transfer. Funds are en route to the merchant's
+     * bank account.
+     *
+     * Acceptance isn't the same as delivery. A `SENT` payout can still
+     * transition to `FAILED` if the receiving bank rejects the transfer. The
+     * bank rail's return window is up to 60 days for ACH and up to 13 months
+     * for SEPA.
      */
     SENT = "SENT",
     /**
-     * The transfer was rejected by the receiving bank. See `failure_reason` for the cause;
-     * the funds remain in the merchant's Wix Payments balance.
+     * The bank rail rejected the transfer. See `failureReason` for the cause.
+     * The funds remain in the merchant's Wix Payments balance.
      */
     FAILED = "FAILED"
 }
 /** @enumType */
 type PayoutStatusWithLiterals = PayoutStatus | 'UNKNOWN' | 'SENT' | 'FAILED';
-/**
- * Carries the reason a payout failed. Wraps the `PayoutFailureCode` enum to leave room
- * for future fields (e.g. a human-readable message); new clients should still read
- * `failure_reason.code` for the enum value.
- */
+/** Reason a payout failed. */
 interface PayoutFailureReason {
     /** Why the bank rail rejected the transfer. */
     code?: PayoutFailureCodeWithLiterals;
 }
 /**
- * Reasons a payout can fail. Values describe real-world bank-rail conditions and
- * are mapped from the underlying provider into a Wix Payments unified vocabulary.
+ * Possible reasons for a payout failure. Each value describes a real-world
+ * bank-rail condition.
  */
 declare enum PayoutFailureCode {
     /**
-     * Generic failure with no more specific reason available from the bank rail.
-     * Note: this value is also returned when no failure reason is known — clients
-     * cannot distinguish "unknown" from "generic" using this code alone.
+     * Generic failure with no more specific reason available from the bank
+     * rail. This value is also returned when no failure reason is known.
+     * Clients can't distinguish "unknown" from "generic" using this code alone.
      */
     GENERIC_PAYOUT_FAILURE = "GENERIC_PAYOUT_FAILURE",
     /**
-     * The merchant's bank account is closed. The merchant must provide new bank
-     * account details before further payouts can succeed.
+     * The merchant's bank account is closed. The merchant must provide new
+     * bank account details before further payouts can succeed.
      */
     ACCOUNT_CLOSED = "ACCOUNT_CLOSED",
     /**
-     * The merchant's bank account is frozen (e.g. due to a hold placed by the bank).
-     * The merchant must resolve the hold with their bank before further payouts can succeed.
+     * The merchant's bank account is frozen, for example due to a hold placed
+     * by the bank. The merchant must resolve the hold with their bank before
+     * further payouts can succeed.
      */
     ACCOUNT_FROZEN = "ACCOUNT_FROZEN",
     /**
-     * The merchant's bank account is restricted from receiving the transfer
-     * (e.g. account type or status does not permit incoming credits).
+     * The merchant's bank account is restricted from receiving the transfer.
+     * For example, the account type or status doesn't permit incoming credits.
      */
     BANK_ACCOUNT_RESTRICTED = "BANK_ACCOUNT_RESTRICTED",
     /**
@@ -142,38 +158,42 @@ declare enum PayoutFailureCode {
      */
     BANK_OWNERSHIP_CHANGED = "BANK_OWNERSHIP_CHANGED",
     /**
-     * The receiving bank could not process the transfer for an unspecified reason.
-     * A subsequent payout attempt may succeed.
+     * The receiving bank couldn't process the transfer for an unspecified
+     * reason. A subsequent payout attempt may succeed.
      */
     COULD_NOT_PROCESS = "COULD_NOT_PROCESS",
     /**
-     * The merchant's bank declined the debit authorisation associated with the transfer.
-     * The merchant must contact their bank to authorise Wix Payments payouts.
+     * The merchant's bank declined the debit authorisation associated with the
+     * transfer. The merchant must contact their bank to authorise Wix Payments
+     * payouts.
      */
     DEBIT_NOT_AUTHORIZED = "DEBIT_NOT_AUTHORIZED",
     /**
-     * The account holder name on file does not match what the receiving bank has on record.
-     * The merchant must correct the account holder name.
+     * The account holder name on file doesn't match the name the receiving
+     * bank has on record. The merchant must correct the account holder name.
      */
     INCORRECT_ACCOUNT_HOLDER_NAME = "INCORRECT_ACCOUNT_HOLDER_NAME",
     /** The city in the bank account details is invalid for the receiving bank. */
     INVALID_ACCOUNT_DETAILS_CITY = "INVALID_ACCOUNT_DETAILS_CITY",
-    /** The bank account number is invalid (wrong format or does not exist). */
+    /**
+     * The bank account number is invalid. The format is wrong or the account
+     * doesn't exist.
+     */
     INVALID_ACCOUNT_NUMBER = "INVALID_ACCOUNT_NUMBER",
-    /** The payout currency is not supported by the receiving bank account. */
+    /** The payout currency isn't supported by the receiving bank account. */
     INVALID_CURRENCY = "INVALID_CURRENCY",
-    /** The routing number (US) is invalid or does not match the receiving bank. */
+    /** The routing number (US) is invalid or doesn't match the receiving bank. */
     INVALID_ROUTING_NUMBER = "INVALID_ROUTING_NUMBER",
-    /** The sort code (UK) is invalid or does not match the receiving bank. */
+    /** The sort code (UK) is invalid or doesn't match the receiving bank. */
     INVALID_SORT_CODE = "INVALID_SORT_CODE",
     /**
-     * No bank account is on file for the merchant.
-     * The merchant must add bank details before payouts can succeed.
+     * No bank account is on file for the merchant. The merchant must add bank
+     * details before payouts can succeed.
      */
     NO_ACCOUNT = "NO_ACCOUNT",
     /**
-     * A technical error at the bank rail prevented the transfer.
-     * A subsequent payout attempt may succeed.
+     * A technical error at the bank rail prevented the transfer. A subsequent
+     * payout attempt may succeed.
      */
     TECHNICAL_ERROR = "TECHNICAL_ERROR"
 }
@@ -181,23 +201,30 @@ declare enum PayoutFailureCode {
 type PayoutFailureCodeWithLiterals = PayoutFailureCode | 'GENERIC_PAYOUT_FAILURE' | 'ACCOUNT_CLOSED' | 'ACCOUNT_FROZEN' | 'BANK_ACCOUNT_RESTRICTED' | 'BANK_OWNERSHIP_CHANGED' | 'COULD_NOT_PROCESS' | 'DEBIT_NOT_AUTHORIZED' | 'INCORRECT_ACCOUNT_HOLDER_NAME' | 'INVALID_ACCOUNT_DETAILS_CITY' | 'INVALID_ACCOUNT_NUMBER' | 'INVALID_CURRENCY' | 'INVALID_ROUTING_NUMBER' | 'INVALID_SORT_CODE' | 'NO_ACCOUNT' | 'TECHNICAL_ERROR';
 interface ListPayoutsRequest {
     /**
-     * ID of the Wix Payments account whose payouts to list.
+     * ID of the Wix Payments account whose payouts to list. Retrieve account
+     * IDs from the Accounts API.
      * @format GUID
      */
     accountId: string;
     /**
-     * Optional. When omitted, payouts across all profiles of the account are returned.
-     * When set, only payouts belonging to the specified account profile are returned.
+     * ID of the Wix Payments account profile to filter by.
+     *
+     * When omitted, payouts across all profiles of the account are returned.
+     * Retrieve profile IDs from the Accounts API.
      * @format GUID
      */
     accountProfileId?: string | null;
-    /** Optional. Returns only payouts created before this timestamp. */
+    /** Returns only payouts created before this date and time. */
     createdBefore?: Date | null;
-    /** Optional. Returns only payouts created after this timestamp. */
+    /** Returns only payouts created after this date and time. */
     createdAfter?: Date | null;
-    /** Optional. Sorting. Only `created_date` is supported; requests sorting by any other field are rejected with INVALID_ARGUMENT. */
+    /**
+     * Sort order for the result list.
+     *
+     * Supported `fieldName` values: `created_date` (snake_case, not auto-converted). At most 1 sort field is allowed.
+     */
     sort?: Sorting;
-    /** Optional paging. Offset-based. */
+    /** Offset-based paging. */
     paging?: Paging;
 }
 interface Sorting {
@@ -222,7 +249,7 @@ interface Paging {
     offset?: number | null;
 }
 interface ListPayoutsResponse {
-    /** List of payouts. */
+    /** List of retrieved payouts. */
     payouts?: Payout[];
     /** Paging metadata. */
     metadata?: PagingMetadata;
@@ -238,16 +265,17 @@ interface PagingMetadata {
     tooManyToCount?: boolean | null;
 }
 interface CreatePayoutRequest {
-    /** Payout. */
+    /** Payout to create. */
     payout?: Payout;
 }
 interface CreatePayoutResponse {
-    /** Payout. */
+    /** Created payout. */
     payout?: Payout;
 }
 interface GetPayoutRequest {
     /**
-     * ID of the Wix Payments account the payout belongs to.
+     * ID of the Wix Payments account that owns the payout. The payout must
+     * belong to this account. Retrieve account IDs from the Accounts API.
      * @format GUID
      */
     accountId: string;
@@ -258,12 +286,13 @@ interface GetPayoutRequest {
     payoutId: string;
 }
 interface GetPayoutResponse {
-    /** Payout. */
+    /** Retrieved payout. */
     payout?: Payout;
 }
 interface ListPayoutGroupsRequest {
     /**
-     * Wix Payments account identifier.
+     * ID of the Wix Payments account whose payout groups to list. Retrieve
+     * account IDs from the Accounts API.
      * @format GUID
      */
     accountId?: string;
@@ -311,7 +340,8 @@ interface PayoutGroup {
 }
 interface GetPayoutGroupRequest {
     /**
-     * Wix Payments account identifier.
+     * ID of the Wix Payments account that owns the payout group. Retrieve
+     * account IDs from the Accounts API.
      * @format GUID
      */
     accountId?: string;
@@ -333,12 +363,13 @@ interface GetPayoutGroupResponse {
 }
 interface GetPayoutGroupByPayoutIdRequest {
     /**
-     * Wix Payments account identifier.
+     * ID of the Wix Payments account that owns the payout. Retrieve account IDs
+     * from the Accounts API.
      * @format GUID
      */
     accountId?: string;
     /**
-     * Payout identifier.
+     * ID of the payout whose group to retrieve.
      * @format GUID
      */
     payoutId?: string;
@@ -560,10 +591,14 @@ interface PayoutCreatedEnvelope {
     metadata: EventMetadata;
 }
 /**
- * Emitted once when the payout is first persisted, before the underlying transfer
- * is initiated at the bank. At this point `status` is SENT and `estimated_arrival_date`
- * is set if the bank rail returned one; `failure_reason` and `bank_transfer_reference`
+ * Triggered when a payout is created.
+ *
+ * The payout is created before the underlying transfer is initiated at the
+ * bank. At this point `status` is `SENT` and `estimatedArrivalDateV2` is set
+ * if the bank rail returned one. `failureReason` and `bankTransferReference`
  * are not yet populated.
+ * @permissionScope View settlement reports and payouts
+ * @permissionScopeId SCOPE.PAYMENTS.PAYOUTS-VIEW-FOR-SITE
  * @permissionId PAYMENTS.PAYOUT_READ
  * @webhook
  * @eventType wix.payments.payouts.v4.payout_created
@@ -577,10 +612,14 @@ interface PayoutUpdatedEnvelope {
     metadata: EventMetadata;
 }
 /**
- * Emitted on every change to a persisted payout. Typical transitions include:
- * status moving from SENT to FAILED (and the corresponding `failure_reason` being set),
- * `estimated_arrival_date` being updated by the bank rail, and `bank_transfer_reference`
- * being populated once the rail returns it.
+ * Triggered when a payout is updated.
+ *
+ * Typical updates include `status` transitioning from `SENT` to `FAILED`
+ * (with `failureReason` being set), `estimatedArrivalDateV2` being refined by
+ * the bank rail, and `bankTransferReference` being populated once the rail
+ * returns it.
+ * @permissionScope View settlement reports and payouts
+ * @permissionScopeId SCOPE.PAYMENTS.PAYOUTS-VIEW-FOR-SITE
  * @permissionId PAYMENTS.PAYOUT_READ
  * @webhook
  * @eventType wix.payments.payouts.v4.payout_updated
@@ -590,42 +629,53 @@ interface PayoutUpdatedEnvelope {
  */
 declare function onPayoutUpdated(handler: (event: PayoutUpdatedEnvelope) => void | Promise<void>): void;
 /**
- * Retrieves a paginated list of payouts for the specified Wix Payments account,
- * with optional filters by profile and creation date.
- * @param accountId - ID of the Wix Payments account whose payouts to list.
+ * Retrieves a paginated list of payouts for the specified Wix Payments account.
+ *
+ * Supports optional filters by account profile and by creation date range.
+ * @param accountId - ID of the Wix Payments account whose payouts to list. Retrieve account
+ * IDs from the Accounts API.
  * @public
  * @documentationMaturity preview
  * @requiredField accountId
  * @permissionId PAYMENTS.PAYOUT_READ
+ * @applicableIdentity APP
  * @fqn wix.payments.v4.payouts.PayoutsService.ListPayouts
  */
 declare function listPayouts(accountId: string, options?: ListPayoutsOptions): Promise<NonNullablePaths<ListPayoutsResponse, `payouts` | `payouts.${number}._id` | `payouts.${number}.accountId` | `payouts.${number}.accountProfileId` | `payouts.${number}.amount.value` | `payouts.${number}.amount.currency` | `payouts.${number}.status` | `payouts.${number}.failureReason.code` | `payouts.${number}.cashAdvanceIncluded`, 5>>;
 interface ListPayoutsOptions {
     /**
-     * Optional. When omitted, payouts across all profiles of the account are returned.
-     * When set, only payouts belonging to the specified account profile are returned.
+     * ID of the Wix Payments account profile to filter by.
+     *
+     * When omitted, payouts across all profiles of the account are returned.
+     * Retrieve profile IDs from the Accounts API.
      * @format GUID
      */
     accountProfileId?: string | null;
-    /** Optional. Returns only payouts created before this timestamp. */
+    /** Returns only payouts created before this date and time. */
     createdBefore?: Date | null;
-    /** Optional. Returns only payouts created after this timestamp. */
+    /** Returns only payouts created after this date and time. */
     createdAfter?: Date | null;
-    /** Optional. Sorting. Only `created_date` is supported; requests sorting by any other field are rejected with INVALID_ARGUMENT. */
+    /**
+     * Sort order for the result list.
+     *
+     * Supported `fieldName` values: `created_date` (snake_case, not auto-converted). At most 1 sort field is allowed.
+     */
     sort?: Sorting;
-    /** Optional paging. Offset-based. */
+    /** Offset-based paging. */
     paging?: Paging;
 }
 /**
- * Retrieves a single payout by id.
+ * Retrieves a single payout by ID.
  * @param payoutId - ID of the payout to retrieve.
- * @param accountId - ID of the Wix Payments account the payout belongs to.
+ * @param accountId - ID of the Wix Payments account that owns the payout. The payout must
+ * belong to this account. Retrieve account IDs from the Accounts API.
  * @public
  * @documentationMaturity preview
  * @requiredField accountId
  * @requiredField payoutId
  * @permissionId PAYMENTS.PAYOUT_READ
- * @returns Payout.
+ * @applicableIdentity APP
+ * @returns Retrieved payout.
  * @fqn wix.payments.v4.payouts.PayoutsService.GetPayout
  */
 declare function getPayout(payoutId: string, accountId: string): Promise<NonNullablePaths<Payout, `_id` | `accountId` | `accountProfileId` | `amount.value` | `amount.currency` | `status` | `failureReason.code` | `cashAdvanceIncluded`, 3>>;