/** The refund object. A refund object is the record of an attempt to return charged funds. */ export interface Refund { /** * Refund ID. * @readonly */ _id?: string | null; /** * Revision number, which increments by 1 each time the refund is updated. * * Ignored when creating a refund. * @readonly */ revision?: string | null; /** * Date and time the refund was created in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#coordinated_Universal_Time_(UTC)) format. For example, "2024-01-30T13:30:00". * @readonly */ _createdDate?: Date | null; /** * Date and time the refund was last updated in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#coordinated_Universal_Time_(UTC)) format. For example, "2024-01-30T13:30:00". * @readonly */ _updatedDate?: Date | null; /** * Custom field data for the refund object. * * [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields) must be configured in the app dashboard before they can be accessed with API calls. */ extendedFields?: ExtendedFields; /** ID of the charge to refund. */ chargeId?: string | null; /** Refund currency. Should be the same as the charge currency. */ currency?: string | null; /** * Amount being returned to the buyer in the refund currency's main units (such as dollars or euros). * For example, `"12.95"`. */ amount?: string | null; /** * Application fee returned to the merchant from Wix in the refund currency's main units (such as dollars or euros). For example, `"12.95"`. * * Only included if an application fee was returned. * @readonly */ returnedApplicationFee?: string | null; /** * Processing fee returned to the merchant from the payment service provider in the refund currency's main units (such as dollars or euros). For example, `"12.95"`. * * This field is empty when the processing fee is unknown. * @readonly */ returnedProcessingFee?: string | null; /** * Whether the refund is for the entire amount of the charge. * @readonly */ full?: boolean | null; /** * Status of the refund. * * Learn more about the [refund lifecycle](https://dev.wix.com/docs/rest/business-management/payments/refunds/introduction#lifecycle-of-a-refund>). * @readonly */ status?: Status; /** * Payment service provider's ID for the refund. * @readonly */ providerRefundId?: string | null; /** Reason this refund was issued. */ reason?: string | null; /** * Details about the refund status. * Used to provide additional information about why a refund was given its status. * @readonly */ statusInfo?: StatusInfo; /** * Unique number assigned to a refund. This number is shared across all parties involved in processing the refund. It allows the merchant to track the refund with their bank. * @readonly */ acquirerReferenceNumber?: string | null; /** Note providing additional information about this refund. */ note?: string | null; } export interface ExtendedFields { /** * Extended field data. Each key corresponds to the namespace of the app that created the extended fields. * The value of each key is structured according to the schema defined when the extended fields were configured. * * You can only access fields for which you have the appropriate permissions. * * Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields). */ namespaces?: Record>; } export declare enum Status { UNKNOWN_STATUS = "UNKNOWN_STATUS", /** Refund was recently created. */ STARTING = "STARTING", /** Refund is being processed asynchronously. */ PENDING = "PENDING", /** Refund succeeded. */ SUCCEEDED = "SUCCEEDED", /** Refund failed. */ FAILED = "FAILED", /** Refund had succeeded, but has since been reversed. */ REVERSED = "REVERSED" } export declare enum Initiator { UNKNOWN_INITIATOR = "UNKNOWN_INITIATOR", WIX = "WIX", API = "API", PROVIDER = "PROVIDER" } export interface StatusInfo { /** * Reason code with detailed information about the refund status. * See the full list of [reason codes](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes#refund-declined). */ code?: string; /** Description of the status. */ description?: string | null; } export interface SyncRefundRequest { /** Refund ID. */ refundId?: string | null; /** ID of the refund on the PSP side. */ providerRefundId?: string | null; /** ID of charge for which the funds are returned by this refund. */ chargeId?: string | null; /** * Status of the refund. * Read more about statuses in this [article](). */ status?: Status; /** * Status code. * [Read more about reason codes.](https://dev.wix.com/docs/rest/api-reference/payment-provider-spi/reason-codes) */ statusCode?: string | null; /** Currency of refund, should be the same as currency of charge. */ currency?: string | null; /** * Amount of refund in base units, what's returned to the buyer. * E.g. "12.95". */ amount?: string | null; /** * Application fee returned to merchant from Wix. * Having this as a separate field since Refund.returned_application_fee is readOnly. */ returnedApplicationFee?: string | null; /** Reason why this refund was issued. */ reason?: string | null; /** Optional free-text note about this refund. */ note?: string | null; /** * Processing fee returned to merchant from Wix. * Having this as a separate field since Refund.returned_processing_fee is readOnly. */ returnedProcessingFee?: string | null; /** Unique number assigned to a refund. This number is shared across all parties involved in processing the refund. It allows the merchant to track the refund with their bank. */ acquirerReferenceNumber?: string | null; } export interface SyncRefundResponse { /** Created/updated refund. */ refund?: Refund; } export interface CreateRefundRequest { /** Refund to be created. */ refund: Refund; /** * Amount of the charge that was previously refunded. * * Specify this to compare your records of previously refunded amounts against those on the server. If they don't match, this method will return an error with the code `PREVIOUSLY_REFUNDED_AMOUNT_MISMATCH`. * * Learn more about [preventing unintended refunds](https://dev.wix.com/docs/rest/business-management/payments/refunds/introduction#preventing-unintended-refunds). */ previouslyRefundedAmount?: string | null; } export interface CreateRefundResponse { /** The created refund. */ refund?: Refund; } export interface GetRefundRequest { /** ID of the refund to retrieve. */ refundId: string; } export interface GetRefundResponse { /** The requested refund. */ refund?: Refund; } export interface QueryRefundsRequest { /** Query options. */ query?: CursorQuery; } export interface CursorQuery extends CursorQueryPagingMethodOneOf { /** Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. */ cursorPaging?: CursorPaging; /** * Filter object in the following format: * `"filter" : { * "fieldName1": "value1", * "fieldName2":{"$operator":"value2"} * }` * Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` */ filter?: Record | null; /** * Sort object in the following format: * `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` */ sort?: Sorting[]; } /** @oneof */ export interface CursorQueryPagingMethodOneOf { /** Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. */ cursorPaging?: CursorPaging; } export interface Sorting { /** Name of the field to sort by. */ fieldName?: string; /** Sort order. */ order?: SortOrder; } export declare enum SortOrder { ASC = "ASC", DESC = "DESC" } export interface CursorPaging { /** Number of items to load. */ limit?: number | null; /** * Pointer to the next or previous page in the list of results. * * You can get the relevant cursor token * from the `pagingMetadata` object in the previous call's response. * Not relevant for the first request. */ cursor?: string | null; } export interface QueryRefundsResponse { /** List of refunds. */ refunds?: Refund[]; /** Metadata for the paginated results. */ pagingMetadata?: CursorPagingMetadata; } export interface CursorPagingMetadata { /** Number of items returned in the response. */ count?: number | null; /** Offset that was requested. */ cursors?: Cursors; /** * Indicates if there are more results after the current page. * If `true`, another page of results can be retrieved. * If `false`, this is the last page. */ hasNext?: boolean | null; } export interface Cursors { /** Cursor pointing to next page in the list of results. */ next?: string | null; /** Cursor pointing to previous page in the list of results. */ prev?: string | null; } export interface UpdateExtendedFieldsRequest { /** ID of the entity to update. */ _id: string; /** Identifier for the app whose extended fields are being updated. */ namespace: string; /** Data to update. Structured according to the [schema](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields#json-schema-for-extended-fields) defined when the extended fields were configured. */ namespaceData: Record | null; } export interface UpdateExtendedFieldsResponse { /** Updated refund. */ refund?: Refund; } export interface GetRefundabilityRequest { /** ID of the charge to calculate refundability for. */ chargeId: string; } export interface GetRefundabilityResponse { /** Refundability of the charge. */ refundability?: Refundability; } /** * Internal notes: * * Instead of separate Refundability and PartialRefundability, we provide min and max refund amount. * If only full refund is possible, min_refund_amount = max_refund_amount = charge amount. */ export interface Refundability extends RefundabilityDetailsOneOf { /** When the charge is refundable, specifies the allowed range for the refund amount. */ refundDetails?: RefundDetails; /** When charge is not refundable, specifies why the refund is not allowed. */ rejectionDetails?: RejectionDetails; /** Whether you can refund the charge. This depends on your app's permissions, and the permissions of the user checking the refundability. */ refundable?: boolean; /** Charge currency. */ currency?: string | null; /** * Sum of amounts of previous refunds for this charge with the `SUCCEEDED` status in the charge currency's main units (such as dollars or euros). For example, `"6.47"`. * Used to [prevent unintended refunds](https://dev.wix.com/docs/rest/business-management/payments/refunds/introduction#preventing-unintended-refunds). */ previouslyRefundedAmount?: string | null; } /** @oneof */ export interface RefundabilityDetailsOneOf { /** When the charge is refundable, specifies the allowed range for the refund amount. */ refundDetails?: RefundDetails; /** When charge is not refundable, specifies why the refund is not allowed. */ rejectionDetails?: RejectionDetails; } export interface RefundDetails { /** Minimum allowed refund amount in the refund currency's main units (such as dollars or euros). For example, `"0.50"`. */ minRefundAmount?: string | null; /** Maximum allowed refund amount in the refund currency's main units (such as dollars or euros). For example, `"12.95"`. */ maxRefundAmount?: string | null; } export interface RejectionDetails { /** Reason the refund was rejected. */ reason?: RejectionReason; } export declare enum RejectionReason { UNKNOWN_REJECTION_REASON = "UNKNOWN_REJECTION_REASON", /** Charge was fully refunded. */ CHARGE_REFUNDED = "CHARGE_REFUNDED", /** Another refund was initiated for this charge and is waiting for confirmation from the provider. */ CHARGE_REFUND_IN_PROGRESS = "CHARGE_REFUND_IN_PROGRESS", /** Charge was disputed. */ CHARGE_DISPUTED = "CHARGE_DISPUTED", /** Charge is too old to be refunded. */ CHARGE_REFUND_PERIOD_ENDED = "CHARGE_REFUND_PERIOD_ENDED", /** Charge is unpaid. */ CHARGE_UNPAID = "CHARGE_UNPAID", /** PSP is temporarily unavailable. */ PROVIDER_DOWN = "PROVIDER_DOWN", /** * PSP doesn't support the refund for one of the following reasons: * - The PSP doesn't currently support refunds. * - The charge is in an invalid state. * - The PSP does not have the required information for this transaction. */ PROVIDER_NOT_SUPPORTED = "PROVIDER_NOT_SUPPORTED", /** Payment method used for the charge doesn't support refunds. */ PAYMENT_METHOD_NOT_SUPPORTED = "PAYMENT_METHOD_NOT_SUPPORTED", /** Merchant account doesn't currently support refunds. */ MERCHANT_ACCOUNT_NOT_SUPPORTED = "MERCHANT_ACCOUNT_NOT_SUPPORTED", /** Merchant doesn't have enough balance to issue a refund for the charge. */ MERCHANT_BALANCE_INSUFFICIENT = "MERCHANT_BALANCE_INSUFFICIENT", /** The identity requesting the refund doesn't have the required permissions. This can occur if a site collaborator attempts to create a refund on behalf of the merchant. */ NOT_AUTHORIZED = "NOT_AUTHORIZED" } export interface DomainEvent extends DomainEventBodyOneOf { createdEvent?: EntityCreatedEvent; updatedEvent?: EntityUpdatedEvent; deletedEvent?: EntityDeletedEvent; actionEvent?: ActionEvent; /** * Unique event ID. * Allows clients to ignore duplicate webhooks. */ _id?: string; /** * Assumes actions are also always typed to an entity_type * Example: wix.stores.catalog.product, wix.bookings.session, wix.payments.transaction */ entityFqdn?: string; /** * This is top level to ease client code dispatching of messages (switch on entity_fqdn+slug) * This is although the created/updated/deleted notion is duplication of the oneof types * Example: created/updated/deleted/started/completed/email_opened */ slug?: string; /** ID of the entity associated with the event. */ entityId?: string; /** Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example: 2020-04-26T13:57:50.699Z */ eventTime?: Date | null; /** * Whether the event was triggered as a result of a privacy regulation application * (for example, GDPR). */ triggeredByAnonymizeRequest?: boolean | null; /** If present, indicates the action that triggered the event. */ originatedFrom?: string | null; /** * A sequence number defining the order of updates to the underlying entity. * For example, given that some entity was updated at 16:00 and than again at 16:01, * it is guaranteed that the sequence number of the second update is strictly higher than the first. * As the consumer, you can use this value to ensure that you handle messages in the correct order. * To do so, you will need to persist this number on your end, and compare the sequence number from the * message against the one you have stored. Given that the stored number is higher, you should ignore the message. */ entityEventSequence?: string | null; } /** @oneof */ export interface DomainEventBodyOneOf { createdEvent?: EntityCreatedEvent; updatedEvent?: EntityUpdatedEvent; deletedEvent?: EntityDeletedEvent; actionEvent?: ActionEvent; } export interface EntityCreatedEvent { entity?: string; } export interface RestoreInfo { deletedDate?: Date | null; } export interface EntityUpdatedEvent { /** * Since platformized APIs only expose PATCH and not PUT we can't assume that the fields sent from the client are the actual diff. * This means that to generate a list of changed fields (as opposed to sent fields) one needs to traverse both objects. * We don't want to impose this on all developers and so we leave this traversal to the notification recipients which need it. */ currentEntity?: string; } export interface EntityDeletedEvent { /** Entity that was deleted */ deletedEntity?: string | null; } export interface ActionEvent { body?: string; } export interface MessageEnvelope { /** App instance ID. */ instanceId?: string | null; /** Event type. */ eventType?: string; /** The identification type and identity data. */ identity?: IdentificationData; /** Stringify payload. */ data?: string; } export interface IdentificationData extends IdentificationDataIdOneOf { /** ID of a site visitor that has not logged in to the site. */ anonymousVisitorId?: string; /** ID of a site visitor that has logged in to the site. */ memberId?: string; /** ID of a Wix user (site owner, contributor, etc.). */ wixUserId?: string; /** ID of an app. */ appId?: string; /** @readonly */ identityType?: WebhookIdentityType; } /** @oneof */ export interface IdentificationDataIdOneOf { /** ID of a site visitor that has not logged in to the site. */ anonymousVisitorId?: string; /** ID of a site visitor that has logged in to the site. */ memberId?: string; /** ID of a Wix user (site owner, contributor, etc.). */ wixUserId?: string; /** ID of an app. */ appId?: string; } export declare enum WebhookIdentityType { UNKNOWN = "UNKNOWN", ANONYMOUS_VISITOR = "ANONYMOUS_VISITOR", MEMBER = "MEMBER", WIX_USER = "WIX_USER", APP = "APP" } interface StatusInfoNonNullableFields { code: string; } export interface RefundNonNullableFields { status: Status; initiator: Initiator; statusInfo?: StatusInfoNonNullableFields; } export interface CreateRefundResponseNonNullableFields { refund?: RefundNonNullableFields; } export interface GetRefundResponseNonNullableFields { refund?: RefundNonNullableFields; } export interface QueryRefundsResponseNonNullableFields { refunds: RefundNonNullableFields[]; } export interface UpdateExtendedFieldsResponseNonNullableFields { refund?: RefundNonNullableFields; } interface RejectionDetailsNonNullableFields { reason: RejectionReason; } interface RefundabilityNonNullableFields { rejectionDetails?: RejectionDetailsNonNullableFields; refundable: boolean; } export interface GetRefundabilityResponseNonNullableFields { refundability?: RefundabilityNonNullableFields; } export interface BaseEventMetadata { /** App instance ID. */ instanceId?: string | null; /** Event type. */ eventType?: string; /** The identification type and identity data. */ identity?: IdentificationData; } export interface EventMetadata extends BaseEventMetadata { /** * Unique event ID. * Allows clients to ignore duplicate webhooks. */ _id?: string; /** * Assumes actions are also always typed to an entity_type * Example: wix.stores.catalog.product, wix.bookings.session, wix.payments.transaction */ entityFqdn?: string; /** * This is top level to ease client code dispatching of messages (switch on entity_fqdn+slug) * This is although the created/updated/deleted notion is duplication of the oneof types * Example: created/updated/deleted/started/completed/email_opened */ slug?: string; /** ID of the entity associated with the event. */ entityId?: string; /** Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example: 2020-04-26T13:57:50.699Z */ eventTime?: Date | null; /** * Whether the event was triggered as a result of a privacy regulation application * (for example, GDPR). */ triggeredByAnonymizeRequest?: boolean | null; /** If present, indicates the action that triggered the event. */ originatedFrom?: string | null; /** * A sequence number defining the order of updates to the underlying entity. * For example, given that some entity was updated at 16:00 and than again at 16:01, * it is guaranteed that the sequence number of the second update is strictly higher than the first. * As the consumer, you can use this value to ensure that you handle messages in the correct order. * To do so, you will need to persist this number on your end, and compare the sequence number from the * message against the one you have stored. Given that the stored number is higher, you should ignore the message. */ entityEventSequence?: string | null; } export interface RefundCreatedEnvelope { entity: Refund; metadata: EventMetadata; } /** @permissionId PAYMENTS.REFUND_READ * @webhook * @eventType wix.payments.refunds.v1.refund_created * @documentationMaturity preview */ export declare function onRefundCreated(handler: (event: RefundCreatedEnvelope) => void | Promise): void; export interface RefundUpdatedEnvelope { entity: Refund; metadata: EventMetadata; } /** @permissionId PAYMENTS.REFUND_READ * @webhook * @eventType wix.payments.refunds.v1.refund_updated * @documentationMaturity preview */ export declare function onRefundUpdated(handler: (event: RefundUpdatedEnvelope) => void | Promise): void; /** * Creates a refund. * * The refunding process starts immediately after a refund entity is created. * * If you specify an `amount`, you must also specify a `currency`. This currency should be the same as the currency of the charge. * If `amount` and `currency` are not specified, the refund is created for the full charge amount. If the charge was already partially refunded, this refund will fail. * * The refund is initially created with a status of `STARTING`. However, the call does not return a response until the refund status transitions away from `STARTING`. Lean more about the [refund lifecycle](https://dev.wix.com/docs/rest/business-management/payments/refunds/introduction#refund-lifecycle). * @param refund - Refund to be created. * @public * @documentationMaturity preview * @requiredField refund * @requiredField refund.chargeId * @permissionId PAYMENTS.REFUND_CREATE * @returns The created refund. * @fqn wix.payments.refunds.v1.RefundService.CreateRefund */ export declare function createRefund(refund: Refund, options?: CreateRefundOptions): Promise; export interface CreateRefundOptions { /** * Amount of the charge that was previously refunded. * * Specify this to compare your records of previously refunded amounts against those on the server. If they don't match, this method will return an error with the code `PREVIOUSLY_REFUNDED_AMOUNT_MISMATCH`. * * Learn more about [preventing unintended refunds](https://dev.wix.com/docs/rest/business-management/payments/refunds/introduction#preventing-unintended-refunds). */ previouslyRefundedAmount?: string | null; } /** * Retrieves a refund. * @param refundId - ID of the refund to retrieve. * @public * @documentationMaturity preview * @requiredField refundId * @permissionId PAYMENTS.REFUND_READ * @returns The requested refund. * @fqn wix.payments.refunds.v1.RefundService.GetRefund */ export declare function getRefund(refundId: string): Promise; /** * Retrieves a list of refunds given the provided paging, filtering, and sorting. Up to 100 Refunds can be returned per request. * * For a detailed list of supported operations, see the [Sorting and Filtering](https://dev.wix.com/docs/rest/business-management/payments/refunds/sorting-and-filtering) article. * To learn how to query refunds, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). * @public * @documentationMaturity preview * @permissionId PAYMENTS.REFUND_READ * @fqn wix.payments.refunds.v1.RefundService.QueryRefunds */ export declare function queryRefunds(): RefundsQueryBuilder; interface QueryCursorResult { cursors: Cursors; hasNext: () => boolean; hasPrev: () => boolean; length: number; pageSize: number; } export interface RefundsQueryResult extends QueryCursorResult { items: Refund[]; query: RefundsQueryBuilder; next: () => Promise; prev: () => Promise; } export interface RefundsQueryBuilder { /** @param propertyName - Property whose value is compared with `value`. * @param value - Value to compare against. * @documentationMaturity preview */ eq: (propertyName: 'chargeId', value: any) => RefundsQueryBuilder; /** @documentationMaturity preview */ in: (propertyName: 'chargeId', value: any) => RefundsQueryBuilder; /** @param propertyNames - Properties used in the sort. To sort by multiple properties, pass properties as additional arguments. * @documentationMaturity preview */ ascending: (...propertyNames: Array<'_createdDate'>) => RefundsQueryBuilder; /** @param propertyNames - Properties used in the sort. To sort by multiple properties, pass properties as additional arguments. * @documentationMaturity preview */ descending: (...propertyNames: Array<'_createdDate'>) => RefundsQueryBuilder; /** @param limit - Number of items to return, which is also the `pageSize` of the results object. * @documentationMaturity preview */ limit: (limit: number) => RefundsQueryBuilder; /** @param cursor - A pointer to specific record * @documentationMaturity preview */ skipTo: (cursor: string) => RefundsQueryBuilder; /** @documentationMaturity preview */ find: () => Promise; } /** * Updates the extended fields of a refund without incrementing the revision number. * @param _id - ID of the entity to update. * @param namespace - Identifier for the app whose extended fields are being updated. * @public * @documentationMaturity preview * @requiredField _id * @requiredField namespace * @requiredField options * @requiredField options.namespaceData * @permissionId PAYMENTS.REFUND_UPDATE * @fqn wix.payments.refunds.v1.RefundService.UpdateExtendedFields */ export declare function updateExtendedFields(_id: string, namespace: string, options: UpdateExtendedFieldsOptions): Promise; export interface UpdateExtendedFieldsOptions { /** Data to update. Structured according to the [schema](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields#json-schema-for-extended-fields) defined when the extended fields were configured. */ namespaceData: Record | null; } /** * Calculates the refundability of a charge. * * Learn more about [refundability](https://dev.wix.com/docs/rest/business-management/payments/refunds/introduction#refundability). * @param chargeId - ID of the charge to calculate refundability for. * @public * @documentationMaturity preview * @requiredField chargeId * @permissionId PAYMENTS.REFUND_GET_REFUNDABILITY * @fqn wix.payments.refunds.v1.RefundService.GetRefundability */ export declare function getRefundability(chargeId: string): Promise; export {};